LangChain核心组件之Agents

智能体（Agents）将大语言模型（LLM）与 工具（Tools） 结合，构建出能够对任务进行推理、决定使用哪些工具，并通过迭代逐步达成目标的系统。

create_agent 提供了一个可用于生产环境的智能体实现。

一个 LLM 智能体会循环调用工具以达成目标。

智能体会持续运行，直到满足停止条件——例如模型输出最终答案，或达到最大迭代次数。

create_agent 基于 LangGraph 构建了一个**图（graph）**结构的智能体运行时。图由节点（步骤）和边（连接）组成，用于定义智能体如何处理信息。智能体在图中移动，依次执行各类节点，例如模型节点（调用模型）、工具节点（执行工具）或中间件（middleware）。
更多信息请参阅 Graph API。

核心组件

模型（Model）

模型 是智能体的推理引擎。它可以通过多种方式指定，支持静态和动态模型选择。

静态模型
静态模型在创建智能体时一次性配置，并在整个执行过程中保持不变。这是最常见且直接的方式。

你可以通过一个 模型标识符字符串 初始化静态模型：

from langchain.agents import create_agent

agent = create_agent("gpt-5", tools=tools)

模型标识符字符串支持自动推断（例如 "gpt-5" 会被自动识别为 "openai:gpt-5"）。完整的映射列表请参阅 官方参考文档。

若需更精细地控制模型配置，可直接使用提供商包初始化模型实例。以下示例使用 ChatOpenAI。其他可用的聊天模型类请参见 Chat models。

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-5",
    temperature=0.1,
    max_tokens=1000,
    timeout=30
    # ...（其他参数）
)
agent = create_agent(model, tools=tools)

使用模型实例可完全掌控配置。当你需要设置特定的 参数，如 temperature、max_tokens、timeout、base_url 或其他提供商专属设置时，请使用此方式。各模型支持的参数和方法请查阅 提供商参考文档。

动态模型
动态模型在 运行时（runtime） 根据当前 状态（state） 和上下文动态选择。这使得你可以实现复杂的路由逻辑和成本优化。

要使用动态模型，可通过 @wrap_model_call 装饰器创建中间件，在请求中动态替换模型：

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse

basic_model = ChatOpenAI(model="gpt-4o-mini")
advanced_model = ChatOpenAI(model="gpt-4o")

@wrap_model_call
def dynamic_model_selection(request: ModelRequest, handler) -> ModelResponse:
    """根据对话复杂度选择模型。"""
    message_count = len(request.state["messages"])

    if message_count > 10:
        # 对长对话使用高级模型
        model = advanced_model
    else:
        model = basic_model

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

agent = create_agent(
    model=basic_model,  # 默认模型
    tools=tools,
    middleware=[dynamic_model_selection]
)

使用结构化输出（structured output）时，不支持预绑定工具的模型（即已调用过 bind_tools 的模型）。若需在结构化输出中使用动态模型选择，请确保传入中间件的模型未被预绑定。 模型配置详情请参见 Models。动态模型选择模式请参见 Dynamic model in middleware。

工具（Tools）

工具赋予智能体执行具体操作的能力。LangChain 的智能体不仅支持简单的模型绑定工具，还提供以下高级功能：

• 单次提示触发多个工具的顺序调用
• 在适当时机进行并行工具调用
• 根据先前结果进行动态工具选择
• 工具调用的重试逻辑与错误处理
• 工具调用间的状态持久化

更多信息请参见 Tools。

定义工具
将工具列表传递给智能体即可。

工具可以是普通的 Python 函数，也可以是 协程（coroutines）。
你可以使用 tool 装饰器 自定义工具名称、描述、参数 schema 等属性。

from langchain.tools import tool
from langchain.agents import create_agent

@tool
def search(query: str) -> str:
    """搜索信息。"""
    return f"Results for: {query}"

@tool
def get_weather(location: str) -> str:
    """获取某地天气信息。"""
    return f"Weather in {location}: Sunny, 72°F"

agent = create_agent(model, tools=[search, get_weather])

如果传入空的工具列表，智能体将退化为一个不支持工具调用的纯 LLM 节点。

工具错误处理
要自定义工具错误的处理方式，可使用 @wrap_tool_call 装饰器创建中间件：

from langchain.agents import create_agent
from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage

@wrap_tool_call
def handle_tool_errors(request, handler):
    """使用自定义消息处理工具执行错误。"""
    try:
        return handler(request)
    except Exception as e:
        # 向模型返回自定义错误消息
        return ToolMessage(
            content=f"工具错误：请检查输入后重试。（{str(e)}）",
            tool_call_id=request.tool_call["id"]
        )

agent = create_agent(
    model="gpt-4o",
    tools=[search, get_weather],
    middleware=[handle_tool_errors]
)

当工具执行失败时，智能体会返回一个包含自定义错误消息的 ToolMessage：

[
    ...
    ToolMessage(
        content="工具错误：请检查输入后重试。（division by zero）",
        tool_call_id="..."
    ),
    ...
]

ReAct 循环中的工具使用
智能体遵循 ReAct（“推理 + 行动”）模式：交替进行简短的推理步骤与针对性的工具调用，并将观察结果反馈到后续决策中，直至生成最终答案。

用户提问：找出当前最受欢迎的无线耳机，并确认是否有货。

================================ 用户消息 =================================

找出当前最受欢迎的无线耳机，并确认是否有货

• 推理：“流行度具有时效性，我需要使用提供的搜索工具。”
• 行动：调用 search_products(“wireless headphones”)

================================== AI 消息 ==================================
工具调用：
  search_products (call_abc123)
 调用 ID: call_abc123
  参数：
    query: wireless headphones

================================= 工具消息 =================================

找到 5 款匹配“无线耳机”的产品。前 5 名：WH-1000XM5, ...

• 推理：“我需要确认排名第一的产品是否有库存，再作答。”
• 行动：调用 check_inventory(“WH-1000XM5”)

================================== AI 消息 ==================================
工具调用：
  check_inventory (call_def456)
 调用 ID: call_def456
  参数：
    product_id: WH-1000XM5

================================= 工具消息 =================================

产品 WH-1000XM5：库存 10 件

• 推理：“我已获得最热门型号及其库存状态，现在可以回答用户了。”
• 行动：生成最终答案

================================== AI 消息 ==================================

我找到了无线耳机（型号 WH-1000XM5），目前有 10 件库存...

更多关于工具的信息，请参见 Tools。

系统提示（System Prompt）
你可以通过提供提示来引导智能体如何处理任务。system_prompt 参数可接受字符串：

agent = create_agent(
    model,
    tools,
    system_prompt="你是一个乐于助人的助手。回答要简洁准确。"
)

如果不提供 system_prompt，智能体将直接从消息中推断任务。

该参数也可接受 SystemMessage 实例。使用 SystemMessage 可更精细地控制提示结构，适用于某些提供商的高级功能，例如 Anthropic 的提示缓存：

from langchain.agents import create_agent
from langchain.messages import SystemMessage, HumanMessage

literary_agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    system_prompt=SystemMessage(
        content=[
            {
                "type": "text",
                "text": "你是一个负责分析文学作品的 AI 助手。",
            },
            {
                "type": "text",
                "text": "<《傲慢与偏见》全文内容>",
                "cache_control": {"type": "ephemeral"}
            }
        ]
    )
)

result = literary_agent.invoke(
    {"messages": [HumanMessage("分析《傲慢与偏见》的主要主题。")]}
)

其中 cache_control: {“type”: “ephemeral”} 会指示 Anthropic 缓存该内容块，从而在重复请求相同系统提示时降低延迟和成本。

动态系统提示
对于需要根据运行时上下文或智能体状态动态修改系统提示的高级场景，可使用 中间件（middleware）。

@dynamic_prompt 装饰器可创建根据模型请求动态生成系统提示的中间件：

from typing import TypedDict

from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest

class Context(TypedDict):
    user_role: str

@dynamic_prompt
def user_role_prompt(request: ModelRequest) -> str:
    """根据用户角色生成系统提示。"""
    user_role = request.runtime.context.get("user_role", "user")
    base_prompt = "你是一个乐于助人的助手。"

    if user_role == "expert":
        return f"{base_prompt} 请提供详细的技术性回答。"
    elif user_role == "beginner":
        return f"{base_prompt} 请用简单语言解释概念，避免使用术语。"

    return base_prompt

agent = create_agent(
    model="gpt-4o",
    tools=[web_search],
    middleware=[user_role_prompt],
    context_schema=Context
)

# 系统提示将根据上下文动态设置
result = agent.invoke(
    {"messages": [{"role": "user", "content": "解释机器学习"}]},
    context={"user_role": "expert"}
)

消息类型与格式的更多细节，请参见 Messages。中间件的完整文档请参见 Middleware。

调用（Invocation）

你可以通过向智能体的 State 传递更新来调用它。所有智能体的状态中都包含一个 消息序列；调用时只需传入新消息：

result = agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山现在的天气如何？"}]}
)

若需流式获取智能体的步骤或 token，请参阅 流式处理（Streaming）指南。

此外，智能体遵循 LangGraph 的 Graph API，支持所有相关方法，如 stream 和 invoke。

高级概念

结构化输出（Structured Output）
有时你希望智能体以特定格式返回结果。LangChain 通过 response_format 参数提供结构化输出策略。

ToolStrategy
ToolStrategy 利用人工工具调用生成结构化输出，适用于所有支持工具调用的模型：

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

class ContactInfo(BaseModel):
    name: str
    email: str
    phone: str

agent = create_agent(
    model="gpt-4o-mini",
    tools=[search_tool],
    response_format=ToolStrategy(ContactInfo)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "从以下信息中提取联系人：John Doe, john@example.com, (555) 123-4567"}]
})

result["structured_response"]
# ContactInfo(name='John Doe', email='john@example.com', phone='(555) 123-4567')

ProviderStrategy
ProviderStrategy 利用模型提供商原生的结构化输出能力。这种方式更可靠，但仅适用于支持原生结构化输出的提供商（如 OpenAI）：

from langchain.agents.structured_output import ProviderStrategy

agent = create_agent(
    model="gpt-4o",
    response_format=ProviderStrategy(ContactInfo)
)

自 langchain 1.0 起，不再支持直接传入 schema（例如 response_format=ContactInfo）。你必须显式使用 ToolStrategy 或 ProviderStrategy。 结构化输出的更多内容，请参见 Structured output。

记忆（Memory）
智能体通过消息状态自动维护对话历史。你还可以配置自定义状态 schema，以在对话中记住额外信息。

这些状态信息可视为智能体的 短期记忆（short-term memory）。

自定义状态 schema 必须以 TypedDict 形式继承 AgentState。

定义自定义状态有两种方式：

• 通过 中间件（middleware）（推荐）
• 通过 create_agent 的 state_schema 参数

通过中间件定义状态
当你的自定义状态需要被特定中间件钩子或关联工具访问时，应使用中间件定义状态。

from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from typing import Any

class CustomState(AgentState):
    user_preferences: dict

class CustomMiddleware(AgentMiddleware):
    state_schema = CustomState
    tools = [tool1, tool2]

    def before_model(self, state: CustomState, runtime) -> dict[str, Any] | None:
        ...

agent = create_agent(
    model,
    tools=tools,
    middleware=[CustomMiddleware()]
)

# 智能体现在可追踪消息之外的额外状态
result = agent.invoke({
    "messages": [{"role": "user", "content": "我偏好技术性解释"}],
    "user_preferences": {"style": "technical", "verbosity": "detailed"},
})

通过 state_schema 定义状态
若自定义状态仅用于工具中，可使用 state_schema 参数作为快捷方式。

from langchain.agents import AgentState

class CustomState(AgentState):
    user_preferences: dict

agent = create_agent(
    model,
    tools=[tool1, tool2],
    state_schema=CustomState
)

# 智能体现在可追踪消息之外的额外状态
result = agent.invoke({
    "messages": [{"role": "user", "content": "我偏好技术性解释"}],
    "user_preferences": {"style": "technical", "verbosity": "detailed"},
})

自 langchain 1.0 起，自定义状态 schema 必须是 TypedDict 类型。不再支持 Pydantic 模型和 dataclass。详情请参阅 v1 迁移指南。

推荐通过中间件定义自定义状态，而非在 create_agent 中使用 state_schema，因为这样可以将状态扩展与相关中间件和工具在概念上保持一致。
为保持向后兼容，create_agent 仍支持 state_schema 参数。

关于记忆的更多内容，请参见 Memory。如需实现跨会话持久化的长期记忆，请参见 Long-term memory。

流式处理（Streaming）
我们已看到如何通过 invoke 获取最终响应。若智能体执行多个步骤，可能耗时较长。为展示中间进展，可流式返回每一步的消息。

for chunk in agent.stream({
    "messages": [{"role": "user", "content": "搜索 AI 新闻并总结发现"}]
}, stream_mode="values"):
    # 每个 chunk 包含当前完整状态
    latest_message = chunk["messages"][-1]
    if latest_message.content:
        print(f"智能体: {latest_message.content}")
    elif latest_message.tool_calls:
        print(f"正在调用工具: {[tc['name'] for tc in latest_message.tool_calls]}")

流式处理的更多细节，请参见 Streaming。

中间件（Middleware）
中间件（Middleware） 为自定义智能体行为提供了强大的扩展能力，可在执行的不同阶段介入：

• 在调用模型前处理状态（如消息裁剪、上下文注入）
• 修改或验证模型响应（如安全护栏、内容过滤）
• 使用自定义逻辑处理工具执行错误
• 根据状态或上下文实现动态模型选择
• 添加自定义日志、监控或分析
• 中间件无缝集成到智能体执行流程中，允许你在关键节点拦截并修改数据流，而无需改动核心智能体逻辑。

中间件的完整文档（包括 @before_model、@after_model、@wrap_tool_call 等装饰器）请参见 Middleware。