LangChain v1 新特性

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

•create_agent

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

⬢Standard content blocks

一个新的 content_blocks 属性，提供跨服务商对现代 LLM 功能的统一访问。

⊞Simplified namespace

langchain 命名空间已被精简，以专注于智能体的基本构建块，遗留功能已移至 langchain-classic。

要升级，

pip

pip install -U langchain

uv

uv add langchain

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

create_agent

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

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 构建在基本的智能体循环之上——调用模型，让它选择要执行的工具，然后在它不再调用任何工具时结束：

更多信息请参阅 智能体。

Middleware

Middleware 是 create_agent 的标志性特性。它提供了一个高度可定制的入口点，提升了你可以构建的上限。

优秀的智能体需要 上下文工程：在正确的时间将正确的信息传递给模型。Middleware 通过可组合的抽象，帮助你控制动态提示词、对话摘要、选择性工具访问、状态管理和护栏。

预构建 middleware

LangChain 为常见模式提供了几个 预构建 middleware，包括：

• 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"]
                }
            }
        ),
    ]
)

自定义 middleware

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

通过在一个 AgentMiddleware 类的子类上实现以下任一钩子，来构建自定义 middleware：

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

自定义 middleware 示例：

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":
            # More powerful model
            model = ChatOpenAI(model="gpt-5.5")
            tools = [advanced_search, data_analysis]
        else:
            # Less powerful model
            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
)

更多信息请参阅 完整的 middleware 指南。

构建在 LangGraph 之上

由于 create_agent 构建在 LangGraph 之上，你可以自动获得对长时间运行且可靠的智能体的内置支持，通过：

•Persistence

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

•Streaming

实时流式输出 token、工具调用和推理追踪

•Human-in-the-loop

在敏感操作之前暂停智能体执行以等待人工审批

•Time travel

将对话回退到任意时间点，并探索替代路径和提示词

你无需学习 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:
    """Get the weather for a city."""
    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"]))
# results in `Weather(temperature=70.0, condition='sunny')`

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

• 解析错误：模型生成的数据与期望的结构不匹配
• 多个工具调用：模型为结构化输出模式生成 2 个或更多工具调用

---

标准内容块

NOTE

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

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

对内容块的更广泛支持将逐步在更多服务商中推出。

新的 content_blocks 属性引入了跨服务商通用的消息内容标准表示：

from langchain_anthropic import ChatAnthropic

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

# Unified access to content blocks
for block in response.content_blocks:
    if block["type"] == "reasoning":
        print(f"Model reasoning: {block['reasoning']}")
    elif block["type"] == "text":
        print(f"Response: {block['text']}")
    elif block["type"] == "tool_call":
        print(f"Tool call: {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 表面。

# Agent building
from langchain.agents import create_agent

# Messages and content
from langchain.messages import AIMessage, HumanMessage

# Tools
from langchain.tools import tool

# Model initialization
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

pip install langchain-classic

uv

uv add 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。

报告问题

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

其他资源

•LangChain 1.0

阅读公告

•Middleware guide

深入了解 middleware

▤Agents Documentation

完整的智能体文档

•Message Content

新的内容块 API

•Migration guide

如何迁移到 LangChain v1

•GitHub

报告问题或贡献

另请参阅

• 版本管理 – 理解版本号
• 发布策略 – 详细的发布策略

---