create_react_agent（弃用）

弃用：langgraph.prebuilt.create_react_agent 在 LangGraph v1 弃用。官方替代是 langchain.agents.create_agent（底层仍是 LangGraph 的 agent ⇄ tools 环，并加上 middleware）。新项目不要再从 langgraph.prebuilt 导入。

段末注释：create_agent = LangChain v1 标准 Agent 工厂；返回值仍是 CompiledStateGraph，invoke / stream / get_state 与手写图相同。

社区方案：官方 LangGraph v1 迁移。风险：动态 prompt / pre-post hook 不能原样搬，要改成 middleware；预绑定 model.bind_tools 的实例不再直接传入。

从零画 llm ↔ tool 环很繁琐。标准工具循环用 create_agent；复杂审批 / 多角色仍手写 StateGraph 或把 create_agent 产物当 Subgraph 节点。

---

1. 定位

维度	内容
角色	预构建 ReAct Agent 图
输入 → 输出	messages in → messages out（含 tool 回合）
核心 API	旧：create_react_agent；新：langchain.agents.create_agent
依赖 LangChain	BaseChatModel、@tool 或 callable tools

---

2. 图拓扑（预构建内部）

节点表（概念）

节点名	职责	读	写
agent	调 LLM 决策	messages	messages
tools	执行 tool	messages	messages

边表（概念）

源	目标	类型
START	agent	固定
agent	tools / END	条件
tools	agent	固定

---

3. invoke 生命周期

1. 用户 messages 进入
2. agent 节点：LLM 返回 tool_call 或最终文本
3. 若有 tool_call → tools 节点 → 结果 append → 回到 agent
4. 无 tool_call → END

含环时至少 2 轮 agent↔tools（若 LLM 连续调工具）。

---

4. 原理

4.0 替代：create_agent

from langchain.agents import create_agent
from langchain_core.tools import tool
from langgraph.checkpoint.memory import InMemorySaver


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


agent = create_agent(
    model="openai:gpt-4.1-mini",  # 或 BaseChatModel 实例
    tools=[add],
    system_prompt="需要计算时必须调用 add。",
    checkpointer=InMemorySaver(),
)
cfg = {"configurable": {"thread_id": "react-v1"}}
out = agent.invoke({"messages": [{"role": "user", "content": "2+3"}]}, cfg)
print(out["messages"][-1].content)

返回的仍是 CompiledStateGraph：同一 thread_id 多次 invoke 会 get_tuple / put。无真实模型时用 §5 的 mock 图对照拓扑。

旧 create_react_agent	新 create_agent
from langgraph.prebuilt import create_react_agent	from langchain.agents import create_agent
prompt=	system_prompt=（str 或 SystemMessage）
动态 prompt 回调	@dynamic_prompt middleware
pre_model_hook / post_model_hook	middleware 的 before_model / after_model
AgentState / Pydantic 变体	langchain.agents.AgentState；扩展用 state_schema 或 middleware
预 model.bind_tools(...)	传入未绑定 model 或 model 字符串；绑工具由工厂完成
工具错误自己处理	wrap_tool_call middleware
结构化输出旧参数	response_format=（ToolStrategy / ProviderStrategy / Pydantic）
HITL 旧 HumanInterrupt*	langchain.agents.middleware 的 HITL middleware

定制超出 middleware（任意条件边、多角色 Supervisor）→ 手写 StateGraph，或把 create_agent(...) 当节点挂进主图。

4.1 与手写图等价

create_agent 内部仍是：agent（调模型）⇄ tools（ToolNode），条件边看是否还有 tool_calls。§5 mock 图即这张环。

4.2 checkpointer

create_agent(..., checkpointer=InMemorySaver()) 与手写 compile(checkpointer=...) 同一套 thread_id。

4.3 mock model

单测可继续用手写 mock agent 节点，不必打真实 API。

---

5. 最小可运行示例（mock，无真实 LLM）

from typing import Annotated, Sequence, TypedDict

from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage
from langchain_core.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition


class AgentState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]


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


tools = [add]
tool_node = ToolNode(tools)


def mock_agent(state: AgentState) -> dict:
    msgs = state["messages"]
    if len(msgs) == 1:
        return {
            "messages": [
                AIMessage(
                    content="",
                    tool_calls=[{"name": "add", "args": {"a": 2, "b": 3}, "id": "c1"}],
                )
            ]
        }
    return {"messages": [AIMessage(content="answer is 5")]}


builder = StateGraph(AgentState)
builder.add_node("agent", mock_agent)
builder.add_node("tools", tool_node)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition, {"tools": "tools", END: END})
builder.add_edge("tools", "agent")

graph = builder.compile(checkpointer=InMemorySaver())
cfg = {"configurable": {"thread_id": "react-mock"}}
out = graph.invoke({"messages": [HumanMessage(content="2+3")]}, cfg)
print(out["messages"][-1].content)

与 create_agent 内部拓扑一致。新项目用 §4.0 的工厂；本段只为对照环，不要再包一层 create_react_agent。

---

6. 执行追踪

轮次	节点	messages 变化
1	agent	+ AIMessage(tool_calls)
1	tools	+ ToolMessage(5)
2	agent	+ AIMessage(“answer is 5”)

---

重要配置参数

参数（API 名）	类型 / 默认值	功能说明	作用与影响	参考起点 / 常用范围	配置指导
create_agent(model, tools, ...)	工厂 → CompiledStateGraph	v1 标准 ReAct 环	替代 create_react_agent	langchain.agents	新代码只走这里
model	str / BaseChatModel	决策模型	字符串如 "openai:gpt-4.1-mini"	必填	不要先 bind_tools
system_prompt	str / SystemMessage / None	静态系统提示	旧参数名是 prompt	短指令	动态提示用 middleware
middleware	序列，默认 ()	替代 hook / 动态 prompt / HITL	可叠多个	before_model 等	先查官方预构建中间件
checkpointer	Saver / None	多轮 thread_id 记忆	不传则无跨 invoke 历史	InMemorySaver	生产换 DB
response_format	Schema / Strategy / None	结构化结束	旧 prompted 输出已移除	Pydantic 模型	按模型能力选 Strategy
tools_condition + ToolNode	手写图组件	§5 mock 环的路由与执行	工厂内部已包含	对照拓扑	不要和新工厂叠用

---

7. 易踩坑

1. 继续 from langgraph.prebuilt import create_react_agent：弃用警告，v2 将删除。
2. 仍传 prompt=：新工厂只要 system_prompt。
3. tool schema 与 args 不匹配：ToolNode / 工具校验失败。
4. 复杂分支硬塞预构建：middleware 不够就手写 StateGraph。

---

小结

• 新代码：from langchain.agents import create_agent；prompt → system_prompt，hook → middleware。
• 产物仍是 LangGraph 图；多轮照挂 checkpointer + thread_id。
• 定制超出工厂 → 手写 StateGraph；单测可用 §5 mock 环。

---

参考链接

• create_agent
• LangGraph v1 迁移
• Migrate to create_agent