create_agent

手写「model → tool_calls → ToolMessage → 再 model」循环，还要处理 max_iterations 与路由，样板代码多。create_agent（v1）用一行创建可执行工具循环的 Agent 图：传入 model 与 tools，内部基于 LangGraph 跑 ReAct 式循环，适合快速原型。

段末注释：create_agent = LangChain v1 标准 Agent 工厂；ReAct（Reasoning and Acting）= 交替推理与调用工具的 Agent 模式。

1. 一句话定位

维度	内容
角色	能力层预构建 Agent：工具循环 + 消息 state
输入 → 输出	`{"messages": [...]}` → `{"messages": [...]}`（含最终 AI 回复）
典型调用入口	`from langchain.agents import create_agent`
与 LangGraph	内部即 LangGraph 图；自定义环/checkpoint 再 drop down 到 LangGraph API

2. 实现逻辑

1. agent = create_agent(model="openai:gpt-4o-mini", tools=[t1, t2], system_prompt="...")
2. agent.invoke({"messages": [{"role":"user", "content":"..."}]})
3. 图节点 model：读 messages → AIMessage（可能 tool_calls）
4. 条件边：有 tool_calls → ToolNode 执行 → ToolMessage 追加
5. 无 tool_calls → END，返回完整 messages
6. 可选 response_format=Schema 以结构化对象结束

字段级变形：

1
2
3

messages: [HumanMessage("2+3?")]
  → ... tool_calls multiply ...
  → [..., ToolMessage("5"), AIMessage("答案是5")]

3. 原理说明

3.1 v1 相对 create_react_agent

迁移：langgraph.prebuilt.create_react_agent → langchain.agents.create_agent。参数 prompt 更名为 system_prompt。

create_agent(...)（函数）
功能：预构建 ReAct 风格工具循环（内部 LangGraph + ToolNode）。

参数	类型	默认值	最小维度
`model`	str / BaseChatModel	必填	非空；字符串形如 `"openai:gpt-4o-mini"`
`tools`	list	`[]` / 必填视版本	有工具任务时 len≥1
`system_prompt`	str / None	`None`	建议非空短指令
`response_format`	BaseModel / None	`None`	若用则 ≥1 字段
`middleware`	list / None	`None`	可空

agent.invoke(state, config=None)（方法）
输入最小结构：{"messages": [HumanMessage(...)]}，messages len ≥ 1。
输出：{"messages": [...]}，含本轮新增的 AI / Tool 消息。

1
2
3

from langchain.agents import create_agent
agent = create_agent(model=model, tools=[add], system_prompt="需要计算时必须调用 add。")
agent.invoke({"messages": [HumanMessage("3 加 19")]})

3.2 model 字符串

init_chat_model(model)（函数，内部使用）
功能：解析 "provider:model"。最小：1 个含冒号的字符串，或直接传 ChatModel 实例（此时不走该函数）。

1	create_agent(model="openai:gpt-4o-mini", tools=[add])

3.3 middleware（进阶）

v1 可通过 middleware 挂 before_model / after_model。列表可空。本篇不展开钩子签名，见官方 Agents 文档。

3.4 何时上图自定义

需要 checkpoint、interrupt、多节点审批时上 LangGraph。标准工具循环用 create_agent 即可。
recursion_limit 默认 25（RunnableConfig），防止死循环；最小有意义 ≥ 工具轮次数 × 2。

4. 最小可运行示例

1	pip install -U langchain langchain-openai langgraph

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

@tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

model = ChatOpenAI(
    model="qwen3.5:9b",
    api_key="ollama",
    base_url="http://localhost:11434/v1",
    temperature=0,
)
agent = create_agent(model=model, tools=[add], system_prompt="需要计算时必须调用 add 工具。")
result = agent.invoke({"messages": [HumanMessage("3 加 19 等于多少？")]})
for m in result["messages"]:
    print(type(m).__name__, getattr(m, "tool_calls", None) or m.content)
# 预期形态：含 HumanMessage → AIMessage(tool_calls=add) → ToolMessage → 最终 AIMessage 含 22

重要配置参数

参数（API 名）	类型 / 默认值	功能说明	作用与影响	参考起点	配置指导
`model`	str / BaseChatModel，必填	Agent 推理用的 Chat 模型	小模型够工具任务；字符串走 `provider:model`	gpt-4o-mini	与 tools 能力匹配
`tools`	list，可空	注册进循环的可调用工具	过多降选工具准确率；未注册会被幻觉	3～10 个	只放本任务需要的
`system_prompt`	str / None	系统指令（v1 已废弃旧名 `prompt`）	过长费 token；过短模型不调工具	短而明确	写清「何时必须调工具」
`response_format`	Pydantic，可选	循环结束时按 schema 产出终态	与工具循环兼容性因模型而异，需实测	按需	字段尽量少
`recursion_limit`	config，默认 25	图/循环最大步数	防死循环；过小复杂题答不完	25	约 ≥ 工具轮次 × 2
middleware	list，可选	在 before_model / after_model 挂钩子	可动态改 prompt；写错易递归	官方示例	动态 prompt 才需要

5. 易踩坑

仍 import create_react_agent：v1 新代码用 create_agent。
messages 用错格式：支持 dict role/content，但 tool 轮需完整 ToolMessage。
工具未出现在 bind 列表：模型幻觉出未注册 name，循环报错或空转。

小结

create_agent 是 v1 标准 Agent 入口，内置工具循环（LangGraph）。
参数：model、tools、system_prompt。
输入输出均为 messages state。
复杂编排与 checkpoint 见 LangGraph 目录。