LangChain create_agent 详解

create_agent 是 LangChain 用来创建 Agent 的工厂函数。它把语言模型、工具、提示词、状态、持久化和中间件组合成一个可执行的 Agent 图。

1. create_agent 是做什么的

从功能上看，create_agent 用于创建能够反复执行“模型判断 → 调用工具 → 获取结果 → 再次判断”的 Agent。

用户问题
   ↓
语言模型判断是否需要工具
   ↓
需要工具 ──→ 执行工具 ──→ 工具结果加入消息
   │                            │
   └──────── 语言模型再次判断 ←──┘
                ↓
          最终回答

当前官方 API 返回的是一个编译后的 Agent 图，类型是 CompiledStateGraph。当模型返回工具调用时，Agent 会执行工具，并把工具结果作为 ToolMessage 加回消息列表，然后继续调用模型；当模型不再请求工具时，流程结束。LangChain 官方 API Reference

2. 函数签名

题目中的函数签名可以按以下方式理解：

from langchain.agents import create_agent

agent = create_agent(
    model,                     # str | BaseChatModel：语言模型
    tools=None,                # Sequence：工具列表
    *,
    system_prompt=None,        # str | SystemMessage：系统提示
    middleware=(),             # Sequence[AgentMiddleware]：中间件列表
    response_format=None,      # ResponseFormat | type：结构化输出配置
    state_schema=None,         # type[AgentState]：自定义状态结构
    context_schema=None,       # 运行时上下文结构
    checkpointer=None,         # Checkpointer：对话持久化
    store=None,                # BaseStore：跨会话存储
    interrupt_before=None,     # list[str]：在哪些节点前暂停
    interrupt_after=None,      # list[str]：在哪些节点后暂停
    debug=False,               # bool：是否输出详细日志
    name=None,                 # str：Agent 名称
    cache=None,                # BaseCache：缓存配置
    transformers=None,         # 当前版本额外支持的流转换器
)

transformers 未出现在题目给出的签名中，但当前官方参考文档的签名已经包含该参数。因此，在具体项目中应以当前安装版本的 API 为准。

3. 参数总览

参数	类型	功能	常见用途
model	str | BaseChatModel	指定 Agent 使用的语言模型	决定理解、规划和回答能力
tools	Sequence 或 None	提供 Agent 可以调用的工具	搜索、数据库、API、计算、文件操作
system_prompt	str | SystemMessage | None	设置 Agent 的身份、规则和行为边界	角色设定、回答规范、安全约束
middleware	Sequence[AgentMiddleware]	在模型调用、工具调用等环节插入逻辑	日志、重试、权限、限流、动态提示词
response_format	ResponseFormat 或类型	要求 Agent 返回结构化结果	JSON、Pydantic 模型、分类结果
state_schema	type[AgentState]	扩展 Agent 的运行状态字段	保存用户 ID、任务状态、中间结果
context_schema	类型	定义一次运行可以传入的上下文	用户信息、租户信息、运行配置
checkpointer	Checkpointer	保存单个线程或会话的状态	多轮对话、暂停后恢复
store	BaseStore	保存跨线程、跨用户的长期数据	用户偏好、长期记忆、共享数据
interrupt_before	list[str]	在指定节点执行前暂停	工具执行前人工确认
interrupt_after	list[str]	在指定节点执行后暂停	工具执行后审核或二次处理
debug	bool	输出更详细的图执行信息	调试流程、检查状态变化
name	str	设置 Agent 图的名称	多 Agent、子图、追踪和识别
cache	BaseCache	为图执行配置缓存	减少重复计算和调用成本
transformers	Sequence[TransformerFactory]	注册流式输出转换器	控制流输出、处理工具调用流

4. 核心参数详解

4.1 model：Agent 的大脑

model 可以传入模型字符串，也可以传入已经创建好的聊天模型实例。

传入模型字符串

from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
)

模型字符串通常使用 provider:model 的形式，例如：

openai:gpt-5.5
anthropic:claude-sonnet-4-5-20250929

使用字符串时，通常还需要安装对应的 Provider 集成包，并配置 API Key。

传入聊天模型对象

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

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

两种方式的区别：

方式	优点	适合场景
模型字符串	简洁，方便切换 Provider	快速原型、配置驱动
模型实例	可精确配置模型参数	生产项目、复杂模型配置

4.2 tools：Agent 能做什么

工具可以是普通 Python 函数、LangChain 工具对象或工具描述字典。

from langchain.agents import create_agent


def add(a: int, b: int) -> int:
    """计算两个数字的和。"""
    return a + b


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[add],
)

工具的文档字符串非常重要。模型通常会根据工具名称、参数类型和描述决定是否调用它。

一个好的工具应该具备：

• 清晰的名称。
• 准确的参数类型。
• 具体的文档字符串。
• 明确的返回值。
• 合理的错误处理。
• 最小必要权限。

如果 tools=None 或传入空列表，Agent 仍然可以调用模型，但不会执行工具调用循环。

4.3 system_prompt：定义 Agent 的行为

system_prompt 会作为系统消息放在消息列表开头。

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[add],
    system_prompt=(
        "你是一个严谨的数学助手。"
        "计算问题必须调用工具，不要心算。"
        "回答时说明计算结果。"
    ),
)

系统提示词通常可以规定：

• Agent 的角色。
• Agent 的目标。
• 什么时候调用工具。
• 不能做什么。
• 输出格式和语言。
• 安全和权限边界。

需特别说明的是，system_prompt 不能替代工具权限控制。涉及风险的操作仍然需要在工具代码和业务服务端进行校验。

4.4 middleware：在 Agent 流程中插入逻辑

中间件可以拦截或修改 Agent 的运行过程，例如：

• 调用模型前修改消息。
• 调用工具前进行权限检查。
• 工具失败后自动重试。
• 记录模型和工具调用日志。
• 根据上下文动态选择模型。
• 限制模型调用次数。
• 对输出进行审核。

概念上可以理解为：

请求
  ↓
Middleware before
  ↓
模型或工具执行
  ↓
Middleware after
  ↓
结果

中间件更适合承载通用能力，而不是具体业务流程。例如，“所有工具都需要权限检查”适合放进中间件；“本次订单必须先查询库存”则更适合放进明确的业务流程节点。

4.5 response_format：让结果结构化

默认情况下，Agent 主要通过消息返回自然语言结果。使用 response_format 可以要求模型返回结构化数据。

from pydantic import BaseModel, Field
from langchain.agents import create_agent


class TicketClassification(BaseModel):
    category: str = Field(description="问题分类")
    priority: str = Field(description="优先级")
    reason: str = Field(description="分类原因")


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    response_format=TicketClassification,
)

结构化结果通常可以从返回状态中的 structured_response 字段读取：

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "用户无法登录，已经影响生产，请分类。"}
    ]
})

classification = result["structured_response"]
print(classification.category)

适合使用结构化输出的场景：

• 意图分类。
• 信息抽取。
• 表单填写。
• 任务路由。
• 结构化报告。
• 给其他程序提供可靠输入。

4.6 state_schema：定义 Agent 的运行状态

Agent 的状态可以理解为 Agent 在执行过程中共享的“工作记录”。默认状态通常包含消息列表等基础字段；如果业务需要更多字段，可以定义自定义状态。

from typing_extensions import NotRequired
from langchain.agents import AgentState, create_agent


class MyAgentState(AgentState):
    user_id: NotRequired[str]
    order_id: NotRequired[str]
    risk_level: NotRequired[str]


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    state_schema=MyAgentState,
)

适合放进状态的数据包括：

• 当前消息。
• 当前任务 ID。
• 分类结果。
• 工具执行结果。
• 风险等级。
• 需要人工审核的标记。

不宜把所有可以即时计算的数据都放进状态。状态应主要保存跨步骤需要复用、重新获取成本较高或必须保留的数据。

4.7 context_schema：传入本次运行的上下文

context_schema 描述一次运行时传入的上下文，例如用户 ID、租户 ID、运行模式或权限信息。

from typing_extensions import TypedDict
from langchain.agents import create_agent


class RuntimeContext(TypedDict):
    user_id: str
    tenant_id: str
    mode: str


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    context_schema=RuntimeContext,
)

上下文可以在调用 Agent 时传入：

result = agent.invoke(
    {"messages": [{"role": "user", "content": "查询我的订单"}]},
    context={
        "user_id": "user-001",
        "tenant_id": "tenant-001",
        "mode": "production",
    },
)

需要区分：

概念	作用
state_schema	Agent 执行过程中持续变化的状态
context_schema	本次运行开始时提供的上下文配置
checkpointer	保存某个线程的执行状态
store	保存跨线程、跨会话的长期数据

4.8 checkpointer：保存单个会话

checkpointer 用于保存某个线程的状态，适合多轮对话和暂停后恢复。

from langgraph.checkpoint.memory import InMemorySaver
from langchain.agents import create_agent

checkpointer = InMemorySaver()

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    checkpointer=checkpointer,
)

config = {
    "configurable": {
        "thread_id": "conversation-001"
    }
}

agent.invoke(
    {"messages": [{"role": "user", "content": "我叫小明"}]},
    config,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "我叫什么？"}]},
    config,
)

其中，thread_id 用于标识会话，使 Checkpointer 能够判断哪些调用属于同一个线程。

InMemorySaver 主要适用于学习和测试；生产环境通常需要使用持久化存储。

4.9 store：保存跨会话数据

checkpointer 主要保存某一个线程的状态，store 则适合保存跨线程、跨用户或跨会话的数据。

简单理解：

checkpointer：这个对话进行到哪一步了？
store：这个用户长期偏好什么？

例如：

• 用户长期偏好。
• 用户的组织信息。
• 多个会话共享的业务配置。
• Agent 之间共享的长期知识。

对于普通多轮对话，使用 checkpointer 即可；需要跨会话共享数据时，再引入 store。

4.10 interrupt_before 和 interrupt_after：人工介入

这两个参数用于在图节点前后暂停执行。

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[send_email],
    interrupt_before=["tools"],
)

典型用途：

• 发邮件前让用户确认。
• 删除数据前让管理员审批。
• 转账前进行人工审核。
• 工具执行后检查结果。
• 高风险任务进入人工工作台。

使用暂停能力时通常还需要 Checkpointer 保存暂停前的状态，才能在之后恢复执行。

4.11 debug：查看执行过程

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[add],
    debug=True,
)

调试模式可用于学习和排错，主要可以观察：

• 模型什么时候被调用。
• 模型是否请求了工具。
• 工具接收了什么参数。
• 工具返回了什么结果。
• 状态如何发生变化。

生产环境不宜无条件输出全部详细内容，因为日志中可能包含用户隐私、密钥或业务数据。

4.12 name：给 Agent 图命名

research_agent = create_agent(
    model="openai:gpt-5.5",
    tools=[],
    name="research_agent",
)

name 在多 Agent 系统中尤其有用，可以帮助：

• 区分不同 Agent。
• 作为子图名称。
• 识别日志和追踪记录。
• 表示 Agent 的职责。

4.13 cache：缓存执行结果

cache 用于减少重复执行，适用于结果稳定且重复率较高的任务。

适合缓存的内容：

• 稳定的文档解析结果。
• 重复的只读查询。
• 成本较高但结果可复用的模型调用。

不适合直接缓存的内容：

• 实时库存。
• 实时天气。
• 用户权限。
• 付款和转账。
• 依赖当前时间的结果。

缓存必须考虑输入、用户权限、数据版本和过期时间，否则可能返回错误或越权的数据。

4.14 transformers：处理流式输出

当前官方接口还支持 transformers，用于向编译后的 Agent 图注册流转换器。

该参数主要用于处理：

• 流式消息转换。
• 工具调用事件转换。
• 自定义输出格式。
• 对流中的内容进行过滤或加工。

这是相对高级的参数。初学阶段可以先使用 stream() 的标准输出模式，待需要统一处理流事件时再使用该参数。

5. 最小可运行结构

下面给出一个最小 Agent 结构：

from langchain.agents import create_agent


def get_weather(city: str) -> str:
    """查询指定城市的天气。"""
    return f"{city}：晴天，25°C"


agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="你是天气助手。需要天气信息时调用天气工具。",
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "北京今天的天气怎么样？"}
    ]
})

print(result["messages"][-1].content)

这里的关键关系是：

model       → 负责判断和生成
tools       → 负责执行真实动作
system_prompt → 负责行为约束
invoke      → 启动 Agent 图
messages    → 保存交互过程

6. Agent 的执行过程

当用户提出一个需要调用工具的问题时，大致会发生以下步骤：

1. 接收 messages
2. 加入 system_prompt
3. 调用 model
4. 判断模型是否返回 tool_calls
5. 如果没有 tool_calls，直接结束
6. 如果有 tool_calls，执行对应 tools
7. 将工具结果写入 messages
8. 再次调用 model
9. 重复上述过程，直到模型给出最终回答

这就是常见的工具调用循环。create_agent 预置了循环控制、状态传递和工具节点。

7. 常见配置组合

7.1 普通问答 Agent

agent = create_agent(
    model=model,
    tools=[],
    system_prompt="你是一个知识问答助手。",
)

7. 工具调用 Agent

agent = create_agent(
    model=model,
    tools=[search_web, query_database, calculate],
    system_prompt="需要外部信息时优先调用工具。",
)

7. 多轮对话 Agent

agent = create_agent(
    model=model,
    tools=tools,
    checkpointer=checkpointer,
)

7. 结构化输出 Agent

agent = create_agent(
    model=model,
    tools=[],
    response_format=ResultSchema,
)

7. 需要人工确认的 Agent

agent = create_agent(
    model=model,
    tools=[send_email, delete_record],
    checkpointer=checkpointer,
    interrupt_before=["tools"],
)

7. 生产级 Agent

生产项目通常会组合：

model
  + tools
  + system_prompt
  + middleware
  + response_format
  + checkpointer
  + store
  + interrupt
  + tracing / logging
  + retry / timeout / permission control

8. create_agent 和旧接口的关系

在较新的 LangChain 版本中，推荐使用：

from langchain.agents import create_agent

一些旧教程会使用：

from langgraph.prebuilt import create_react_agent

或者：

from langchain_classic.agents import initialize_agent

官方参考文档将 create_react_agent 和 initialize_agent 标记为迁移方向上的旧接口，新的 Agent 通常应优先使用 langchain.agents.create_agent。create_agent 在保留工具调用循环的基础上，增加了更统一的中间件、结构化输出和 LangGraph 能力。LangChain Agents 参考文档

9. 常见误区

误区一：Agent 会自动拥有所有能力

Agent 只能调用传入的工具。没有搜索工具时，它无法真正搜索互联网；没有数据库工具时，它也无法查询数据库。

误区二：只靠 system prompt 就能保证安全

不能。安全控制必须在工具和服务端执行，例如检查用户身份、权限、参数范围和操作风险。

误区三：state_schema 就是长期记忆

不是。state_schema 是运行状态结构；要实现会话持久化，需要 checkpointer；要实现跨会话长期存储，需要 store。

误区四：所有问题都应该交给 Agent 自主决定

并非所有问题都需要 Agent。对于固定且可预测的业务流程，普通工作流通常更加合适；只有在需要动态选择工具或步骤时，才有必要引入 Agent。

误区五：工具越多越好

工具过多会增加模型选择难度、调用成本和错误概率。应该提供职责清晰、权限最小的工具。

10. 学习顺序

可以按照以下顺序掌握相关内容：

1. model：让 Agent 能够调用模型。
2. tools：让 Agent 能够执行真实动作。
3. system_prompt：约束 Agent 的行为。
4. invoke 和 stream：运行和观察 Agent。
5. response_format：获得稳定的结构化结果。
6. checkpointer：实现多轮对话。
7. middleware：加入重试、日志和权限逻辑。
8. interrupt_before：实现人工确认。
9. state_schema、context_schema 和 store：构建复杂应用。

11. 总结

create_agent = 模型 + 工具 + 提示词 + 状态 + 执行循环 + 可选的持久化与中间件

理解该函数的重点并非记住每个参数的名称，而是明确它们分别解决的问题：

• model 决定 Agent 如何理解和决策。
• tools 决定 Agent 能够做什么。
• system_prompt 决定 Agent 应该遵守什么规则。
• middleware 决定如何控制 Agent 的执行过程。
• state_schema 和 context_schema 决定 Agent 如何管理数据。
• checkpointer 和 store 决定数据保存多久、在哪些会话之间共享。
• interrupt 决定什么时候交给人确认。

参考资料

• LangChain 官方 create_agent API Reference
• LangChain 官方 Agents Reference
• LangChain 官方 Python 文档