LangChain v1 迁移指南 - Docs by LangChain

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

简化的包

langchain 包的命名空间在 v1 中已大幅缩减，专注于代理的核心构建块。简化的包使发现和使用核心功能变得更加容易。

命名空间

Module	What’s available	Notes
`langchain.agents`	`create_agent`, `AgentState`	Core agent creation functionality
`langchain.messages`	Message types, content blocks, `trim_messages`	Re-exported from `langchain-core`
`langchain.tools`	`@tool`, `BaseTool`, injection helpers	Re-exported from `langchain-core`
`langchain.chat_models`	`init_chat_model`, `BaseChatModel`	Unified model initialization
`langchain.embeddings`	`init_embeddings`, `Embeddings`	Embedding models

`langchain-classic`

If you were using any of the following from the langchain package, you’ll need to install langchain-classic and update your imports:

Legacy chains (LLMChain, ConversationChain, etc.)
Retrievers (e.g. MultiQueryRetriever or anything from the previous langchain.retrievers module)
The indexing API
The hub module (for managing prompts programmatically)
Embeddings modules (e.g. CacheBackedEmbeddings and community embeddings)
langchain-community re-exports
Other deprecated functionality

# 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

Install with:

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`，动态提示使用中间件
模型前钩子	由带有 `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 

有关更多信息，请参阅 Agents。

提示

静态提示重命名

prompt 参数已重命名为 system_prompt：

from langchain.agents import create_agent

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

`SystemMessage` 转换为字符串

如果在系统提示中使用 SystemMessage 对象，请提取字符串内容：

from langchain.agents import create_agent

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    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="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="claude-sonnet-4-5-20250929",
    tools=tools,
    middleware=[
        SummarizationMiddleware(  
            model="claude-sonnet-4-5-20250929",  
            max_tokens_before_summary=1000
        )  
    ]  
)

模型后钩子

模型后钩子现在通过带有 after_model 方法的中间件实现。这种新模式更具扩展性——您可以定义多个中间件在调用模型之后运行，在不同代理之间重用通用模式。常见用例包括：

人在回路
输出护栏

v1 为工具调用的人在回路审批提供了内置中间件：

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware

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

自定义状态

自定义状态使用其他字段扩展默认代理状态。您可以通过两种方式定义自定义状态：

通过 create_agent 上的 state_schema - 最适合在工具中使用的状态
通过中间件 - 最适合由特定中间件钩子和附加到该中间件的工具管理的状态

通过中间件定义自定义状态优于通过 create_agent 上的 state_schema 定义，因为它允许您将状态扩展在概念上限定到相关的中间件和工具。为了向后兼容，create_agent 仍然支持 state_schema。

通过 `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="claude-sonnet-4-5-20250929",
    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="claude-sonnet-4-5-20250929",
    tools=[...],
    middleware=[CallCounterMiddleware()]  
)

有关通过中间件定义自定义状态的更多详细信息，请参阅中间件文档。

状态类型限制

create_agent 仅支持 TypedDict 作为状态模式。不再支持 Pydantic 模型和 dataclass。

from langchain.agents import AgentState, create_agent

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

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    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 不再接受带有工具或配置的预绑定模型：

# 不再支持
model_with_tools = ChatOpenAI().bind_tools([some_tool])
agent = create_agent(model_with_tools, tools=[])

# 改用
agent = create_agent("gpt-4o-mini", tools=[some_tool])

如果未使用结构化输出，动态模型函数可以返回预绑定模型。

工具

create_agent 的 tools 参数接受以下列表：

LangChain BaseTool 实例（使用 @tool 装饰的函数）
具有适当类型提示和文档字符串的可调用对象（函数）
表示内置提供程序工具的 dict

该参数将不再接受 ToolNode 实例。

from langchain.agents import create_agent

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    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="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=Context  
)

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 属性，用于规范化内容
标准化的块形状，记录在 Messages 中
通过 LC_OUTPUT_VERSION=v1 或 output_version="v1" 将标准块可选序列化到 content 中

读取标准化内容

from langchain.chat_models import init_chat_model

model = init_chat_model("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

了解更多：Messages、Standard content blocks 和 Multimodal。

简化的包

langchain 包的命名空间在 v1 中已大幅缩减，专注于代理的核心构建块。简化的包使发现和使用核心功能变得更加容易。

命名空间

Module	What’s available	Notes
`langchain.agents`	`create_agent`, `AgentState`	Core agent creation functionality
`langchain.messages`	Message types, content blocks, `trim_messages`	Re-exported from `langchain-core`
`langchain.tools`	`@tool`, `BaseTool`, injection helpers	Re-exported from `langchain-core`
`langchain.chat_models`	`init_chat_model`, `BaseChatModel`	Unified model initialization
`langchain.embeddings`	`init_embeddings`, `Embeddings`	Embedding models

`langchain-classic`

If you were using any of the following from the langchain package, you’ll need to install langchain-classic and update your imports:

Legacy chains (LLMChain, ConversationChain, etc.)
Retrievers (e.g. MultiQueryRetriever or anything from the previous langchain.retrievers module)
The indexing API
The hub module (for managing prompts programmatically)
Embeddings modules (e.g. CacheBackedEmbeddings and community embeddings)
langchain-community re-exports
Other deprecated functionality

# 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"。

# 使用 output_version 标志强制执行以前的行为
model = ChatOpenAI(model="gpt-4o-mini", output_version="v0")

`langchain-anthropic` 中的默认 `max_tokens`

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

遗留代码移至 `langchain-classic`

标准接口和代理焦点之外的现有功能已移至 langchain-classic 包。有关核心 langchain 包中可用的内容和移至 langchain-classic 的内容的详细信息，请参阅简化的命名空间部分。

移除已弃用的 API

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

Text 属性

消息对象上的 .text() 方法使用应去掉括号，因为它现在是一个属性：

# 属性访问
text = response.text

# 已弃用的方法调用
text = response.text()

现有使用模式（即 .text()）将继续工作，但现在会发出警告。方法形式将在 v2 中移除。

从 `AIMessage` 中移除 `example` 参数

example 参数已从 AIMessage 对象中移除。我们建议迁移到使用 additional_kwargs 来根据需要传递额外的元数据。

次要变更

AIMessageChunk 对象现在包含一个 chunk_position 属性，位置为 'last' 以指示流中的最终块。这允许更清晰地处理流式消息。如果块不是最终块，chunk_position 将为 None。
LanguageModelOutputVar 现在类型化为 AIMessage 而不是 BaseMessage。
合并消息块的逻辑（AIMessageChunk.add）已更新，对合并块的最终 id 进行更复杂的选择处理。它优先考虑提供程序分配的 ID 而不是 LangChain 生成的 ID。
我们现在默认使用 utf-8 编码打开文件。
标准测试现在使用多模态内容块。

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.

LangChain v1.0

Get started

Core components

Advanced usage

Use in production

​简化的包

​命名空间

​langchain-classic

​迁移到 create_agent

​导入路径

​提示

​静态提示重命名

​SystemMessage 转换为字符串

​动态提示

​模型前钩子

​模型后钩子

​自定义状态

​通过 state_schema 定义状态

​通过中间件定义状态

​状态类型限制

​模型

​动态模型选择

​预绑定模型

​工具

​处理工具错误

​结构化输出

​节点变化

​工具和提供程序策略

​移除了提示输出

​流式节点名称重命名

​运行时上下文

​标准内容

​变化内容

​读取标准化内容

​创建多模态消息

​示例块形状

​序列化标准内容

​简化的包

​命名空间

​langchain-classic

​破坏性变更

​放弃 Python 3.9 支持

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

​OpenAI Responses API 的默认消息格式

​langchain-anthropic 中的默认 max_tokens

​遗留代码移至 langchain-classic

​移除已弃用的 API

​Text 属性

​从 AIMessage 中移除 example 参数

​次要变更

简化的包

命名空间

`langchain-classic`

迁移到 `create_agent`

导入路径

提示

静态提示重命名

`SystemMessage` 转换为字符串

动态提示

模型前钩子

模型后钩子

自定义状态

通过 `state_schema` 定义状态

通过中间件定义状态

状态类型限制

模型

动态模型选择

预绑定模型

工具

处理工具错误

结构化输出

节点变化

工具和提供程序策略

移除了提示输出

流式节点名称重命名

运行时上下文

标准内容

变化内容

读取标准化内容

创建多模态消息

示例块形状

序列化标准内容

简化的包

命名空间

`langchain-classic`

破坏性变更

放弃 Python 3.9 支持

更新聊天模型的返回类型

OpenAI Responses API 的默认消息格式

`langchain-anthropic` 中的默认 `max_tokens`

遗留代码移至 `langchain-classic`

移除已弃用的 API

Text 属性

从 `AIMessage` 中移除 `example` 参数

次要变更