LangChain v1 新特性 - Docs by LangChain

LangChain v1 是一个专注、生产就绪的智能体构建基础框架。 我们围绕三个核心改进精简了框架：

create_agent

LangChain 中构建智能体的新标准，取代了 langgraph.prebuilt.create_react_agent。

标准内容块

新的 content_blocks 属性，提供跨提供商的现代 LLM 功能统一访问方式。

简化命名空间

langchain 命名空间已精简，专注于智能体的核心构建模块，遗留功能已移至 langchain-classic。

要升级，请运行：

bash pip pip install -U langchain bash uv uv add langchain

完整的变更列表，请参阅迁移指南。

`create_agent`

create_agent 是 LangChain 1.0 中构建智能体的标准方式。它提供了比 langgraph.prebuilt.create_react_agent 更简单的接口，同时通过使用中间件提供了更大的定制潜力。

from langchain.agents import create_agent

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[search_web, analyze_data, send_email],
    system_prompt="You are a helpful research assistant."
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "Research AI safety trends"}
    ]
})

在底层，create_agent 基于基本的智能体循环构建——调用模型，让其选择要执行的工具，然后在不再调用工具时结束：

更多信息，请参阅智能体。

中间件

中间件是 create_agent 的核心特性。它提供了一个高度可定制的入口点，提升了你能构建的智能体的上限。优秀的智能体需要上下文工程：在正确的时间将正确的信息提供给模型。中间件通过可组合的抽象，帮助你控制动态提示、对话摘要、选择性工具访问、状态管理和防护栏。

预构建中间件

LangChain 提供了一些用于常见模式的预构建中间件，包括：

PIIMiddleware：在发送给模型之前编辑敏感信息
SummarizationMiddleware：当对话历史过长时进行压缩
HumanInTheLoopMiddleware：对敏感工具调用要求批准

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),
        PIIMiddleware(
            "phone_number",
            detector=(
                r"(?:\+?\d{1,3}[\s.-]?)?"
                r"(?:\(?\d{2,4}\)?[\s.-]?)?"
                r"\d{3,4}[\s.-]?\d{4}"
			),
			strategy="block"
        ),
        SummarizationMiddleware(
            model="claude-sonnet-4-6",
            trigger={"tokens": 500}
        ),
        HumanInTheLoopMiddleware(
            interrupt_on={
                "send_email": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                }
            }
        ),
    ]
)

自定义中间件

你也可以构建自定义中间件以满足你的需求。中间件在智能体执行的每个步骤都暴露了钩子：

通过在 AgentMiddleware 类的子类上实现以下任一钩子来构建自定义中间件：

钩子	运行时机	用例
`before_agent`	调用智能体之前	加载记忆、验证输入
`before_model`	每次 LLM 调用之前	更新提示、修剪消息
`wrap_model_call`	围绕每次 LLM 调用	拦截并修改请求/响应
`wrap_tool_call`	围绕每次工具调用	拦截并修改工具执行
`after_model`	每次 LLM 响应之后	验证输出、应用防护栏
`after_agent`	智能体完成后	保存结果、清理

自定义中间件示例：

from dataclasses import dataclass
from typing import Callable

from langchain_openai import ChatOpenAI

from langchain.agents.middleware import (
    AgentMiddleware,
    ModelRequest
)
from langchain.agents.middleware.types import ModelResponse

@dataclass
class Context:
    user_expertise: str = "beginner"

class ExpertiseBasedToolMiddleware(AgentMiddleware):
    def wrap_model_call(
        self,
        request: ModelRequest,
        handler: Callable[[ModelRequest], ModelResponse]
    ) -> ModelResponse:
        user_level = request.runtime.context.user_expertise

        if user_level == "expert":
            # 更强大的模型
            model = ChatOpenAI(model="gpt-5.4")
            tools = [advanced_search, data_analysis]
        else:
            # 较弱的模型
            model = ChatOpenAI(model="gpt-5-nano")
            tools = [simple_search, basic_calculator]

        return handler(request.override(model=model, tools=tools))

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[
        simple_search,
        advanced_search,
        basic_calculator,
        data_analysis
    ],
    middleware=[ExpertiseBasedToolMiddleware()],
    context_schema=Context
)

更多信息，请参阅完整的中间件指南。

基于 LangGraph 构建

因为 create_agent 是基于 LangGraph 构建的，你自动获得了对长时间运行和可靠智能体的内置支持，通过：

持久化

对话通过内置检查点自动跨会话持久化

流式传输

实时流式传输令牌、工具调用和推理轨迹

Human in the Loop

在敏感操作前暂停智能体执行以供人类批准

时间旅行

将对话倒回至任意点，并探索替代路径和提示

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

结构化输出

create_agent 改进了结构化输出生成：

主循环集成：结构化输出现在在主循环中生成，无需额外的 LLM 调用
结构化输出策略：模型可以选择调用工具或使用提供商端的结构化输出生成
成本降低：消除了额外 LLM 调用带来的额外开销

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:
    """获取城市的天气。"""
    return f"it's sunny and 70 degrees in {city}"

agent = create_agent(
    "gpt-5.4-mini",
    tools=[weather_tool],
    response_format=ToolStrategy(Weather)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What's the weather in SF?"}]
})

print(repr(result["structured_response"]))
# 结果为 `Weather(temperature=70.0, condition='sunny')`

错误处理：通过 ToolStrategy 的 handle_errors 参数控制错误处理：

解析错误：模型生成的数据与所需结构不匹配
多次工具调用：模型为结构化输出模式生成 2 次以上的工具调用

标准内容块

内容块支持目前仅适用于以下集成：

对内容块的更广泛支持将逐步扩展到更多提供商。

新的 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']})")

优势

提供商无关：使用相同的 API 访问推理轨迹、引用、内置工具（网络搜索、代码解释器等）和其他功能，无论提供商如何
类型安全：所有内容块类型都有完整的类型提示
向后兼容：标准内容可以延迟加载，因此没有相关的破坏性变更

更多信息，请参阅我们的内容块指南。

简化包

LangChain v1 精简了 langchain 包命名空间，专注于智能体的核心构建模块。精简后的命名空间暴露了最有用和相关的功能：

命名空间

模块	可用内容	备注
`langchain.agents`	`create_agent`, `AgentState`	核心智能体创建功能
`langchain.messages`	消息类型, 内容块, `trim_messages`	从 `langchain-core` 重新导出
`langchain.tools`	`@tool`, `BaseTool`, 注入辅助工具	从 `langchain-core` 重新导出
`langchain.chat_models`	`init_chat_model`, `BaseChatModel`	统一的模型初始化
`langchain.embeddings`	`Embeddings`, `init_embeddings`	嵌入模型

其中大部分是从 langchain-core 重新导出的，以方便使用，这为你构建智能体提供了一个专注的 API 表面。

# 智能体构建
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`

遗留功能已移至 langchain-classic，以保持核心包的精简和专注。 langchain-classic 中包含的内容：

遗留的链和链实现
检索器（例如 MultiQueryRetriever 或之前 langchain.retrievers 模块中的任何内容）
索引 API
hub 模块（用于以编程方式管理提示）
langchain-community 导出
其他已弃用的功能

如果你使用其中任何功能，请安装 langchain-classic：

pip install langchain-classic

然后更新你的导入：

from langchain import ...  
from langchain_classic import ...  

from langchain.chains import ...  
from langchain_classic.chains import ...  

from langchain.retrievers import ...  
from langchain_classic.retrievers import ...  

from langchain import hub  
from langchain_classic import hub  

迁移指南

请参阅我们的迁移指南以获取将代码更新到 LangChain v1 的帮助。

报告问题

请在 GitHub 上使用 'v1' 标签报告在 1.0 中发现的任何问题。

附加资源

LangChain 1.0

阅读公告

中间件指南

深入了解中间件

智能体文档

完整的智能体文档

消息内容

新的内容块 API

迁移指南

如何迁移到 LangChain v1

GitHub

报告问题或贡献

另请参阅

版本控制 – 理解版本号
发布策略 – 详细的发布策略

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

create_agent

标准内容块

简化命名空间

​create_agent

​中间件

​预构建中间件

​自定义中间件

​基于 LangGraph 构建

持久化

流式传输

Human in the Loop

时间旅行

​结构化输出

​标准内容块

​优势

​简化包

​命名空间

​langchain-classic

​迁移指南

​报告问题

​附加资源

LangChain 1.0

中间件指南

智能体文档

消息内容

迁移指南

GitHub

​另请参阅

`create_agent`

中间件

预构建中间件

自定义中间件

基于 LangGraph 构建

结构化输出

标准内容块

优势

简化包

命名空间

`langchain-classic`

迁移指南

报告问题

附加资源

另请参阅