LangChain v1 重大更新讲解⚠⚠⚠

LangChain v1 重大更新讲解

为什么没有先发布demo教学而是先发布一个什么重大更新

因为langchain更新了，更新还挺多的所以建议大家还是从新版本开始学习

作者：吴佳浩

最后更新：2025-11-22

适用版本：LangChain v1.0+

0. 环境准备

在开始之前，请确保 Python 版本 ≥ 3.9，并安装以下核心包：

1# 安装 v1 核心包、经典兼容包和图运行时
2pip install -U langchain langchain-classic langgraph
3
4# 安装适配的模型提供商包 (以 OpenAI 为例)
5pip install -U langchain-openai
6

一、LangChain v1 为什么是一次“大版本革命”？

LangChain v1 不再仅仅是一个“LLM 调用工具箱”，而是正式转向构建生产级 Agent 系统的工程框架。

核心变化包括：

create_agent：正式成为 Agent 的标准构建方式（底层基于 LangGraph）。
Middleware (中间件)：允许在任意阶段（模型调用前、工具执行时、输出后）拦截并修改逻辑。
content_blocks：所有模型输出（推理/文本/工具调用）统一为标准格式，不再依赖正则解析。
结构化输出：Pydantic Schema 成为一等公民，极大提升稳定性。
命名空间拆分：旧 API（如 Chains）全部迁入 langchain-classic，主包只保留 Agent 核心。

二、v0.1 → v1.0：差异对照表（核心必读）

这是理解 v1 最重要的一张表，展示了从“脚本思维”到“工程思维”的转变。

项目	LangChain v0.x (旧版)	LangChain v1.0 (新版)	核心差异
中心思想	Chains (链式调用)	Agents (智能体)	从线性执行转向循环图执行 (Graph)
构建入口	initialize_agent	create_agent	统一的新标准接口
底层引擎	AgentExecutor (硬编码循环)	LangGraph	支持持久化、流式、分支、循环的图运行时
流式能力	部分支持 (Token级)	全链路流式	支持 Token、中间步骤、推理过程的实时流
扩展机制	无 (需修改源码或Prompt)	Middleware	完整的生命周期钩子 (Hooks)
工具定义	Tool + func	Tool + Pydantic Schema	类型更安全，参数定义更清晰
结构化输出	JSON Parser + Regex	Structured Output	直接绑定 Pydantic 类，由模型底层保证格式
输出解析	纯文本 + 正则匹配	content_blocks	标准化对象 (推理块、文本块、工具块)
包管理	langchain.*	langchain-classic	旧功能移至 classic 包，保持主包轻量

三、LangChain v1 架构总览

💡 核心提示：LangChain v1 的底层引擎实际上是 LangGraph。create_agent 本质上是为你预构建了一个标准的 LangGraph 图。

1flowchart TD
2    subgraph AgentRuntime ["LangGraph 运行时"]
3        direction TB
4        A["用户输入 (Messages)"] --> B[" 模型推理 (LLM)"]
5        B --> C{"决策节点"}
6        C -->|需要工具| D[" 工具执行 (Tool Execution)"]
7        D --> E[" 工具结果反馈"]
8        E --> B
9        C -->|无需工具/结束| F[" 生成最终回答"]
10    end
11    
12    style A fill:#e1f5fe,stroke:#01579b
13    style B fill:#fff9c4,stroke:#fbc02d
14    style D fill:#e8f5e9,stroke:#2e7d32
15

四、create_agent：全新的 Agent 创建方式

为什么废弃 initialize_agent？

因为 v1 统一使用图架构（Graph Architecture）。所有的 Agent 本质上都是：推理 → 工具 → 再推理的循环。create_agent 是这个标准循环的工厂函数。

基本用法：

1from langchain.agents import create_agent
2from langchain_openai import ChatOpenAI
3
4# 1. 定义模型
5model = ChatOpenAI(model="gpt-4o")
6
7# 2. 创建 Agent
8agent = create_agent(
9    model=model,
10    tools=[search_tool, calculator_tool],
11    system_prompt="你是一个乐于助人的金融分析师。"
12)
13
14# 3. 运行 (Invoke)
15result = agent.invoke({"messages": [{"role": "user", "content": "分析 AAPL 股价"}]})
16

五、Middleware：核心扩展机制（洋葱模型）

中间件是 v1 最强大的功能，允许你在 Agent 生命周期的任意节点插入逻辑（如鉴权、日志、路由）。

生命周期时序图：

1sequenceDiagram
2    participant User
3    participant MW as Middleware (中间件层)
4    participant Agent as Agent Runtime
5    participant Model as LLM
6
7    User->>Agent: invoke(input)
8    Agent->>MW: 1. before_agent_start
9    MW-->>Agent: (清洗后的输入)
10
11    loop 思考与执行循环
12        Agent->>MW: 2. before_model
13        Note right of MW: 动态修改 Prompt / 路由模型
14        
15        rect rgb(240,240,240)
16            MW->>Model: 3. wrap_model_call
17            Model-->>MW: 返回原始结果
18        end
19        
20        MW-->>Agent: 4. after_model (校验输出)
21
22        opt 工具调用
23            Agent->>MW: 5. wrap_tool_call
24            Note right of MW: 敏感操作审批 / 审计
25            MW-->>Agent: 工具结果
26        end
27    end
28
29    Agent->>MW: 6. after_agent
30    MW-->>User: 最终响应
31

六、content_blocks：跨模型统一输出

解决“不同模型返回格式不同”的痛点。

模型输出现在包含统一的 .content_blocks 属性：

reasoning: 模型的思考过程（如 Chain of Thought）。
tool_call: 结构化的工具调用请求。
text: 最终回复文本。

七、结构化输出（Structured Output）

v1 推荐使用 Pydantic Schema 来强制模型输出特定格式，而不是在 Prompt 里写“请返回 JSON”。

三种策略：

SchemaBasedStructurer (推荐)：直接传入 Pydantic 类。
ToolStrategy：利用 Tool Calling 机制输出结构。
ProviderStrategy：利用模型原生 JSON Mode（如 OpenAI JSON Object）。

八、命名空间重构 + langchain-classic

为了给 Agent 让路，旧的“链式”组件被移入 classic 包。

迁移对照：

组件	旧引入方式	v1 新引入方式
Memory	from langchain.memory import ...	from langchain_classic.memory import ...
Chains	from langchain.chains import ...	from langchain_classic.chains import ...
Retrievers	from langchain.retrievers import ...	from langchain_classic.retrievers import ...

🛠 九、v0 → v1 迁移指南（实战版）

1. ConversationChain → create_agent

❌ 旧 (v0)：

1from langchain.chains import ConversationChain  
2chain = ConversationChain(llm=llm)  
3chain.run("Hi")

✔ 新 (v1)：

1from langchain.agents import create_agent  
2# create_agent 自带记忆管理 (通过 LangGraph checkpoint)  
3agent = create_agent(model=llm, tools=[])  
4agent.invoke({"messages": [...]})

2. LLMChain → model.invoke

❌ 旧 (v0)：

1chain = LLMChain(prompt=prompt, llm=llm)  
2chain.run(variable="value")

✔ 新 (v1)：

1# 直接使用 LCEL (LangChain Expression Language)  
2chain = prompt | llm  
3chain.invoke({"variable": "value"})

3. Tool 定义方式

❌ 旧 (v0)：依赖 func 和文档字符串解析。
✔ 新 (v1)：强烈建议使用 @tool 装饰器并配合 Pydantic 类型的参数注解，或者使用 create_tool(schema=MySchema)。

十、推荐的生产级项目结构图

在 v1 时代，推荐采用分层架构来管理 Agent 项目：

1graph TD
2  Root[" my_agent_project/"] --> A[" app/"]
3  
4  A --> B[" agent.py <br/> (create_agent 组装入口)"]
5  
6  A --> C["middleware/ <br/> (中间件层)"]
7  C --> C1[" auth_middleware.py"]
8  C --> C2[" risk_control.py"]
9  
10  A --> D[" schemas/ <br/> (数据结构)"]
11  D --> D1[" user_context.py"]
12  D --> D2[" output_schema.py"]
13  
14  A --> E[" tools/ <br/> (工具集)"]
15  E --> E1[" search_tool.py"]
16  E --> E2[" db_tool.py"]
17  
18  A --> F[" main.py <br/> (FastAPI/Streamlit 入口)"]
19

十一、真实企业级案例：多步骤任务 Agent

场景：自动代码修复 Agent。

流程：写代码 → 运行测试 → 失败则分析日志 → 修复代码 → 循环直至成功。

1flowchart TD
2    Start(("开始")) --> Gen["生成初版代码"]
3    Gen --> Run["🔧 工具: 运行代码/测试"]
4    Run --> Check{"测试通过?"}
5    
6    Check -->|失败| Debug[" LLM: 分析错误日志"]
7    Debug --> Gen
8    
9    Check -->|成功| Output["输出最终代码"]
10    Output --> End(("结束"))
11

这在 v1 中通过 createagent 天然支持，因为底层 Graph 支持循环，且可以通过中间件记录每次尝试的详细日志。

十二、可运行综合示例代码

这是一个包含了 中间件 (Middleware) 和 结构化输出 的完整 v1 示例。

1import asyncio
2from typing import Any, Dict
3from pydantic import BaseModel, Field
4
5from langchain.agents import create_agent
6from langchain_openai import ChatOpenAI
7from langchain.tools import tool
8from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
9
10# 1. 定义工具
11@tool
12def get_weather(city: str) -> str:
13    """获取指定城市的天气信息"""
14    # 模拟 API 返回
15    return f"{city} 天气晴朗, 25°C"
16
17# 2. 定义结构化输出 Schema
18class WeatherReport(BaseModel):
19    city: str = Field(description="城市名称")
20    temperature: float = Field(description="温度数值")
21    summary: str = Field(description="一句话天气总结")
22
23# 3. 定义自定义中间件 (示例：自动添加礼貌用语)
24class PolitenessMiddleware(AgentMiddleware):
25    def wrap_model_call(self, request: ModelRequest, handler) -> ModelResponse:
26        # 在发送给模型前，修改 System Prompt
27        print("🕵️ Middleware: 正在注入礼貌指令...")
28        if request.messages:
29            last_msg = request.messages[-1]
30            if last_msg.role == "user":
31                last_msg.content += " (请用非常礼貌的语气回答)"
32        return handler(request)
33
34# 4. 构建 Agent
35async def main():
36    agent = create_agent(
37        model=ChatOpenAI(model="gpt-4o-mini"),
38        tools=[get_weather],
39        middleware=[PolitenessMiddleware()],
40        # 强制结构化输出 (v1 特性)
41        # response_format=ToolStrategy(WeatherReport) # 若需强制结构化可开启此行
42    )
43
44    print("🚀 Agent 启动...")
45    result = await agent.ainvoke({
46        "messages": [{"role": "user", "content": "帮我查一下北京的天气"}]
47    })
48
49    # v1 的 result 包含完整的执行状态
50    print("\n💬 最终回复:")
51    print(result["messages"][-1].content)
52
53if __name__ == "__main__":
54    asyncio.run(main())
55

十三、总结

LangChain v1 标志着我们从 “玩票性质的 Chain” 走向了 “工程化的 Agent”。

如果你需要构建简单的问答机器人，LangChain v1 提供了更统一的接口。
如果你需要构建复杂的、多步推理的、具有自我纠错能力的企业级智能体，LangChain v1 (配合 LangGraph) 是目前 Python 生态中最佳的选择。

下一步建议： 安装 langchain-classic 确保旧代码运行，同时在新模块中开始尝试使用 create_agent。慎重更新老项目。。。。。。崩了。。。别赖我。。

《LangChain v1 重大更新讲解⚠⚠⚠》是转载文章，点击查看原文。

LangChain v1 重大更新讲解⚠⚠⚠