Langchain 1.0 版本的create_agent详解

第1节：执行摘要与架构范式转变

1.1 create_agent简介：现代统一代理API

create_agent函数是LangChain中用于构建可靠大型语言模型（LLM）代理的单一、生产就绪型实现 。其核心作用是将语言模型（作为推理引擎）与工具集（作为行动层）相结合，创建出能够对复杂任务进行推理、自主决定使用何种工具，并通过迭代流程寻找解决方案的系统 。

在生产环境中，create_agent通过抽象底层图形定义和状态转换的复杂性，提供了一种简洁且高效的代理构建方法。它标志着LangChain代理设计理念的重大进步，将重点从分散的、模板特定的代理类型（例如早期显式的ReAct实现）转移到统一、灵活的架构上来 。

1.2 create_agent在生产LLM系统中的作用

对于需要部署到生产环境中的LLM应用而言，可靠性、可控性和可扩展性至关重要。create_agent通过其底层架构LangGraph提供了关键的支持：

1. 可靠性与结构化执行： 基于LangGraph的图形运行时确保了代理执行的每一步都是结构化和可预测的 。这种结构化执行是实现高效调试、可追溯性（通过跟踪）和最终系统可靠性的基础 。
2. 状态管理与容错性： 代理必须能够处理多轮对话和长期任务。LangGraph提供的内置状态管理能力，以及基于检查点（Checkpointing）的机制，使得代理即使在遇到中断或系统故障时，也能从已知的良好状态恢复 。
3. 深度定制能力： 尽管create_agent提供了一个预构建的、开箱即用的执行流程，但它通过middleware（中间件）参数暴露了对核心代理循环的深层控制权 。这允许开发人员根据特定的企业要求，实现如动态模型选择、安全防护（Guardrails）或人机协作（Human-in-the-Loop）等高级功能 。

1.3 概念概览：从传统架构到基于LangGraph的代理

早期LangChain版本依赖于枚举类型（如AgentType.ZERO_SHOT_REACT_DESCRIPTION）来定义代理的行为和提示模板 。然而，在现代create_agent的官方文档中，一个重要的观察是该函数没有提供显式的agent_type参数 。

这种参数的移除表明，底层的推理和行动逻辑已经通过LangGraph运行时实现了标准化和优化。这种运行时本质上倾向于使用高效且可靠的工具调用（Tool Calling） 范式，而非传统的基于文本的ReAct提示 。因此，开发者不再需要选择预设的提示模板（ReAct或Zero-Shot），而是通过统一的执行流，结合自定义的system_prompt和强大的middleware机制来进行定制。这种统一性极大地简化了生产部署和维护工作，因为开发者只需要关注定制单一的、高性能的执行流程。

第2节：LangGraph基础：基于图形的代理运行时

2.1 定义代理核心：结构化执行与状态管理

create_agent的核心优势在于其基于LangGraph构建的图形化代理运行时 。LangGraph定义了代理处理信息的精确方式，通过一系列节点（Nodes）和边（Edges）来描述执行流程 。

核心代理循环通常遵循Action-Observation（行动-观察）模式，该模式由以下步骤构成：输入（Input）-> 模型调用（Reasoning）-> 工具执行（Action）-> 观察结果（Observation）-> 重复，直至终止（Finish） 。LangGraph负责管理这些节点之间的精确状态转移。

图形化结构保证了结构化执行。这意味着代理的每一步操作都是明确界定和可预测的，这对于实现透明的调试（Tracing）和增强生产环境下的可靠性至关重要 。

2.2 了解LangGraph在create_agent中的作用：节点、边与状态管理

在LangGraph的框架中，代理的逻辑被分解为具体组件：

• 节点（Nodes）： 代表代理执行过程中的具体处理步骤 。这包括调用LLM的“模型节点”、执行外部操作的“工具节点”，以及用于定制逻辑的“中间件节点” 。
• 边（Edges）： 定义了执行流的路径和条件 。例如，如果模型响应请求进行工具调用，则执行流会沿着一条边转移到“工具节点”；如果模型提供了一个最终答案，则转移到“完成”节点。
• 状态管理： LangGraph的核心价值之一是内置的状态管理能力 。代理可以维护和更新上下文，这对于处理复杂的多步骤任务或需要等待人类反馈的人机协作场景至关重要。

2.3 LangGraph的关键优势：检查点、容错性与人机协作能力

LangGraph的底层设计赋予了create_agent强大的生产级特性：

1. 检查点（Checkpointing）： 检查点功能能够将代理的序列化状态（通道值，默认序列化为MsgPack，可选加密）保存在持久化存储中 。这允许代理流程在任何机器上、经过任意时长（可能是数天甚至数月）后从保存点精确恢复。这对于长时间运行的服务和MLOps的流程管理至关重要 。
2. 容错性（Fault Tolerance）： 检查点是实现容错性的基础。如果代理执行过程中发生意外中断或故障，它可以自动从最近保存的检查点重启，确保任务的连续性和数据完整性 。
3. 人机协作（Human-in-the-Loop, HITL）： 检查点功能支持“预期中断”，即代理可以中断自身，等待用户或开发者的输入、审查或批准，然后再继续执行 。与简单地让进程挂起等待输入不同，这种机制通过保存状态并实际终止等待进程，解决了长时间等待任务（如几天或几个月）或同时中断大量代理时的规模化问题 。

第3节：核心配置：基本参数与动态组件

create_agent函数提供了一系列关键参数，用于定义代理的推理能力、行动范围和行为规范。

3.1 推理引擎（model）：静态配置与动态选择

model参数定义了代理的核心智能来源，即LLM。

• 静态模型配置： 这是最直接的配置方式。模型可以在创建代理时通过一个模型标识符字符串（例如，"anthropic:claude-sonnet-4-5"）指定 。或者，也可以传入一个已配置的模型实例（如ChatOpenAI），以实现对temperature、max_tokens或timeouts等参数的精细控制 。
• 动态模型选择： 对于需要进行成本优化和复杂路由的生产系统，模型可以在运行时根据当前的代理状态和上下文动态选择。这种高级功能是通过middleware框架和@wrap_model_call装饰器实现的 。在请求调用模型之前，中间件可以拦截请求并替换当前使用的模型实例，从而实现基于会话长度或任务类型的智能模型切换 。

3.2 行动层（tools）：定义与集成外部能力

tools参数接受一个工具列表，这些工具赋予了代理采取行动和获取外部信息的能力 。工具通常被定义为可调用的函数，通过明确的文档字符串（Docstrings）来向LLM描述其功能和参数，以便LLM进行准确的函数调用。如果提供的工具列表为空，那么create_agent将创建一个仅包含单个LLM节点的代理，不具备任何工具调用或行动能力 。

工具的使用遵循Action-Observation模式 ，即模型决定调用工具，代理执行工具，并将工具的输出（Observation）反馈给模型进行下一步推理。

3.3 塑造行为（system_prompt）：有效指令的原则

system_prompt参数是一个字符串，用于定义代理的角色、行为、语气和对任务的一般方法 。有效的系统提示应该具体且具有可操作性 。与模型一样，系统提示也可以通过middleware进行动态修改或注入额外的上下文，以适应会话流程中的状态变化 。

3.4 核心参数介绍

下表总结了create_agent函数的关键配置参数及其在生产代理中的作用。

核心 create_agent 参数参考表

参数	类型/结构	在生产代理中的目的	关键设计要点
model	模型标识符（字符串）或模型实例	定义推理引擎，影响代理的智能和运行成本。	支持静态配置或通过中间件实现动态切换 。
tools	可调用函数列表或ToolNode实例	赋予代理执行外部行动和收集观察结果的能力。	如果列表为空，则代理仅作为对话LLM运行 。
system_prompt	字符串	确定代理的角色、约束和行为规范。	对于塑造代理的行为至关重要；可通过中间件动态修改 。
response_format	Schema类型或策略	强制代理返回结构化数据，确保下游应用的可靠性。	支持提供商原生策略或工具调用策略进行输出验证 。
middleware	中间件对象列表	在核心代理循环的各个阶段提供自定义钩子。	生产中实现安全防护、错误处理和状态操作的关键 。
state_schema	Pydantic BaseModel（可选）	定义自定义状态组件，主要供工具访问和使用。	推荐通过中间件定义高级自定义状态 。

第4节：高级输出控制：结构化数据与响应格式

4.1 结构化输出在代理工作流中的重要性

在生产应用中，从LLM获取可预测的、机器可读的结果至关重要。结构化输出确保了下游应用（如API、数据库或报告生成系统）接收到经过验证的格式化数据（如JSON对象、Pydantic模型或Dataclass），从而避免了依赖不稳定的自然语言解析 。

通过配置结构化输出，代理会在其最终状态中捕获、验证并返回结构化数据，该数据被放置在状态的特定键中，即'structured_response' 。

4.2 response_format参数的深入分析

response_format参数用于指定所需的输出结构。它接受具体的Schema类型，包括Pydantic BaseModel、Python Dataclass、TypedDict，或者原始的JSON Schema 。

从类型定义上看，该参数是一个联合类型（Union），允许传入一个具体的Schema类型或特定的策略对象：Union,None] 。

4.3 策略比较：优化可靠性与性能

LangChain设计了一个可靠性层级结构，旨在自动选择最可靠的结构化输出方法。当开发者直接传入Schema类型时，系统会根据模型的兼容性自动选择策略 。

1. ProviderStrategy：提供商原生策略

提供商原生策略利用了现代LLM提供商（目前主要为OpenAI和Groq）在API层面提供的原生功能调用或JSON模式 。

• 机制： Schema约束由模型提供商的API本身强制执行。
• 可靠性： 最高。由于是提供商强制执行Schema验证，因此保证了极高的可靠性和严格的验证 。
• 应用优先级： 当模型支持原生结构化输出时，LangChain会自动优先选择此策略 。

2. ToolStrategy：工具调用策略

工具调用策略是一种模型无关的稳健方法，用作通用回退机制。

• 机制： 代理在内部流程中创建了一个额外的步骤，即要求LLM调用一个专门用于输出结构化数据的工具 。
• 可靠性： 稳健，适用于任何具备工具调用能力的模型。
• 应用场景： 当模型不原生支持结构化输出时，或者当开发者明确要求使用此方法时使用 。

在生产环境的实践中，选择支持原生结构化输出的模型（并使用ProviderStrategy）是最佳实践，因为由API强制执行的Schema约束比依赖模型在文本中遵循提示指导更为可靠，从而提高了系统的整体稳定性。

结构化输出策略比较表

特性	ProviderStrategy	ToolStrategy	生产部署考量
机制	原生API强制执行（JSON模式、函数调用） 。	代理显式调用内部工具返回结构化数据 。	最小化对纯文本解析的依赖。
模型依赖性	高（要求原生支持，如OpenAI, Grok） 。	低（适用于任何具备工具调用能力的模型） 。	为获得最大可靠性，应优先选择支持原生策略的模型。
验证	由模型提供商API强制执行的严格验证。	LangChain在工具输出后执行验证 。	保证输出结构的高可靠性。
效率	高效，通常只需一次API调用。	效率略低（模型需要执行一次工具调用步骤）。	在原生支持的模型中获得性能提升。

第5节：使用中间件扩展代理逻辑

5.1 中间件框架：定制执行控制的钩子

middleware参数是create_agent提供的高级定制核心。中间件提供了一组可定制的钩子（Hooks），环绕在核心代理循环（尤其是模型调用和工具执行）的周围 。

中间件的主要能力包括：

• 监控与分析： 添加自定义日志记录和指标追踪。
• 修改与转换： 在模型调用前对提示词进行预处理（如消息修剪、上下文注入），或在模型响应后对其输出进行后处理（如内容过滤、安全防护） 。
• 流程控制： 实现重试机制、回退逻辑、早期终止和人机协作中断 。
• 安全与合规： 应用速率限制、身份信息（PII）检测、以及合规性检查 。

5.2 使用 @wrap_model_call 实现动态模型选择

动态模型选择是一种关键的生产优化手段，它允许代理根据当前任务或会话的复杂性在不同的LLM之间切换，从而实现成本效益最大化。

实现动态模型的机制在于创建实现了wrap_model_call方法的自定义中间件 。当代理准备调用LLM时，wrap_model_call方法会拦截该请求 (ModelRequest) 。

该方法的工作流程如下：它检查当前请求的状态，例如对话中的消息数量 (len(request.messages)) 。根据预设逻辑（例如，如果消息超过10条），中间件会动态地修改请求对象中的模型设置，将其从一个成本较低的模型（如GPT-4o-mini）切换到一个更强大的模型（如GPT-4o），然后将修改后的请求传递给原始处理程序 (handler(request)) 执行 。

这种设计模式的关键在于解耦：它将代理的核心推理结构（LangGraph流）与操作基础设施逻辑（成本控制、安全防护、路由）分离。中间件成为企业集成、满足 MLOps 要求和实施内部业务逻辑（例如，在执行工具之前进行授权检查）的主要接入点。

5.3 生产就绪的关键内置中间件

LangChain提供了一系列预构建的中间件，用于解决常见的生产挑战 ：

• 人机协作 (Human-in-the-loop): 允许在工具调用执行前暂停代理流程，等待人类的批准、编辑或拒绝。值得注意的是，此功能需要配置检查点（checkpointer） 来持久化状态，以便处理可能发生的长时间中断 。
• 模型调用限制 (Model call limit) 和 工具调用限制 (Tool call limit): 用于防止代理陷入无限循环或过度使用昂贵的工具，是控制成本和防止拒绝服务（DoS）场景的关键 。
• 摘要 (Summarization): 在接近上下文窗口限制时，自动对对话历史进行摘要处理，以保持对话流畅性 。
• 模型回退 (Model fallback): 当主模型发生故障或超时时，自动切换到备用模型以增强韧性 。
• PII检测 (PII detection): 检测和处理对话中的个人身份信息，以满足数据安全和合规要求 。

生产中间件能力表

中间件示例	目的	机制/钩子	生产价值
动态模型选择	根据任务复杂度和上下文切换LLM。	使用@wrap_model_call修改ModelRequest中的模型 。	成本优化和资源智能分配。
人机协作	暂停执行以进行外部审查或批准。	拦截执行流；要求检查点实现状态持久化 。	高风险行动和监管合规的关键。
PII检测	扫描消息/输出中的敏感数据。	基于检测结果修改输入/输出状态 。	满足安全和数据合规性要求（如GDPR）。
工具调用限制	阻止无限循环或昂贵工具的滥用。	对工具使用次数实施约束 。	成本控制和流程稳定性保障。
工具重试	自动重新尝试运行失败的工具步骤。	透明地处理工具执行失败 。	增强代理的整体韧性和容错能力。

第6节：稳健的工具管理与错误恢复

6.1 最大化代理效用的工具定义

工具是代理执行外部动作的基础。它们通常是使用@tool装饰器定义的Python可调用函数，清晰的文档字符串被用来定义工具的Schema和用途，供LLM在函数调用时参考 。

6.2 定制工具错误处理策略的必要性

在生产环境中，外部工具（例如数据库连接、API调用）不可避免地会遭遇故障，如连接超时、业务逻辑限制或临时错误 。为了防止代理在外部故障时崩溃，必须具备可靠的错误处理和恢复策略 。

6.3 利用 ToolNode 和 handle_tool_errors 实现优雅故障恢复

create_agent的tools参数可以接受一个ToolNode实例，这是一个专门负责在LangGraph中处理工具执行的节点 。ToolNode允许通过handle_tool_errors参数定义一个自定义的错误处理函数 。

恢复机制： 当工具执行中抛出异常（例如ConnectionError或ValueError）时，自定义的错误处理函数会拦截该异常 。该函数不会让代理失败，而是根据异常类型（例如，判断是临时连接错误还是永久性的数值错误），返回一个格式化后的、具有指导意义的字符串。这个字符串随后作为“观察结果（Observation）”反馈给LLM 。

例如，如果遇到数据库连接超时，处理函数可以返回“数据库当前过载，但重试是安全的，请用相同的参数重试” 。LLM接收到此观察结果后，可以基于此信息进行下一步推理（例如，决定是否重试或修改策略），从而实现从外部故障中的优雅恢复。这种机制将故障处理提升到推理层面，而不是简单的技术故障捕获。

第7节：背景分析：create_agent与传统代理的对比

7.1 LangChain中代理设计的演变

LangChain的代理架构经历了一次重大的演变。在LangGraph出现之前，代理主要依赖于固定的提示模板（如ReAct、Zero-Shot） 。这些早期架构在状态管理、检查点和可靠的文本输出解析方面存在固有挑战 。

create_agent的出现标志着代理进入了基于图形、有状态的运行时时代，它通过结构化执行（LangGraph）和对现代LLM原生能力（Tool Calling）的利用，极大地提升了效率和可靠性 。

7.2 对比代理架构：ReAct vs. 函数调用（Tool Calling）

理解create_agent的设计理念，必须理解传统ReAct代理与现代Tool Calling代理之间的根本区别。

1. 传统ReAct代理（基于文本的推理）

• 提示策略： 要求LLM通过自然语言进行“逐步思考”，并在输出中明确包含Thought（思考）、Action（行动）和Observation（观察）的步骤 。
• 机制： 整个过程是文本驱动的、迭代的对话。
• 缺点： 过程冗长、占用大量Token，且对Action步骤的文本解析容易出错且不可靠。

2. 现代Tool Calling代理（基于函数的调用）

• 提示策略： 向LLM提供结构化的函数Schema，并指令其“使用结构化数据直接调用这些函数” 。
• 机制： LLM响应的是一个干净、结构化的JSON/字典对象，包含工具名称和参数 。
• 优点： 清晰、高效、参数传递可靠性高。

7.3 create_agent如何封装现代工具调用范式

create_agent本质上采用了Tool Calling的效率优势，并将其嵌入到LangGraph的架构稳定性中。这种架构上的选择具有重要的运营意义。

由于create_agent采用Function-Based（函数式）的方法，LLM不需要像ReAct那样冗长地阐述其思考过程。决策制定过程在模型内部发生（隐式推理），这使得代理运行速度更快，Token使用量更少，从而实现更高的效率和更低的运营成本 。

这意味着在使用create_agent进行生产部署时，开发者不能依赖文本输出中的Thought步骤来理解代理的决策过程。相反，必须利用专用的追踪工具（如LangSmith）或自定义的中间件日志，才能深入检查代理在图形流中的每一步状态和决策。

架构对比：传统代理与现代代理

特性	传统 ReAct 代理（基于文本）	传统 Tool Calling 代理（基于函数）	现代 create_agent（基于图形）
核心架构	模板驱动的文本循环。	专门用于函数调用的链。	由LangGraph管理的状态机 。
效率/Token使用	低（冗长，高Token消耗） 。	高（结构化，简洁的函数调用） 。	极高（利用Tool Calling，优化流程）。
推理透明度	显式（Thought步骤可见） 。	隐式（模型内部决策） 。	可通过追踪工具或中间件日志管理。
状态管理	有限（通常仅序列化链记忆）。	有限（通常仅序列化链记忆）。	完整的状态管理、检查点和容错性 。
定制性	低（受限于提示模板）。	中等（受限于链组件）。	极高（通过中间件钩子深度控制） 。
生产适用性	可靠性和效率较低。	性能高，但依赖特定模型。	最佳：提供全面的状态、可靠性和定制能力 。

第8节：实施工作流与高级最佳实践

8.1 综合Python实施示例

构建一个基于create_agent的生产代理涉及定义工具、配置模型，并使用关键参数初始化代理。

Python

from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

# 1. 定义工具 (Tools)
@tool
def get_weather(city: str) -> str:
    """获取给定城市的当前天气信息。"""
    return f"It's always sunny in {city}!"

# 2. 配置模型和系统提示
MODEL_NAME = "openai:gpt-4o-mini"
SYSTEM_PROMPT = "你是一个专业且乐于助人的天气助理，只能使用提供的工具回答问题。"

# 3. 创建代理
agent = create_agent(
    model=MODEL_NAME,
    tools=[get_weather],
    system_prompt=SYSTEM_PROMPT,
)

# 4. 运行代理
result = agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

# 结果将包含代理的最终响应和执行路径。

在实际部署中，模型配置可以更详细，例如：通过init_chat_model来设置具体的temperature、timeout和max_tokens等参数 。

8.2 高级实施：结构化输出示例

当需要代理返回特定格式（如用于API调用的JSON）时，可以使用response_format参数。

Python

from dataclasses import dataclass
from typing import List
from langchain.agents import create_agent

# 定义结构化输出Schema (可以使用Pydantic BaseModel 或 Dataclass)
@dataclass
class ProductReview:
    product_name: str
    summary: str
    rating: int
    key_features: List[str]

# 创建代理，要求它使用定义的Schema返回数据
# LangChain将自动选择 ProviderStrategy 或 ToolStrategy 
agent_with_structured_output = create_agent(
    model="openai:gpt-4o",  # 假设此模型支持 ProviderStrategy
    tools=,  # 不需要工具，只需要结构化输出
    system_prompt="你是一名专业的产品评论摘要员。",
    response_format=ProductReview,
)

# 代理的最终结果将包含 ProductReview 实例在 'structured_response' 键中 。

8.3 故障排除与最佳实践

为了确保create_agent在生产中的高可用性和稳定性，应遵循以下实践：

1. 最大化结构化可靠性： 优先选择支持提供商原生结构化输出的模型（如某些OpenAI或Groq模型），并直接传递Schema类型 。这最大限度地减少了因LLM生成文本不合规导致的Schema验证错误 。
2. 实施健壮的错误处理： 对于所有外部工具，应使用ToolNode并配置handle_tool_errors函数 。这使得代理能够在遇到连接错误或业务逻辑异常时，通过LLM的推理步骤进行自我恢复或策略调整。
3. 防止失控的成本： 在代理中集成Model call limit和Tool call limit中间件 。这可以有效地对代理的迭代次数设置上限，防止其在遇到复杂或模糊任务时陷入无限循环，从而控制运营成本。

结论与建议

langchain.agents.create_agent函数提供了一个基于LangGraph架构的、统一且高度可定制的LLM代理实现。它代表了LangChain从传统的模板驱动、基于文本的ReAct代理向现代的、基于图形和函数调用的高可靠系统的根本性转变 。

对于寻求将LLM代理部署到生产环境的技术团队，create_agent是首选方案，原因在于其架构固有的几个优势：

1. 状态管理与容错性： 通过LangGraph的检查点机制，代理具备了真正的状态持久化和故障恢复能力，支持人机协作和长时间运行的复杂任务 。
2. 效率与可靠性： 该函数隐式地利用了现代LLM高效的Tool Calling范式，并结合了ProviderStrategy来强制执行结构化输出，从而在保证输出格式可靠性的同时，最大限度地提高了执行效率 。
3. 无与伦比的定制深度： middleware框架提供了对代理执行流程的细粒度控制，使得实施成本优化（动态模型选择）、安全防护（PII检测）和业务逻辑集成成为可能，而无需修改核心代理逻辑 。

因此，建议MLOps工程师和架构师将create_agent视为构建所有生产级LangChain代理的标准接口。在实施复杂逻辑时，应将中间件作为主要的扩展点，并确保工具通过ToolNode集成，以实现企业级所需的故障恢复能力。

第9节：参考来源

Langchain官方文档-Agent:
https://docs.langchain.com/oss/python/langchain/agents

Langchain官方文档-Quickstart:
https://docs.langchain.com/oss/python/langchain/quickstart

Langchain官方文档-middleware: https://docs.langchain.com/oss/python/langchain/middleware

Langchain官方文档-如何自定义tools:
https://python.langchain.com/docs/how_to/custom_tools/

Langchain官方文档-结构化输出：
https://docs.langchain.com/oss/python/langchain/structured-output

Langchain官方文档-AgentType介绍（已废弃）:
https://api.python.langchain.com/en/latest/agents/langchain.agents.agent_types.AgentType.html

Langchain官方文档-LangGraph介绍:
https://docs.langchain.com/oss/python/langgraph/overview

Understanding LangChain Agents: create_react_agent vs create_tool_calling_agent: https://medium.com/@anil.goyal0057/understanding-langchain-agents-create-react-agent-vs-create-tool-calling-agent-e977a9dfe31e

Building LangGraph: Designing an Agent Runtime from first principles: https://blog.langchain.com/building-langgraph/