Skip to main content
本指南概述了 LangChain v1 与之前版本之间的主要变化。

​
简化软件包

langchain 包命名空间在 v1 版本中已大幅精简，专注于为智能体提供核心构建块。精简后的包让核心功能更易于发现和使用。

​
命名空间

模块可用内容备注
langchain.agentscreate_agent, AgentState核心智能体创建功能
langchain.messages消息类型, 内容块, trim_messages从 langchain-core 重新导出
langchain.tools@tool, BaseTool, 注入辅助函数从 langchain-core 重新导出
langchain.chat_modelsinit_chat_model, BaseChatModel统一模型初始化
langchain.embeddingsinit_embeddings, Embeddings嵌入模型

​
langchain-classic

如果您之前使用了来自 langchain 包的以下任何内容，您需要安装 langchain-classic 并更新您的导入：
  • 传统链（LLMChain、ConversationChain 等）
  • 检索器（例如 MultiQueryRetriever 或之前 langchain.retrievers 模块中的任何内容）
  • 索引 API
  • hub 模块（用于以编程方式管理提示词）
  • 嵌入模块（例如 CacheBackedEmbeddings 和社区嵌入）
  • langchain-community 重新导出
  • 其他已弃用功能
# Chains
from langchain_classic.chains import LLMChain

# Retrievers
from langchain_classic.retrievers import ...

# Indexing
from langchain_classic.indexes import ...

# Hub
from langchain_classic import hub
使用以下命令安装： 
pip install langchain-classic

​
迁移到 create_agent

在 v1.0 之前，我们推荐使用 langgraph.prebuilt.create_react_agent 来构建智能体。 现在，我们推荐您使用 langchain.agents.create_agent 来构建智能体。 下表概述了从 create_react_agent 到 create_agent 的功能变化：
章节简要说明 - 变更内容
导入路径包从 langgraph.prebuilt 移动到 langchain.agents
提示词参数重命名为 [system_prompt](https://reference.langchain.com/python/langchain/agents/#langchain.agents.create_agent(system_prompt)，动态提示词使用中间件
模型前钩子由带有 before_model 方法的中间件替代
模型后钩子由带有 after_model 方法的中间件替代
自定义状态仅支持 TypedDict，可通过 state_schema 或中间件定义
模型通过中间件动态选择，不支持预绑定模型
工具工具错误处理移至带有 wrap_tool_call 的中间件
结构化输出移除提示输出，使用 ToolStrategy/ProviderStrategy
流式节点名称节点名称从 "agent" 更改为 "model"
运行时上下文通过 context 参数进行依赖注入，而非 config["configurable"]
命名空间精简以专注于智能体构建块，旧代码移至 langchain-classic

​
导入路径

智能体预构建的导入路径已从 langgraph.prebuilt 更改为 langchain.agents。 函数名称已从 create_react_agent 更改为 create_agent： 
from langgraph.prebuilt import create_react_agent 
from langchain.agents import create_agent
要了解更多信息，请参阅 智能体。

​
提示词

​
静态提示重命名

prompt 参数已重命名为 system_prompt： 
from langchain.agents import create_agent


agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[check_weather],
    system_prompt="You are a helpful assistant"
)

​
SystemMessage 转为字符串

如果使用 SystemMessage 对象在系统提示中，提取字符串内容： 
from langchain.agents import create_agent


agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[check_weather],
    system_prompt="You are a helpful assistant"
)

​
动态提示词

动态提示是一种核心的上下文工程模式——它能根据当前的对话状态，调整你提供给模型的信息。为此，请使用 @dynamic_prompt 装饰器： 
from dataclasses import dataclass

from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest
from langgraph.runtime import Runtime


@dataclass
class Context:  
    user_role: str = "user"

@dynamic_prompt
def dynamic_prompt(request: ModelRequest) -> str:  
    user_role = request.runtime.context.user_role
    base_prompt = "You are a helpful assistant."

    if user_role == "expert":
        prompt = (
            f"{base_prompt} Provide detailed technical responses."
        )
    elif user_role == "beginner":
        prompt = (
            f"{base_prompt} Explain concepts simply and avoid jargon."
        )
    else:
        prompt = base_prompt

    return prompt  

agent = create_agent(
    model="openai:gpt-4o",
    tools=tools,
    middleware=[dynamic_prompt],  
    context_schema=Context
)

# Use with context
agent.invoke(
    {"messages": [{"role": "user", "content": "Explain async programming"}]},
    context=Context(user_role="expert")
)

​
预模型钩子

模型前钩子现已通过 before_model 方法实现为中间件。这种新模式更具扩展性，您可以定义多个中间件在模型调用前运行，并在不同智能体间复用通用模式。 常见用例包括：
  • 总结对话历史
  • 精简消息
  • 输入护栏，例如 PII 脱敏
v1 现在有了摘要中间件作为内置选项： 
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware


agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=tools,
    middleware=[
        SummarizationMiddleware(  
            model="anthropic:claude-sonnet-4-5",  
            max_tokens_before_summary=1000
        )  
    ]  
)

​
模型后钩子

模型后钩子现已通过 after_model 方法实现为中间件。 这种新模式更具扩展性——你可以定义多个中间件在模型调用后运行，从而在不同的智能体之间复用通用模式。 常见用例包括： v1 有一个内置中间件，用于人工介入审批工具调用： 
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware


agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[read_email, send_email],
    middleware=[HumanInTheLoopMiddleware(
        interrupt_on={
            "send_email": True,
            "description": "Please review this email before sending"
        },
    )]
)

​
自定义状态

自定义状态通过添加额外的字段来扩展默认的智能体状态。你可以通过两种方式定义自定义状态：
  1. 通过 state_schema 在 create_agent 上 - 最适用于在工具中使用的状态
  2. 通过中间件 - 最适用于由特定中间件钩子管理的状态，以及附加到该中间件的工具
通过中间件定义自定义状态优于通过 state_schema 在 create_agent 上定义，因为它允许您将状态扩展在概念上限定到相关的中间件和工具范围内。state_schema 为了向后兼容仍然支持 create_agent。

​
通过 state_schema 定义状态

当您的自定义状态需要被工具访问时，使用 state_schema 参数： 
from langchain.tools import tool, ToolRuntime
from langchain.agents import create_agent, AgentState  


# Define custom state extending AgentState
class CustomState(AgentState):
    user_name: str

@tool
def greet(
    runtime: ToolRuntime[CustomState]
) -> str:
    """Use this to greet the user by name."""
    user_name = runtime.state.get("user_name", "Unknown")  
    return f"Hello {user_name}!"

agent = create_agent(  
    model="anthropic:claude-sonnet-4-5",
    tools=[greet],
    state_schema=CustomState  
)

​
通过中间件定义状态

中间件还可以通过设置 state_schema 属性来定义自定义状态。 这有助于将状态扩展在概念上限定在相关的中间件和工具范围内。 
from langchain.agents.middleware import AgentState, AgentMiddleware
from typing_extensions import NotRequired
from typing import Any

class CustomState(AgentState):
    model_call_count: NotRequired[int]

class CallCounterMiddleware(AgentMiddleware[CustomState]):
    state_schema = CustomState  

    def before_model(self, state: CustomState, runtime) -> dict[str, Any] | None:
        count = state.get("model_call_count", 0)
        if count > 10:
            return {"jump_to": "end"}
        return None

    def after_model(self, state: CustomState, runtime) -> dict[str, Any] | None:
        return {"model_call_count": state.get("model_call_count", 0) + 1}

agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[...],
    middleware=[CallCounterMiddleware()]  
)
请参阅中间件文档，了解有关通过中间件定义自定义状态的更多详情。

​
状态类型限制

create_agent 仅支持 TypedDict 用于状态模式。Pydantic 模型和 dataclasses 不再支持。 
from langchain.agents import AgentState, create_agent

# AgentState is a TypedDict
class CustomAgentState(AgentState):  
    user_id: str

agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=tools,
    state_schema=CustomAgentState  
)
只需继承自 langchain.agents.AgentState 而不是 BaseModel 或使用 dataclass 装饰。 如果需要执行验证，请在中间件钩子中处理。

​
模型

动态模型选择使您能够根据运行时上下文（例如，任务复杂性、成本约束或用户偏好）选择不同的模型。在 langgraph-prebuilt v0.6 版本中发布的 create_react_agent 支持通过传递给 model 参数的可调用对象进行动态模型和工具选择。 在 v1 中，此功能已被移植到中间件接口。

​
动态模型选择

from langchain.agents import create_agent
from langchain.agents.middleware import (
    AgentMiddleware, ModelRequest, ModelRequestHandler
)
from langchain.messages import AIMessage
from langchain_openai import ChatOpenAI


basic_model = ChatOpenAI(model="gpt-5-nano")
advanced_model = ChatOpenAI(model="gpt-5")

class DynamicModelMiddleware(AgentMiddleware):

    def wrap_model_call(self, request: ModelRequest, handler: ModelRequestHandler) -> AIMessage:
        if len(request.state.messages) > self.messages_threshold:
            model = advanced_model
        else:
            model = basic_model

        return handler(request.replace(model=model))

    def __init__(self, messages_threshold: int) -> None:
        self.messages_threshold = messages_threshold

agent = create_agent(
    model=basic_model,
    tools=tools,
    middleware=[DynamicModelMiddleware(messages_threshold=10)]
)

​
预绑定模型

为了更好地支持结构化输出，create_agent 不再接受预绑定了工具或配置的模型： 
# No longer supported
model_with_tools = ChatOpenAI().bind_tools([some_tool])
agent = create_agent(model_with_tools, tools=[])

# Use instead
agent = create_agent("openai:gpt-4o-mini", tools=[some_tool])
如果未使用结构化输出，动态模型函数可以返回预先绑定的模型。

​
工具

create_agent 的 [tools](https://reference.langchain.com/python/langchain/agents/#langchain.agents.create_agent(tools) 参数接受一个列表：
  • LangChain BaseTool 实例（由 @tool 装饰的函数）
  • 带有适当类型提示和文档字符串的可调用对象（函数）
  • dict，表示一个内置的提供商工具
参数将不再接受 ToolNode 实例。 
from langchain.agents import create_agent


agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[check_weather, search_web]
)

​
处理工具错误

您现在可以通过实现 wrap_tool_call 方法的中间件来配置工具错误的处理。 
# Example coming soon

​
结构化输出

​
节点变更

结构化输出过去通常在与主智能体分离的节点中生成。现在情况不再是这样。 我们在主循环中生成结构化输出，从而降低成本和延迟。

​
工具和提供商策略

v1 版本中引入了两种新的结构化输出策略：
  • ToolStrategy 使用模拟的工具调用 来生成结构化输出
  • ProviderStrategy 使用提供商原生的结构化输出生成
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy, ProviderStrategy
from pydantic import BaseModel


class OutputSchema(BaseModel):
    summary: str
    sentiment: str

# Using ToolStrategy
agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=tools,
    # explicitly using tool strategy
    response_format=ToolStrategy(OutputSchema)  
)

​
提示输出已移除

提示输出 不再通过 response_format 参数提供支持。与人工工具调用和提供商原生结构化输出等策略相比，提示输出并未被证明特别可靠。

​
流式节点名称重命名

当从智能体流式传输事件时，节点名称已从 "agent" 更改为 "model"，以更好地反映节点的用途。

​
运行时上下文

当你调用一个智能体时，通常需要传递两种类型的数据：
  • 随对话不断变化的动态状态（例如，消息历史）
  • 在对话中保持不变的静态上下文（例如，用户元数据）
在 v1 中，通过将 context 参数设置为 invoke 和 stream 来支持静态上下文。 
from dataclasses import dataclass

from langchain.agents import create_agent


@dataclass
class Context:
    user_id: str
    session_id: str

agent = create_agent(
    model=model,
    tools=tools,
    context_schema=ContextSchema  
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Hello"}]},
    context=Context(user_id="123", session_id="abc")  
)
为了向后兼容，旧的 config["configurable"] 模式仍然有效，但对于新应用程序或正在迁移到 v1 的应用程序，建议使用新的 context 参数。

​
标准内容

在 v1 版本中，消息新增了与提供商无关的标准内容块。通过 @message.content_blocks[content_blocks] 访问它们，即可获得跨提供商的一致的、有类型的视图。现有的 message.content 字段对于字符串或提供商原生结构保持不变。

​
有什么变化

  • 消息新增 content_blocks 属性，用于规范化内容
  • 标准化的块形状，相关文档见 消息
  • 可选通过 LC_OUTPUT_VERSION=v1 或 output_version="v1" 将标准块序列化为 content

​
读取标准化内容

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5-nano")
response = model.invoke("Explain AI")

for block in response.content_blocks:
    if block["type"] == "reasoning":
        print(block.get("reasoning"))
    elif block["type"] == "text":
        print(block.get("text"))

​
创建多模态消息

from langchain.messages import HumanMessage

message = HumanMessage(content_blocks=[
    {"type": "text", "text": "Describe this image."},
    {"type": "image", "url": "https://example.com/image.jpg"},
])
res = model.invoke([message])

​
示例块形状

# Text block
text_block = {
    "type": "text",
    "text": "Hello world",
}

# Image block
image_block = {
    "type": "image",
    "url": "https://example.com/image.png",
    "mime_type": "image/png",
}
有关更多详细信息，请参见内容块参考。

​
序列化标准内容

默认情况下，标准内容块不会被序列化到 content 属性中。如果您需要访问 content 属性中的标准内容块（例如，在向客户端发送消息时），您可以选择将它们序列化到 content 中。 
export LC_OUTPUT_VERSION=v1
了解更多：消息、标准内容块和多模态。

​
简化版包

langchain 包命名空间在 v1 版本中已大幅精简，以专注于智能体的核心构建模块。精简后的包让核心功能更易于发现和使用。

​
命名空间

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

​
langchain-classic

如果您之前从 langchain 包中使用了以下任何内容，您需要安装 langchain-classic 并更新您的导入：
  • 遗留链 (LLMChain, ConversationChain, 等)
  • 检索器 (例如 MultiQueryRetriever 或来自上一个 langchain.retrievers 模块的任何内容)
  • 索引 API
  • hub 模块 (用于以编程方式管理提示词)
  • 嵌入模块 (例如 CacheBackedEmbeddings 和社区嵌入)
  • langchain-community 的重新导出
  • 其他已弃用的功能
# Chains
from langchain_classic.chains import LLMChain

# Retrievers
from langchain_classic.retrievers import ...

# Indexing
from langchain_classic.indexes import ...

# Hub
from langchain_classic import hub
安装: 
uv pip install langchain-classic

​
重大变更

​
不再支持 Python 3.9

所有 LangChain 包现在要求 Python 3.10 或更高版本。Python 3.9 将于 2025 年 10 月 生命周期结束。

​
聊天模型更新后的返回类型

聊天模型调用的返回类型签名已从 BaseMessage 修复为 AIMessage。实现 bind_tools 的自定义聊天模型应该更新其返回签名： 
def bind_tools(
        ...
    ) -> Runnable[LanguageModelInput, AIMessage]:

​
OpenAI Responses API 的默认消息格式

在与 Responses API 交互时，langchain-openai 现在默认将响应项存储在消息 content 中。要恢复之前的行为，请将 LC_OUTPUT_VERSION 环境变量设置为 v0，或在实例化 ChatOpenAI 时指定 output_version="v0"。 
# Enforce previous behavior with output_version flag
model = ChatOpenAI(model="gpt-4o-mini", output_version="v0")

​
默认 max_tokens 在 langchain-anthropic 中

langchain-anthropic 中的 max_tokens 参数现在默认为基于所选模型的更高值，而不是之前的默认值 1024。如果您依赖于旧的默认值，请显式设置 max_tokens=1024。

​
遗留代码已移动到 langchain-classic

标准接口和智能体核心重点之外的现有功能已被迁移到 langchain-classic 包。请参阅 简化的命名空间 部分，了解核心 langchain 包中可用的功能以及已迁移到 langchain-classic 的内容。

​
已弃用 API 的移除

已被弃用并计划在 1.0 版本中移除的方法、函数和其他对象已被删除。请查看先前版本中的 弃用通知 以获取替代的 API。

​
.text() 现在是属性

在消息对象上使用 .text() 方法时应去掉括号： 
# Property access
text = response.text

# Deprecated method call
text = response.text()
现有的使用模式（即 .text()）将继续正常工作，但现在会发出警告。
在 GitHub 上编辑此页面的源代码。
通过 MCP 以编程方式将这些文档连接到 Claude、VSCode 等，以获得实时答案。