智能体

智能体将语言模型与工具相结合，创建能够进行任务推理、决定使用哪些工具以及迭代寻求解决方案的系统。 create_agent 提供了一个生产就绪的智能体实现。一个LLM智能体通过循环运行工具以实现目标。智能体运行，直到满足停止条件——即模型发出最终输出或达到迭代限制。

create_agent 使用 LangGraph 构建了一个基于图的智能体运行时。图由节点（步骤）和边（连接）组成，这些节点和边定义了您的智能体如何处理信息。智能体通过这个图进行移动，执行节点，如模型节点（调用模型）、工具节点（执行工具）或中间件。了解有关图API的更多信息。

核心组件

模型

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

静态模型

静态模型在创建智能体时进行一次配置，并在整个执行过程中保持不变。这是最常见且最直接的方法。要从模型标识符字符串初始化一个静态模型：模型：

from langchain.agents import create_agent

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

模型标识符字符串支持自动推断（例如，"gpt-5" 将被推断为 "openai:gpt-5"）。请参阅 [参考](https://reference.langchain.com/python/langchain/models/#langchain.chat_models.init_chat_model(model_provider) 以查看模型标识符字符串映射的完整列表。

为了更好地控制模型配置，请直接使用提供程序包初始化模型实例。在此示例中，我们使用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
    # ... (other params)
)
agent = create_agent(model, tools=tools)

模型实例让您完全控制配置。当您需要设置特定的参数，如temperature、max_tokens、timeouts、base_url以及其他特定于提供者的设置时，请使用它们。请参阅参考以查看您模型上的可用参数和方法。

动态模型

动态模型根据当前的状态和上下文在进行选择。这允许实现复杂的路由逻辑和成本优化。要使用动态模型，请使用@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:
    """Choose model based on conversation complexity."""
    message_count = len(request.state["messages"])

    if message_count > 10:
        # Use an advanced model for longer conversations
        model = advanced_model
    else:
        model = basic_model

    request.model = model
    return handler(request)

agent = create_agent(
    model=basic_model,  # Default model
    tools=tools,
    middleware=[dynamic_model_selection]
)

在结构化输出时，不支持预绑定模型（已调用bind_tools的模型）。如果您需要与结构化输出一起使用动态模型选择，请确保传递给中间件的模型不是预绑定的。

有关模型配置的详细信息，请参阅模型。有关中间件中的动态模型选择模式，请参阅中间件中的动态模型。

工具

工具赋予智能体执行动作的能力。智能体不仅超越了简单的模型绑定，还通过以下方式促进：

按顺序进行多次工具调用（由单个提示触发）
适当情况下并行工具调用
根据先前结果动态选择工具
工具重试逻辑和错误处理
工具调用之间的状态持久化

有关更多信息，请参阅工具。

定义工具

将工具列表传递给智能体。

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


@tool
def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"

@tool
def get_weather(location: str) -> str:
    """Get weather information for a location."""
    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_core.messages import ToolMessage


@wrap_tool_call
def handle_tool_errors(request, handler):
    """Handle tool execution errors with custom messages."""
    try:
        return handler(request)
    except Exception as e:
        # Return a custom error message to the model
        return ToolMessage(
            content=f"Tool error: Please check your input and try again. ({str(e)})",
            tool_call_id=request.tool_call["id"]
        )

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

智能体在工具失败时将返回一个ToolMessage，其中包含自定义错误信息：

[
    ...
    ToolMessage(
        content="Tool error: Please check your input and try again. (division by zero)",
        tool_call_id="..."
    ),
    ...
]

ReAct循环中的工具使用

智能体遵循ReAct（“推理+行动”）模式，在针对工具调用的简短推理步骤和将结果观察输入后续决策之间交替，直到它们能够提供一个最终答案。

Example of ReAct loop

提示：识别当前最受欢迎的无线耳机并验证其可用性。

================================ Human Message =================================

Find the most popular wireless headphones right now and check if they're in stock

推理: “流行度是时间敏感的，我需要使用提供的搜索工具。”
行动: 调用 search_products("wireless headphones")

================================== Ai Message ==================================
Tool Calls:
  search_products (call_abc123)
 Call ID: call_abc123
  Args:
    query: wireless headphones

================================= Tool Message =================================

Found 5 products matching "wireless headphones". Top 5 results: WH-1000XM5, ...

推理: “在回答之前，我需要确认顶级物品的可用性。”
行动: 调用 check_inventory("WH-1000XM5")

================================== Ai Message ==================================
Tool Calls:
  check_inventory (call_def456)
 Call ID: call_def456
  Args:
    product_id: WH-1000XM5

================================= Tool Message =================================

Product WH-1000XM5: 10 units in stock

推理: “我拥有最受欢迎的模型及其库存状态。我现在可以回答用户的问题。”
行动: 生成最终答案

================================== Ai Message ==================================

I found wireless headphones (model WH-1000XM5) with 10 units in stock...

要了解更多关于工具的信息，请参阅工具。

系统提示

您可以通过提供提示来塑造智能体处理任务的方式。参数 system_prompt 可以作为字符串提供：

agent = create_agent(
    model,
    tools,
    system_prompt="You are a helpful assistant. Be concise and accurate."
)

当未提供[system_prompt](https://reference.langchain.com/python/langchain/agents/#langchain.agents.create_agent(system_prompt)时，智能体将从消息中直接推断其任务。

动态系统提示

对于需要根据运行时上下文或智能体状态修改系统提示符的更高级用例，您可以使用中间件。 The @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:
    """Generate system prompt based on user role."""
    user_role = request.runtime.context.get("user_role", "user")
    base_prompt = "You are a helpful assistant."

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

    return base_prompt

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

# The system prompt will be set dynamically based on context
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Explain machine learning"}]},
    context={"user_role": "expert"}
)

有关消息类型和格式的更多详细信息，请参阅消息。有关中间件的全面文档，请参阅中间件。

调用

您可以通过传递一个更新给其 State 来调用一个智能体。所有智能体在其状态中包含一个消息序列；要调用智能体，传递一条新消息：

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

为了从智能体中流式传输步骤和/或令牌，请参阅流式传输指南。否则，智能体遵循 LangGraph 图 API 并支持所有相关方法。

高级概念

结构化输出

在某些情况下，您可能希望智能体以特定格式返回输出。LangChain通过[response_format](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.ModelRequest(response_format)参数提供了结构化输出的策略。

工具策略

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="openai:gpt-4o-mini",
    tools=[search_tool],
    response_format=ToolStrategy(ContactInfo)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

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

提供者策略

ProviderStrategy 使用模型提供者的原生结构化输出生成。这更可靠，但仅适用于支持原生结构化输出的提供者（例如，OpenAI）：

from langchain.agents.structured_output import ProviderStrategy

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

截至 langchain 1.0，仅传递模式（例如，response_format=ContactInfo）不再受支持。您必须显式使用 ToolStrategy 或 ProviderStrategy。

要了解结构化输出，请参阅结构化输出。

记忆

智能体通过消息状态自动维护对话历史。您还可以配置智能体在对话过程中使用自定义状态模式来记住更多信息。存储在状态中的信息可以被视为智能体的短期记忆：自定义状态模式必须扩展为 TypedDict AgentState。有两种方式可以定义自定义状态：

通过中间件（推荐）
在 state_schema 上通过 create_agent

通过中间件定义自定义状态比在 state_schema 上通过 create_agent 定义它更受欢迎，因为它允许您将状态扩展概念性地限制到相关的中间件和工具。state_schema 仍然支持在 create_agent 上进行向后兼容。

通过中间件定义状态

使用中间件来定义自定义状态，当您的自定义状态需要被附加到该中间件的特定中间件钩子和工具访问时。

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


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()]
)

# The agent can now track additional state beyond messages
result = agent.invoke({
    "messages": [{"role": "user", "content": "I prefer technical explanations"}],
    "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
)
# The agent can now track additional state beyond messages
result = agent.invoke({
    "messages": [{"role": "user", "content": "I prefer technical explanations"}],
    "user_preferences": {"style": "technical", "verbosity": "detailed"},
})

截至 langchain 1.0，自定义状态模式必须是 TypedDict 类型。Pydantic 模型和 dataclasses 不再受支持。有关更多详细信息，请参阅 v1 迁移指南。

要了解更多关于记忆的信息，请参阅记忆。有关实现跨会话持久的长时记忆的信息，请参阅长时记忆。

流媒体

我们已经看到如何使用 invoke 来调用智能体以获取最终响应。如果智能体执行多个步骤，这可能需要一些时间。为了显示中间进度，我们可以按发生顺序流回消息。

for chunk in agent.stream({
    "messages": [{"role": "user", "content": "Search for AI news and summarize the findings"}]
}, stream_mode="values"):
    # Each chunk contains the full state at that point
    latest_message = chunk["messages"][-1]
    if latest_message.content:
        print(f"Agent: {latest_message.content}")
    elif latest_message.tool_calls:
        print(f"Calling tools: {[tc['name'] for tc in latest_message.tool_calls]}")

有关流式传输的更多详细信息，请参阅流式传输。

中间件

中间件为在执行的不同阶段自定义智能体行为提供了强大的扩展性。您可以使用中间件来：

在调用模型之前处理进程状态（例如，消息修剪、上下文注入）
修改或验证模型的响应（例如，安全措施、内容过滤）
使用自定义逻辑处理工具执行错误
根据状态或上下文实现动态模型选择
添加自定义日志记录、监控或分析

中间件可以无缝集成到智能体的执行图中，让您能够在关键点拦截和修改数据流，而无需更改核心智能体逻辑。

For comprehensive middleware documentation including decorators like @before_model, @after_model, and @wrap_tool_call, see Middleware.

在GitHub上编辑此页面的源代码。

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

LangChain v1.0

开始使用

核心组件

高级用法

生产环境使用

核心组件

模型

静态模型

动态模型

工具

定义工具

工具错误处理

ReAct循环中的工具使用

系统提示

动态系统提示

调用

高级概念

结构化输出

工具策略

提供者策略

记忆

通过中间件定义状态

通过 `state_schema` 定义状态

流媒体

中间件

LangChain v1.0

开始使用

核心组件

高级用法

生产环境使用

​核心组件

​模型

​静态模型

​动态模型

​工具

​定义工具

​工具错误处理

​ReAct循环中的工具使用

​系统提示

​动态系统提示

​调用

​高级概念

​结构化输出

​工具策略

​提供者策略

​记忆

​通过中间件定义状态

​通过 state_schema 定义状态

​流媒体

​中间件

核心组件

模型

静态模型

动态模型

工具

定义工具

工具错误处理

ReAct循环中的工具使用

系统提示

动态系统提示

调用

高级概念

结构化输出

工具策略

提供者策略

记忆

通过中间件定义状态

通过 `state_schema` 定义状态

流媒体

中间件