LangChain v1 版本变更学习

LangChain v1版本进行了重大架构重构，主要围绕三个核心改进方向：全新的Agent创建方式、统一的内容块标准和简化的命名空间。其中最显著的变化是Agent创建机制从create_react_agent升级为更灵活的create_agent，引入了中间件架构，通过六大钩子（before_agent、before_model等）实现对Agent生命周期的完全控制。同时，结构化输出功能从需要额外

FserSuN

12人浏览 · 2026-03-07 20:24:04

FserSuN · 2026-03-07 20:24:04 发布

LangChain v1 版本重大变更深度解析

概述

LangChain v1 是一个专注于生产环境的 Agent 构建框架，开发团队通过精简架构，围绕三个核心改进方向重新设计了整个框架：全新的 Agent 创建方式、统一的内容块标准、简化的命名空间。这些变化不仅提升了开发体验，更重要的是为复杂的生产场景提供了更强大的定制化能力。

一、Agent 创建：从 `create_react_agent` 到 `create_agent`

变化前（v0.x）

在 LangChain v0.x 版本中，创建 Agent 主要使用 langgraph.prebuilt.create_react_agent：

from langgraph.prebuilt import create_react_agent

agent = create_react_agent(
    model="claude-3-sonnet",
    tools=[search_web, analyze_data],
    system_prompt="You are a helpful assistant."
)

存在的问题：

扩展性有限，难以在 Agent 执行的关键节点插入自定义逻辑
缺乏标准化的上下文工程（Context Engineering）机制
复杂场景（如 PII 脱敏、对话摘要、人工审核）需要大量样板代码

变化后（v1.0）

v1.0 引入了全新的 create_agent，通过**中间件（Middleware）**架构提供了强大的定制化能力：

from langchain.agents import create_agent
from langchain.agents.middleware import (
    PIIMiddleware,
    SummarizationMiddleware,
    HumanInTheLoopMiddleware
)

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[read_email, send_email],
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        SummarizationMiddleware(model="claude-sonnet-4-6", trigger={"tokens": 500}),
        HumanInTheLoopMiddleware(
            interrupt_on={"send_email": {"allowed_decisions": ["approve", "edit", "reject"]}}
        ),
    ]
)

执行流程对比

中间件钩子体系

中间件架构通过六大钩子实现对 Agent 生命周期的完全控制：

钩子	执行时机	典型用途
`before_agent`	Agent 调用前	加载记忆、验证输入
`before_model`	每次 LLM 调用前	更新提示词、修剪消息
`wrap_model_call`	包裹 LLM 调用	拦截和修改请求/响应
`wrap_tool_call`	包裹工具调用	拦截和修改工具执行
`after_model`	LLM 响应后	验证输出、应用护栏
`after_agent`	Agent 完成后	保存结果、清理资源

实现原理与模式

实现原理：
create_agent 基于 LangGraph 构建，采用事件驱动架构。中间件通过**责任链模式（Chain of Responsibility Pattern）**串联，每个中间件可以选择继续传递请求或短路返回。

核心模式：

拦截器模式（Interceptor Pattern）：钩子机制允许在关键点拦截和修改数据流
控制反转（Inversion of Control）：框架调用用户代码（钩子），而非用户调用框架
组合优于继承（Composition over Inheritance）：通过组合多个中间件实现功能，而非继承基类

二、结构化输出：从额外调用到主循环集成

变化前（v0.x）

v0.x 中生成结构化输出需要额外的 LLM 调用：

# v0.x 方式：需要两次调用
from pydantic import BaseModel

class Weather(BaseModel):
    temperature: float
    condition: str

# 第一次：正常对话获取信息
response = agent.invoke({"messages": [{"role": "user", "content": "What's the weather in SF?"}]})

# 第二次：额外调用提取结构化数据
structured_output = model.with_structured_output(Weather).invoke(response["messages"])

问题：

额外的 LLM 调用增加成本
延迟增加
两次调用之间可能丢失上下文

变化后（v1.0）

v1.0 将结构化输出集成到主循环中：

from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy
from pydantic import BaseModel

class Weather(BaseModel):
    temperature: float
    condition: str

def weather_tool(city: str) -> str:
    """Get the weather for a city."""
    return f"it's sunny and 70 degrees in {city}"

agent = create_agent(
    "gpt-4.1-mini",
    tools=[weather_tool],
    response_format=ToolStrategy(Weather)  # 直接指定输出格式
)

result = agent.invoke({"messages": [{"role": "user", "content": "What's the weather in SF?"}]})
print(result["structured_response"])  # Weather(temperature=70.0, condition='sunny')

结构化输出策略

ToolStrategy 允许模型在两种策略间选择：

错误处理机制：

from langchain.agents.structured_output import ToolStrategy

agent = create_agent(
    model,
    tools=[weather_tool],
    response_format=ToolStrategy(
        Weather,
        handle_errors={
            "parsing_errors": "raise",      # 解析错误时抛出异常
            "multiple_tool_calls": "ignore"  # 多个工具调用时忽略
        }
    )
)

实现原理与模式

实现原理：
利用 LLM 的函数调用（Function Calling）能力，将 Pydantic 模型转换为 JSON Schema，让模型直接生成符合结构的数据。主循环通过状态机模式跟踪是否需要结构化输出。

核心模式：

策略模式（Strategy Pattern）：ToolStrategy 允许切换不同的结构化输出策略
模板方法模式（Template Method Pattern）：定义结构化输出的标准流程，允许子类定制特定步骤

三、内容块标准：统一的多模态内容访问

变化前（v0.x）

不同 Provider 的内容访问方式各异：

# OpenAI
response = openai_model.invoke("...")
content = response.content  # 纯文本

# Anthropic
response = anthropic_model.invoke("...")
content = response.content  # 可能是列表，包含文本和工具调用

# 需要编写大量条件代码处理差异

变化后（v1.0）

v1.0 引入统一的 content_blocks 属性：

from langchain_anthropic import ChatAnthropic

model = ChatAnthropic(model="claude-sonnet-4-6")
response = model.invoke("What's the capital of France?")

# 统一访问内容块
for block in response.content_blocks:
    if block["type"] == "reasoning":
        print(f"模型推理: {block['reasoning']}")
    elif block["type"] == "text":
        print(f"响应: {block['text']}")
    elif block["type"] == "tool_call":
        print(f"工具调用: {block['name']}({block['args']})")
    elif block["type"] == "image":
        print(f"图片: {block['source']}")

内容块类型体系

支持的 Provider

目前支持内容块的 Provider：

langchain-anthropic
langchain-aws
langchain-openai
langchain-google-genai
langchain-ollama

实现原理与模式

实现原理：
通过**适配器模式（Adapter Pattern）**将不同 Provider 的响应格式转换为统一的内容块标准。每个 Provider 实现特定的解析器，将原生响应转换为标准块格式。

核心模式：

适配器模式（Adapter Pattern）：统一不同 Provider 的 API 差异
访问者模式（Visitor Pattern）：便于对不同类型的内容块执行不同操作

四、命名空间简化：从臃肿到精简

变化前（v0.x）

v0.x 的 langchain 命名空间包含大量功能：

# 混乱的导入路径
from langchain.chains import RetrievalQA, LLMChain
from langchain.retrievers import MultiQueryRetriever
from langchain import hub
from langchain.indexes import VectorstoreIndexCreator
from langchain.agents import initialize_agent, AgentType

问题：

命名空间臃肿，包含大量遗留功能
核心功能被淹没在次要功能中
新用户难以找到正确的导入路径

变化后（v1.0）

v1.0 将核心功能精简到 langchain，将遗留功能迁移到 langchain-classic：

# v1.0 精简的核心导入
from langchain.agents import create_agent
from langchain.messages import AIMessage, HumanMessage
from langchain.tools import tool
from langchain.chat_models import init_chat_model
from langchain.embeddings import init_embeddings

命名空间对比

迁移方式

# 安装 langchain-classic
pip install langchain-classic

# 更新导入
from langchain import hub                    # 旧
from langchain_classic import hub             # 新

from langchain.chains import ...             # 旧
from langchain_classic.chains import ...      # 新

from langchain.retrievers import ...         # 旧
from langchain_classic.retrievers import ...  # 新

实现原理与模式

实现原理：
通过**包拆分（Package Splitting）**将代码库按功能生命周期分离。核心包保持精简和稳定，遗留功能独立维护。

核心模式：

单一职责原则（Single Responsibility Principle）：每个包有明确的职责边界
开闭原则（Open/Closed Principle）：核心包对扩展开放，对修改关闭

五、底层架构：基于 LangGraph 构建

LangGraph 集成

create_agent 完全基于 LangGraph 构建，自动获得以下能力：

无需学习 LangGraph 即可使用这些功能——它们开箱即用。

Agent 循环架构

六、设计模式总结

LangChain v1 的实现广泛运用了以下设计模式：

模式	应用场景	优势
中间件模式（Middleware）	Agent 生命周期钩子	高度可扩展、职责分离
责任链模式（Chain of Responsibility）	中间件串联执行	灵活组合、顺序可控
拦截器模式（Interceptor）	请求/响应拦截	透明增强、AOP 思想
策略模式（Strategy）	结构化输出策略	运行时切换算法
适配器模式（Adapter）	多 Provider 统一接口	消除差异、统一访问
状态机模式（State Machine）	Agent 执行循环	清晰的执行流程
控制反转（IoC）	框架调用用户代码	解耦、可测试
事件驱动架构（EDA）	LangGraph 集成	异步、可观测

附录：参考资料

LangChain v1 官方文档
https://docs.langchain.com/oss/python/releases/langchain-v1
LangChain v1 迁移指南
https://docs.langchain.com/oss/python/migrate/langchain-v1
LangChain Python SDK 参考
https://reference.langchain.com/python/langchain/
LangGraph 文档
https://docs.langchain.com/oss/python/langgraph
LangChain 版本策略
https://docs.langchain.com/oss/python/versioning
LangChain 变更日志
https://docs.langchain.com/oss/python/releases/changelog
langchain-classic PyPI
https://pypi.org/project/langchain-classic/
LangChain GitHub Issues (v1 标签)
https://github.com/langchain-ai/langchain/issues?q=state%3Aopen+label%3Av1