6.1 核心组件（Agent）

Agents 结合语言模型与工具，构建能够推理任务、决策工具使用，并逐步推进解决方案的系统。create_agent 提供了可直接用于生产环境的 Agent 实现。

LLM Agent 会循环调用工具以达成目标，直至满足停止条件------即模型输出最终结果或达到迭代上限。其流程为：输入 → 模型 → 工具 → 输出，核心环节包含行动（action）、观察（observation）与完成（finish）。

create_agent 基于 LangGraph 构建了基于图的 Agent 运行时。图由节点（步骤）和边（连接）组成，定义了 Agent 处理信息的逻辑。Agent 会遍历该图，执行模型节点（调用模型）、工具节点（执行工具）或中间件等操作。如需了解更多，可查看 Graph API 相关文档。

核心组件（Core components）

模型（Model）

模型是 Agent 的推理核心，支持多种指定方式，包括静态和动态模型选择。

静态模型（Static model）

静态模型在创建 Agent 时配置一次，执行过程中保持不变，是最常用、最简洁的方式。

通过模型标识符字符串初始化静态模型：

python 复制代码

from langchain.agents import create_agent

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

模型标识符字符串支持自动推断（例如 "gpt-5" 会被推断为 "openai:gpt-5"）。查看参考文档可获取完整的模型标识符映射列表。

若需更精细控制模型配置，可通过供应商包直接初始化模型实例。以下示例使用 ChatOpenAI，其他可用聊天模型类可参考 Chat models：

python 复制代码

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（最大令牌数）、timeouts（超时时间）、base_url（基础地址）等特定参数或供应商专属设置的场景。查看参考文档可了解模型支持的参数和方法。

动态模型（Dynamic model）

动态模型会根据运行时的当前状态和上下文选择，支持复杂的路由逻辑和成本优化。

使用动态模型需通过 @wrap_model_call 装饰器创建中间件，在请求中修改模型：

python 复制代码

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-4.1-mini")
advanced_model = ChatOpenAI(model="gpt-4.1")

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

使用结构化输出时，不支持预绑定工具（已调用 bind_tools 的模型）。若需结合动态模型选择与结构化输出，确保传递给中间件的模型未预绑定工具。

模型配置详情可查看 Models，动态模型选择模式可参考 Dynamic model in middleware。

工具（Tools）

工具赋予 Agent 执行操作的能力。Agent 不仅支持简单的模型-工具绑定，还具备以下功能：

序列调用多个工具（由单个提示词触发）
适当时机并行调用工具
基于历史结果动态选择工具
工具重试逻辑与错误处理
工具调用间的状态持久化

定义工具（Defining tools）

向 Agent 传递工具列表即可完成配置。工具可定义为普通 Python 函数或协程，通过 tool 装饰器可自定义工具名称、描述、参数模式等属性：

python 复制代码

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

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

@tool
def get_weather(location: str) -> str:
    """获取指定地点的天气信息。"""
    return f"{location} 的天气：晴，72华氏度"

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

若传入空工具列表，Agent 将仅包含单个 LLM 节点，不具备工具调用能力。

工具错误处理（Tool error handling）

如需自定义工具错误处理逻辑，可通过 @wrap_tool_call 装饰器创建中间件：

python 复制代码

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-4.1",
    tools=[search, get_weather],
    middleware=[handle_tool_errors]
)

工具执行失败时，Agent 将返回包含自定义错误消息的 ToolMessage：

python 复制代码

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

ReAct 循环中的工具使用（Tool use in the ReAct loop）

Agent 遵循 ReAct（"推理 + 行动"）模式，交替执行目标明确的工具调用推理步骤，并将观察结果传入后续决策，直至生成最终答案。

ReAct 循环示例

提示词：找出当前最受欢迎的无线耳机并验证库存情况。

复制代码

================================ 人类消息 =================================
找出目前最受欢迎的无线耳机，查看是否有货

推理："受欢迎程度具有时效性，需使用提供的搜索工具。"

行动：调用 search_products("无线耳机")

复制代码

================================== AI 消息 ==================================
工具调用：
  search_products（调用ID：call_abc123）
  参数：
    query：无线耳机

================================= 工具消息 =================================
找到 5 款匹配"无线耳机"的产品，Top5 结果：WH-1000XM5、...

推理："需确认排名第一产品的库存状态后再回复用户。"

行动：调用 check_inventory("WH-1000XM5")

复制代码

================================== AI 消息 ==================================
工具调用：
  check_inventory（调用ID：call_def456）
  参数：
    product_id：WH-1000XM5

================================= 工具消息 =================================
产品 WH-1000XM5：库存 10 台

推理："已获取最受欢迎型号及库存状态，可向用户回复。"

行动：生成最终答案

复制代码

================================== AI 消息 ==================================
我找到目前最受欢迎的无线耳机型号为 WH-1000XM5，当前库存 10 台...

动态工具（Dynamic tools）

部分场景下需在运行时修改 Agent 可用工具集，而非提前定义所有工具，具体分为两种方式（取决于工具是否提前已知）：

过滤预注册工具

若所有可能用到的工具在创建 Agent 时已知，可先预注册所有工具，再根据状态、权限或上下文动态过滤暴露给模型的工具：

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from typing import Callable

@wrap_model_call
def filter_tools(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse],
) -> ModelResponse:
    """根据用户权限过滤工具。"""
    user_role = request.runtime.context.user_role

    if user_role == "admin":
        # 管理员可使用所有工具
        tools = request.tools
    else:
        # 普通用户仅可使用只读工具
        tools = [t for t in request.tools if t.name.startswith("read_")]

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

agent = create_agent(
    model="gpt-4o",
    tools=[read_data, write_data, delete_data],  # 预注册所有工具
    middleware=[filter_tools],
)

该方式适用于：

所有工具在编译/启动时已知
需根据权限、功能开关或对话状态过滤工具
工具本身静态，但可用性动态变化

更多示例可查看 Dynamically selecting tools。

运行时工具注册

若工具在运行时发现或创建（例如从 MCP 服务器加载、基于用户数据生成或从远程注册中心获取），需同时完成工具注册和动态执行处理，需两个中间件钩子：

wrap_model_call - 向请求中添加动态工具
wrap_tool_call - 处理动态添加工具的执行

python 复制代码

from langchain.tools import tool
from langchain.agents import create_agent
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ToolCallRequest

# 运行时动态添加的工具
@tool
def calculate_tip(bill_amount: float, tip_percentage: float = 20.0) -> str:
    """计算账单小费金额。"""
    tip = bill_amount * (tip_percentage / 100)
    return f"小费：${tip:.2f}，总计：${bill_amount + tip:.2f}"

class DynamicToolMiddleware(AgentMiddleware):
    """注册并处理动态工具的中间件。"""

    def wrap_model_call(self, request: ModelRequest, handler):
        # 向请求中添加动态工具（可从 MCP 服务器、数据库等加载）
        updated = request.override(tools=[*request.tools, calculate_tip])
        return handler(updated)

    def wrap_tool_call(self, request: ToolCallRequest, handler):
        # 处理动态工具的执行
        if request.tool_call["name"] == "calculate_tip":
            return handler(request.override(tool=calculate_tip))
        return handler(request)

agent = create_agent(
    model="gpt-4o",
    tools=[get_weather],  # 仅注册静态工具
    middleware=[DynamicToolMiddleware()],
)

# Agent 现在可同时使用 get_weather 和 calculate_tip
result = agent.invoke({
    "messages": [{"role": "user", "content": "计算 85 美元账单的 20% 小费"}]
})

该方式适用于：

工具在运行时发现（例如来自 MCP 服务器）
工具基于用户数据或配置动态生成
需与外部工具注册中心集成

运行时注册的工具必须使用 wrap_tool_call 钩子，否则 Agent 无法识别并执行未包含在初始工具列表中的动态工具。

系统提示词（System prompt）

通过提供提示词可定义 Agent 处理任务的方式，system_prompt 参数支持字符串格式：

python 复制代码

agent = create_agent(
    model,
    tools,
    system_prompt="你是一个有帮助的助手，回复需简洁准确。"
)

若未指定 system_prompt，Agent 将直接从消息中推断任务。

system_prompt 还支持 str 或 SystemMessage 类型，使用 SystemMessage 可更灵活控制提示词结构，适用于供应商专属功能（如 Anthropic 的提示词缓存）：

python 复制代码

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 缓存该内容块，减少重复请求的延迟和成本。

动态系统提示词（Dynamic system prompt）

如需根据运行时上下文或 Agent 状态修改系统提示词，可使用中间件实现。通过 @dynamic_prompt 装饰器创建中间件，基于模型请求生成系统提示词：

python 复制代码

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-4.1",
    tools=[web_search],
    middleware=[user_role_prompt],
    context_schema=Context
)

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

调用（Invocation）

调用 Agent 需向其 State（状态）传递更新内容。所有 Agent 的状态均包含消息序列，调用时只需传入新消息：

python 复制代码

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

如需流式获取 Agent 的步骤和/或令牌，可参考 streaming 指南。此外，Agent 遵循 LangGraph 的 Graph API，支持 stream、invoke 等相关方法。

高级概念（Advanced concepts）

结构化输出（Structured output）

部分场景下需 Agent 以特定格式返回结果，LangChain 通过 response_format 参数提供结构化输出策略。

工具策略（ToolStrategy）

ToolStrategy 利用人工工具调用生成结构化输出，适用于所有支持工具调用的模型。当供应商原生结构化输出（通过 ProviderStrategy）不可用或不可靠时，可使用该策略：

python 复制代码

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-4.1-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 利用模型供应商的原生结构化输出功能，可靠性更高，但仅适用于支持该功能的供应商：

python 复制代码

from langchain.agents.structured_output import ProviderStrategy

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

在 langchain 1.0 中，直接传递模式（例如 response_format=ContactInfo）时，若模型支持原生结构化输出，将默认使用 ProviderStrategy，否则自动降级为 ToolStrategy。

记忆（Memory）

Agent 通过消息状态自动维护对话历史，也可配置自定义状态模式，在对话过程中记录额外信息。状态中存储的信息可视为 Agent 的短期记忆（short-term memory）。

自定义状态模式必须以 TypedDict 形式继承 AgentState，有两种定义方式：

通过中间件定义状态（Defining state via middleware）

当自定义状态需被特定中间件钩子和关联工具访问时，推荐使用中间件定义：

python 复制代码

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

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

通过状态模式定义状态（Defining state via state_schema）

若自定义状态仅用于工具，可通过 create_agent 的 state_schema 参数快速定义：

python 复制代码

from langchain.agents import AgentState

class CustomState(AgentState):
    user_preferences: dict

agent = create_agent(
    model,
    tools=[tool1, tool2],
    state_schema=CustomState
)
# Agent 现在可跟踪消息之外的额外状态
result = agent.invoke({
    "messages": [{"role": "user", "content": "我偏好技术类解释"}],
    "user_preferences": {"style": "technical", "verbosity": "detailed"},
})

langchain 1.0 中，自定义状态模式必须为 TypedDict 类型，不再支持 Pydantic 模型和数据类，详情可查看 v1 迁移指南（v1 migration guide）。

相比通过 create_agent 的 state_schema 参数定义，中间件定义方式更优，可将状态扩展与相关中间件和工具在概念上绑定。state_schema 参数仍为向后兼容保留。

流式传输（Streaming）

前文介绍了通过 invoke 调用 Agent 获取最终响应的方式。若 Agent 需执行多个步骤，可能耗时较长，可通过流式传输实时返回消息，展示中间进度：

python 复制代码

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

中间件（Middleware）

中间件为自定义 Agent 执行各阶段行为提供了强大的扩展性，可用于：

模型调用前处理状态（例如消息截断、上下文注入）
修改或验证模型响应（例如安全护栏、内容过滤）
用自定义逻辑处理工具执行错误
基于状态或上下文实现动态模型选择
添加自定义日志、监控或分析功能

中间件可无缝集成到 Agent 的执行流程中，无需修改核心逻辑即可在关键节点拦截和修改数据流。

需要我将这份翻译整理成可直接保存的文档，或针对某个具体模块（如代码示例、参数说明）补充更细致的注释吗？