LangChain v1 重大更新讲解⚠⚠⚠LangChain v1 重大更新讲解作者：吴佳浩最后更新：2025-1

LangChain v1 重大更新讲解

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

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

人工智能的无限可能.png

作者：吴佳浩

最后更新：2025-11-22

适用版本：LangChain v1.0+

0. 环境准备

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

# 安装 v1 核心包、经典兼容包和图运行时
pip install -U langchain langchain-classic langgraph

# 安装适配的模型提供商包 (以 OpenAI 为例)
pip install -U langchain-openai

一、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 图。

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

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

为什么废弃 initialize_agent？

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

基本用法：

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

# 1. 定义模型
model = ChatOpenAI(model="gpt-4o")

# 2. 创建 Agent
agent = create_agent(
    model=model,
    tools=[search_tool, calculator_tool],
    system_prompt="你是一个乐于助人的金融分析师。"
)

# 3. 运行 (Invoke)
result = agent.invoke({"messages": [{"role": "user", "content": "分析 AAPL 股价"}]})

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

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

生命周期时序图：

sequenceDiagram
    participant User
    participant MW as Middleware (中间件层)
    participant Agent as Agent Runtime
    participant Model as LLM

    User->>Agent: invoke(input)
    Agent->>MW: 1. before_agent_start
    MW-->>Agent: (清洗后的输入)

    loop 思考与执行循环
        Agent->>MW: 2. before_model
        Note right of MW: 动态修改 Prompt / 路由模型
        
        rect rgb(240,240,240)
            MW->>Model: 3. wrap_model_call
            Model-->>MW: 返回原始结果
        end
        
        MW-->>Agent: 4. after_model (校验输出)

        opt 工具调用
            Agent->>MW: 5. wrap_tool_call
            Note right of MW: 敏感操作审批 / 审计
            MW-->>Agent: 工具结果
        end
    end

    Agent->>MW: 6. after_agent
    MW-->>User: 最终响应

六、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)：

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

✔ 新 (v1)：

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

2. LLMChain → model.invoke

❌ 旧 (v0)：

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

✔ 新 (v1)：

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

3. Tool 定义方式

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

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

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

graph TD
  Root[" my_agent_project/"] --> A[" app/"]
  
  A --> B[" agent.py <br/> (create_agent 组装入口)"]
  
  A --> C["middleware/ <br/> (中间件层)"]
  C --> C1[" auth_middleware.py"]
  C --> C2[" risk_control.py"]
  
  A --> D[" schemas/ <br/> (数据结构)"]
  D --> D1[" user_context.py"]
  D --> D2[" output_schema.py"]
  
  A --> E[" tools/ <br/> (工具集)"]
  E --> E1[" search_tool.py"]
  E --> E2[" db_tool.py"]
  
  A --> F[" main.py <br/> (FastAPI/Streamlit 入口)"]

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

场景：自动代码修复 Agent。

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

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

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

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

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

import asyncio
from typing import Any, Dict
from pydantic import BaseModel, Field

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain.tools import tool
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse

# 1. 定义工具
@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    # 模拟 API 返回
    return f"{city} 天气晴朗, 25°C"

# 2. 定义结构化输出 Schema
class WeatherReport(BaseModel):
    city: str = Field(description="城市名称")
    temperature: float = Field(description="温度数值")
    summary: str = Field(description="一句话天气总结")

# 3. 定义自定义中间件 (示例：自动添加礼貌用语)
class PolitenessMiddleware(AgentMiddleware):
    def wrap_model_call(self, request: ModelRequest, handler) -> ModelResponse:
        # 在发送给模型前，修改 System Prompt
        print("🕵️ Middleware: 正在注入礼貌指令...")
        if request.messages:
            last_msg = request.messages[-1]
            if last_msg.role == "user":
                last_msg.content += " (请用非常礼貌的语气回答)"
        return handler(request)

# 4. 构建 Agent
async def main():
    agent = create_agent(
        model=ChatOpenAI(model="gpt-4o-mini"),
        tools=[get_weather],
        middleware=[PolitenessMiddleware()],
        # 强制结构化输出 (v1 特性)
        # response_format=ToolStrategy(WeatherReport) # 若需强制结构化可开启此行
    )

    print("🚀 Agent 启动...")
    result = await agent.ainvoke({
        "messages": [{"role": "user", "content": "帮我查一下北京的天气"}]
    })

    # v1 的 result 包含完整的执行状态
    print("\n💬 最终回复:")
    print(result["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

十三、总结

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

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

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

LangChain v1 重大更新讲解⚠⚠⚠