LangChain 1.3 安装与使用指南 —— 从"链"到 Agent Harness 的全新范式

2026 年 8 月 25 日，LangChain 发布 1.3.17。如今的 LangChain 早已不是当年那个”Prompt + LLM + Output Parser 串链子”的框架——1.x 时代的核心是一句话：Agent = Model + Harness。官方提供 create_agent：一个极简、高度可配置的 Agent 运行时，你只需要模型、工具和系统提示词，10 行代码就能跑起一个能调用工具的 Agent。

本文基于官方文档与 Quickstart，带你从零安装、10 行代码上手，再到工具、记忆、Deep Agents、LangGraph、LangSmith 的完整进阶路径。

一、先搞清楚生态全景

LangChain 已经不是”一个库”，而是一整套 LLM 应用生态。装之前先认清楚各司其职：

flowchart TB
    subgraph LC[LangChain 1.x 核心]
        A1[langchain · create_agent 高层 Agent]
        A2[langchain-core · 抽象基座]
        A3[langchain.chat_models.init_chat_model · 统一模型接口]
    end
    subgraph INT[集成包 · 按需安装]
        B1[langchain-openai / anthropic / google-genai]
        B2[langchain-ollama / aws / fireworks]
        B3[langchain-openrouter / huggingface / baseten]
    end
    subgraph LG[LangGraph · 低层编排]
        C1[持久化执行 durable execution]
        C2[人工介入 human-in-the-loop]
        C3[状态图 StateGraph]
    end
    subgraph DA[Deep Agents]
        D1[内置规划 / 虚拟文件系统 / 子代理]
    end
    subgraph LS[LangSmith · 可观测与评估]
        E1[Trace 追踪]
        E2[LangSmith Engine · 自动发现问题]
        E3[LangSmith Gateway · 模型网关]
    end
    LC --- INT
    LC --> LG
    LG --> DA
    LC --> LS

选择指南：

层	用途	什么时候用
LangChain（`create_agent`）	高度可定制的高层 Agent 框架	大部分场景的起点，按需组合
Deep Agents（`deepagents`）	开箱即用的完整 Agent	要”最大能力、最少配置”：自动上下文压缩、虚拟文件系统、子代理
LangGraph	低层编排运行时	需要确定性 + Agentic 混合工作流、精确控制延迟
LangSmith	追踪、调试、评估、监控	任何框架都要配，生产必备

二、安装

2.1 环境要求

Python 3.x（pip / uv 均可）
一个模型提供方的 API Key（OpenAI / Anthropic / Google / 本地 Ollama 等）

2.2 三种安装方式

# 方式一：uv（官方推荐，最新版 1.3.17 安装最快）
uv init
uv add langchain
uv sync

# 方式二：pip
pip install -U langchain

# 方式三：venv 虚拟环境
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -U langchain

2.3 按需安装集成包

LangChain 1.x 把提供商集成拆成了独立包，用到哪个装哪个：

pip install -U langchain "langchain[openai]"        # OpenAI
pip install -U langchain "langchain[anthropic]"     # Claude
pip install -U langchain "langchain[google-genai]"  # Gemini
pip install -U langchain langchain-ollama           # 本地 Ollama
pip install -U langchain langchain-aws              # AWS Bedrock
pip install -U langchain langchain-fireworks        # Fireworks
pip install -U langchain langchain-openrouter       # OpenRouter
pip install -U langchain "langchain[huggingface]"   # HuggingFace

要用 Deep Agents 再装一个：

pip install -U deepagents

2.4 验证安装

python -c "import langchain; print(langchain.__version__)"
# 1.3.17

三、快速上手：10 行代码创建第一个 Agent

设置 API Key（以 OpenAI 为例）：

export OPENAI_API_KEY="your-api-key"

创建一个带天气工具的 Agent：

from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
)
print(result["messages"][-1].content_blocks)

关键点：

create_agent(model, tools, system_prompt) 就是全部入口；
模型字符串格式：provider:model，例如 openai:gpt-5.5、google_genai:gemini-2.5-flash-lite、claude-sonnet-4-6、ollama:devstral-2、bedrock_converse:us.anthropic.claude-sonnet-4-6、huggingface:microsoft/Phi-3-mini-4k-instruct；
普通 Python 函数直接作为工具传入即可，函数签名和 docstring 会自动变成模型看到的工具定义。

执行流程：

sequenceDiagram
    participant U as 用户
    participant A as create_agent
    participant M as 模型
    participant T as 工具（get_weather）
    participant K as 记忆（checkpointer）
    U->>A: invoke 消息
    A->>M: 模型循环（system + 历史 + 工具定义）
    M->>A: 请求调用 get_weather(city)
    A->>T: 执行工具
    T-->>A: 返回结果
    A->>M: 回填工具结果
    M-->>A: 最终回复
    A->>K: 持久化会话状态
    A-->>U: 输出

四、进阶使用

4.1 统一模型接口：init_chat_model

换模型只需改一行字符串，参数保持统一：

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "openai:gpt-5.5",          # 或 "claude-sonnet-4-6" / "gemini-3.1-pro-preview"...
    temperature=0.5,
    timeout=300,
    max_tokens=25000,
    streaming=True,            # 部分 provider 支持
)

特殊场景用 model_provider 显式指定（如 model_provider="bedrock_converse"、model_provider="huggingface"）；Azure 还需 azure_deployment=... 参数。

4.2 工具系统：@tool 与运行时注入

from langchain.tools import tool

@tool
def fetch_text_from_url(url: str) -> str:
    """Fetch the document from a URL."""
    ...

工具的名称、描述、参数名都会进入模型的 prompt，写清楚 docstring 就是最好的工具文档；
@tool 装饰器支持 ToolRuntime 参数注入——工具可以访问运行时上下文和 Agent 记忆；
结构化输出、guardrails、重试、路由都可以通过中间件（middleware）增量叠加到 harness 上。

4.3 记忆与状态：checkpointer

Agent 默认是无状态的；要跨轮对话记住上下文，用 checkpointer：

from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    tools=[fetch_text_from_url],
    system_prompt=SYSTEM_PROMPT,
    checkpointer=checkpointer,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "..."}]},
    config={"configurable": {"thread_id": "my-thread"}},
)

生产环境不要用 InMemorySaver，换成持久化 checkpointer（数据库存消息历史）。thread_id 是会话标识，同一个 thread 的多次 invoke 共享上下文。

4.4 LangChain Agent vs Deep Agent：怎么选？

两者都给你工具/记忆/提示词的精细控制，区别在于Deep Agent 内置了一堆常用能力：任务规划（write_todos）、虚拟文件系统（grep / read_file / 大结果自动落盘）、子代理。

官方 Quickstart 用《了不起的盖茨比》文本做了一个真实对比：

任务	LangChain Agent	Deep Agent
统计含 “Gatsby” 的行数	`null`（无计算工具，拒绝瞎编 ✅）	258 行（用 grep 精确统计）
第一个含 “Daisy” 的行号	`null`	第 181 行
工具策略	只调了 fetch 工具，大文本塞进上下文	自动落盘 → grep → read_file → 精确验证

结论：Deep Agent 适合”最大能力、最少配置”——规划、文件系统、子代理开箱即用；LangChain Agent 适合”精细控制”——自己决定每一步的中间件和工具策略。

flowchart TD
    A[我的需求] --> B{需要什么？}
    B -->|最大能力 · 最少配置| C[Deep Agent<br>create_deep_agent]
    B -->|精细控制 · 自定义中间件| D[LangChain Agent<br>create_agent]
    B -->|确定性+Agentic 混合工作流| E[LangGraph<br>StateGraph]
    C --> F[LangSmith 追踪/评估]
    D --> F
    E --> F

4.5 LangGraph：低层编排

需要把确定性流程（如固定顺序的数据管道）与 Agentic 行为混合时，直接用 LangGraph：

StateGraph：显式定义状态与节点迁移；
durable execution：任务中断/重启后恢复；
human-in-the-loop：关键节点插入人工审批；
LangChain Agent 本身就是基于 LangGraph 构建的，所以天然继承这些能力（持久化、流式、人工介入），只是把复杂度藏起来了。

4.6 测试与生产：LangSmith

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."

Trace：每个 LLM 调用、工具调用、状态迁移、延迟一目了然；
LangSmith Engine：持续监控 trace，自动发现问题并给出修复建议；
LangSmith Gateway：一个网关路由大多数主流 provider，可用 Gateway Credits 免 provider key 调模型；
部署：LangGraph 应用可直接 langgraph deploy 到生产。

五、常见问题

问题	解决
`ModuleNotFoundError: langchain_openai`	没装集成包，`pip install "langchain[openai]"`
模型名不认识	检查 `provider:model` 前缀格式；provider 特有 ID 查集成包参考文档
Ollama 连接失败	先 `ollama serve`，模型名用 `ollama:<model>`
401 错误	确认对应环境变量（`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GOOGLE_API_KEY`…）
大文本塞爆上下文	换 Deep Agent（自动落盘 + grep），或给 Agent 加文件系统工具
会话不记得上下文	加 checkpointer + `thread_id`

六、总结

LangChain 1.3 的安装和使用比以往任何版本都简单：

装：pip install -U langchain + 按需集成包；
跑：create_agent(model, tools, system_prompt) 十行代码出 Agent；
进阶：init_chat_model 统一换模型、@tool 扩展能力、checkpointer 加记忆；
选型：要省事用 Deep Agents，要精细用 LangChain Agent，要混合编排上 LangGraph；
上线：LangSmith 追踪 + Engine 监控 + Gateway 网关 + langgraph deploy。

给 AI 编码助手用户的彩蛋：官方提供了 LangChain Docs MCP Server（让 Claude 等助手实时查文档）和 LangChain Skills（提升在 LangChain 生态上的任务表现），写代码时直接接上。

~/blog