【LangGraph】langgraph.prebuilt.create_react_agent() 函数：快速创建基于 ReAct（Reasoning + Acting）架构的智能代理

本文是对 langgraph.prebuilt.create_react_agent 函数的详细且全面的介绍，涵盖其定义、功能、设计理念、参数、返回值、使用场景、实现原理、示例代码、高级用法、注意事项、与其他方法的对比，以及学习建议。

---

1. 概述

langgraph.prebuilt.create_react_agent 是 LangGraph 库中的一个预构建函数，位于 langgraph.prebuilt 模块，用于快速创建基于 ReAct（Reasoning + Acting）架构的智能代理。LangGraph 是 LangChain 生态的扩展，专注于构建复杂、有状态的工作流，通过状态图（State Graph）管理节点和边，支持动态路由、循环和多代理协作。

ReAct 是一种结合推理和行动的代理架构，基于论文 ReAct: Synergizing Reasoning and Acting in Language Models。它通过语言模型（LLM）生成推理步骤（思考）和行动指令（工具调用），动态决定是否直接回答用户或调用工具获取信息。create_react_agent 封装了 ReAct 的标准逻辑，简化了代理的构建过程，使开发者无需手动定义状态图即可快速实现功能。

1.1 核心功能

• 快速构建 ReAct 代理：自动生成一个支持推理和工具调用的代理，基于 LLM 和工具列表。
• 状态管理：支持对话历史和中间结果的跟踪，适合多轮交互。
• 工具集成：与 LangChain 的工具生态无缝集成，支持搜索、计算、API 调用等。
• 流式输出：提供流式响应，增强实时交互体验。
• 状态持久化：通过检查点（checkpointer）支持有状态对话，保存和恢复上下文。
• 异步支持：支持异步执行，适合高并发或 I/O 密集型任务。

1.2 设计理念

• 简化和标准化：为开发者提供开箱即用的 ReAct 代理，降低复杂工作流的构建难度。
• 模块化：与 LangChain 的 LLM 和工具生态紧密集成，保持扩展性。
• 动态性：支持动态决策，代理根据输入和上下文选择推理或工具调用。
• 可控性：通过状态管理和检查点机制，提供清晰的上下文跟踪和调试能力。

---

2. 函数定义与参数

以下是 create_react_agent 函数的定义和参数：

from langgraph.prebuilt import create_react_agent

def create_react_agent(
    model: BaseLanguageModel,
    tools: Sequence[BaseTool],
    checkpointer: Optional[BaseCheckpointSaver] = None,
    state_modifier: Optional[Union[str, BasePromptTemplate]] = None,
    interrupt_before: Optional[List[str]] = None,
    interrupt_after: Optional[List[str]] = None,
    debug: bool = False,
    stream_mode: Literal["values", "messages"] = "values",
) -> CompiledGraph:
    """
    创建一个 ReAct 风格的代理。

    参数：
        model: 语言模型实例，用于生成推理和工具调用。
        tools: 工具列表，代理可调用以执行任务。
        checkpointer: 可选，检查点保存器，用于状态持久化。
        state_modifier: 可选，提示模板或字符串，用于自定义代理的行为。
        interrupt_before: 可选，指定在某些节点执行前中断。
        interrupt_after: 可选，指定在某些节点执行后中断。
        debug: 是否启用调试模式，输出详细日志。
        stream_mode: 流式输出模式，"values" 或 "messages"。

    返回：
        CompiledGraph: 编译后的状态图，可通过 invoke 或 stream 调用。
    """

2.1 参数详解

• model：
  • 类型：BaseLanguageModel（LangChain 的语言模型基类）。
  • 描述：用于生成推理和工具调用的 LLM，例如 ChatOpenAI(model="gpt-4")。
  • 要求：模型必须支持工具调用（Tool Calling），如 OpenAI 的 gpt-3.5-turbo 或 gpt-4。函数会自动绑定工具，无需手动调用 bind_tools。
• tools：
  • 类型：Sequence[BaseTool]（LangChain 工具列表）。
  • 描述：代理可调用的工具，例如搜索工具（DuckDuckGoSearchRun）、计算器或自定义 API 工具。
  • 示例：tools=[DuckDuckGoSearchRun(), Calculator()]。
• checkpointer：
  • 类型：Optional[BaseCheckpointSaver]。
  • 描述：用于保存和恢复状态，支持有状态对话。常用 MemorySaver（内存中保存）或数据库检查点（如 SQLite）。
  • 默认：None，表示无状态交互。
• state_modifier：
  • 类型：Optional[Union[str, BasePromptTemplate]]。
  • 描述：自定义代理的提示模板或字符串，用于调整 LLM 的行为（例如添加系统提示）。
  • 默认：None，使用默认 ReAct 提示。
• interrupt_before：
  • 类型：Optional[List[str]]。
  • 描述：指定在某些节点执行前中断工作流，用于调试或人工干预。
  • 默认：None，无中断。
• interrupt_after：
  • 类型：Optional[List[str]]。
  • 描述：指定在某些节点执行后中断工作流。
  • 默认：None，无中断。
• debug：
  • 类型：bool。
  • 描述：是否启用调试模式，输出详细的执行日志。
  • 默认：False。
• stream_mode：
  • 类型：Literal["values", "messages"]。
  • 描述：流式输出模式：
    • "values"：返回完整的消息（消息级流式）。
    • "messages"：返回每个令牌（令牌级流式）。
  • 默认："values"。

2.2 返回值

• 类型：CompiledGraph。
• 描述：一个编译后的 LangGraph 状态图，可通过 invoke（同步）、ainvoke（异步）或 stream（流式）方法调用。
• 示例：agent_executor.invoke({"input": "查询天气"}) 返回状态字典。

---

3. 工作原理

create_react_agent 内部自动构建一个 ReAct 风格的状态图，包含以下核心组件：

3.1 状态（State）

• 默认状态是一个字典，包含 messages 字段（List[BaseMessage]），存储对话历史、用户输入、LLM 响应和工具调用结果。
• 如果使用 checkpointer，状态会持久化，支持多轮对话。

示例状态：

{
    "messages": [
        HumanMessage(content="查询天气"),
        AIMessage(content=None, tool_calls=[{"name": "search", "args": {"query": "天气"}}]),
        ToolMessage(content="天气结果", tool_call_id="call_123")
    ]
}

3.2 节点（Nodes）

• Agent 节点：调用 LLM 生成推理或工具调用。通常使用 ToolNode 预构建逻辑，结合 model 和 tools。
• Tool 节点：执行工具调用，基于 langgraph.prebuilt.ToolNode，处理 LLM 生成的 ToolCall 请求。
• 节点之间通过状态共享上下文，Agent 节点决定是否调用工具，Tool 节点执行具体任务。

3.3 边（Edges）

• 普通边：从 Agent 节点到 Tool 节点，当 LLM 生成工具调用时。
• 条件边：根据状态决定下一步：
  • 如果有工具调用，返回 Tool 节点。
  • 如果无工具调用或达到终止条件，跳转到 END。

3.4 执行流程

1. 用户输入：通过 invoke 或 stream 传入初始状态（包含 input）。
2. Agent 节点：LLM 分析输入和历史，生成：
   • 直接回答（AIMessage）。
   • 工具调用（AIMessage 包含 tool_calls）。
3. Tool 节点：执行工具调用，将结果作为 ToolMessage 添加到状态。
4. 循环或终止：根据状态（是否有新的工具调用）决定返回 Agent 节点或结束。
5. 输出：返回最终状态，通常包含 messages 字段。

3.5 ReAct 逻辑

ReAct 代理的核心是交替进行推理和行动：

• 推理：LLM 分析输入，决定是否需要工具或直接回答。
• 行动：调用工具获取外部信息，更新状态。
• 迭代：根据工具结果，LLM 可能再次推理或生成最终回答。

create_react_agent 自动实现这一逻辑，通过状态图管理迭代过程。

---

4. 使用步骤

以下是使用 create_react_agent 的标准步骤：

4.1 安装依赖

pip install langgraph langchain langchain-openai langchain-community

• langgraph：核心库。
• langchain：提供 LLM 和工具支持。
• langchain-openai：OpenAI 模型集成。
• langchain-community：社区工具（如搜索）。

配置 OpenAI API 密钥：

import os
os.environ["OPENAI_API_KEY"] = "你的API密钥"

4.2 定义工具

使用 LangChain 的工具接口（@tool 装饰器或 BaseTool 子类）。

from langchain_core.tools import tool

@tool
def search(query: str) -> str:
    """模拟搜索引擎"""
    return f"搜索结果：{query}"

4.3 初始化 LLM

选择支持工具调用的模型。

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-3.5-turbo")

4.4 创建代理

调用 create_react_agent，传入 LLM 和工具。

from langgraph.prebuilt import create_react_agent

tools = [search]
agent_executor = create_react_agent(llm, tools)

4.5 运行代理

通过 invoke 或 stream 执行。

result = agent_executor.invoke({"input": "搜索 LangGraph 文档"})
print(result["messages"][-1].content)

---

5. 详细示例

以下是一个完整的示例，展示如何使用 create_react_agent 构建一个支持搜索和多轮对话的代理。

5.1 代码实现

from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage

# 定义工具
@tool
def search(query: str) -> str:
    """模拟搜索引擎"""
    return f"搜索结果：{query} 的相关文档"

# 初始化 LLM
llm = ChatOpenAI(model="gpt-3.5-turbo")

# 创建检查点
memory = MemorySaver()

# 创建代理
tools = [search]
agent_executor = create_react_agent(
    model=llm,
    tools=tools,
    checkpointer=memory,
    stream_mode="values"
)

# 运行多轮对话
config = {"configurable": {"thread_id": "conversation_1"}}  # 用于状态持久化
inputs = [
    {"input": "搜索 LangGraph 的最新功能"},
    {"input": "我之前问了什么？"}
]

for input_data in inputs:
    print(f"\n用户输入：{input_data['input']}")
    for chunk in agent_executor.stream(input_data, config=config):
        last_message = chunk["messages"][-1]
        print(f"代理输出：{last_message.content}")

5.2 输出示例

用户输入：搜索 LangGraph 的最新功能
代理输出：搜索结果：LangGraph 的最新功能的文档

用户输入：我之前问了什么？
代理输出：你之前问了“搜索 LangGraph 的最新功能”。

5.3 代码说明

• 工具：定义了一个 search 工具，模拟搜索功能。
• LLM：使用 gpt-3.5-turbo，支持工具调用。
• 检查点：MemorySaver 保存对话历史，thread_id 标识对话线程。
• 代理：通过 create_react_agent 创建，支持流式输出。
• 运行：模拟多轮对话，代理根据历史回答问题。

---

6. 高级用法

6.1 自定义提示

使用 state_modifier 参数自定义代理行为。

from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template(
    "你是一个专业助手，严格遵循用户指令。回答前仔细思考，并优先使用工具获取准确信息。\n用户输入：{input}"
)
agent_executor = create_react_agent(llm, tools, state_modifier=prompt)

6.2 异步执行

支持异步调用，适合高并发场景。

import asyncio

async def run_agent():
    result = await agent_executor.ainvoke({"input": "搜索天气"})
    print(result["messages"][-1].content)

asyncio.run(run_agent())

6.3 流式输出

使用 stream_mode="messages" 实现令牌级流式。

for chunk in agent_executor.stream({"input": "搜索 LangGraph"}, stream_mode="messages"):
    print(chunk)

6.4 中断机制

使用 interrupt_before 或 interrupt_after 在特定节点暂停执行。

agent_executor = create_react_agent(
    llm,
    tools,
    interrupt_before=["tools"]  # 在工具调用前中断
)

6.5 多工具支持

支持多个工具，LLM 动态选择。

@tool
def calculator(expression: str) -> str:
    return f"计算结果：{eval(expression)}"

tools = [search, calculator]
agent_executor = create_react_agent(llm, tools)

6.6 数据库检查点

使用 SQLite 或其他数据库保存状态。

from langgraph.checkpoint.sqlite import SqliteSaver

checkpointer = SqliteSaver.from_conn_string("checkpoint.db")
agent_executor = create_react_agent(llm, tools, checkpointer=checkpointer)

---

7. 实现原理

create_react_agent 内部构建了一个状态图，基于以下组件：

• 状态定义：使用 MessagesState（默认），包含 messages 字段。
• 节点：
  • agent 节点：调用 LLM，生成 AIMessage 或工具调用。
  • tools 节点：基于 ToolNode，执行工具调用。
• 边：
  • 从 agent 到 tools（如果有工具调用）。
  • 条件边：检查 messages 中的 tool_calls，决定循环或终止。
• 运行时：LangGraph 的运行时管理状态更新和节点调度。

核心逻辑基于 ReAct 的迭代过程：

1. LLM 分析输入，生成推理或工具调用。
2. 如果有工具调用，执行工具并更新状态。
3. 重复直到 LLM 决定直接回答或达到终止条件。

---

8. 适用场景

• 聊天机器人：支持多轮对话和工具调用，如智能客服。
• 自动化工作流：如数据分析后调用 API 生成报告。
• 智能助手：支持天气查询、行程规划等功能。
• 研究原型：快速测试 LLM 和工具的集成效果。

---

9. 注意事项

1. 模型兼容性：
   • 使用支持工具调用的 LLM（如 OpenAI、Anthropic）。
   • 确保 model 是基础模型，create_react_agent 会自动绑定工具。
2. 工具定义：
   • 工具必须符合 LangChain 的 BaseTool 接口。
   • 提供清晰的工具描述（description），帮助 LLM 正确选择。
3. 状态管理：
   • 无 checkpointer 时，代理是无状态的。
   • 使用 thread_id 区分不同对话线程。
4. 性能优化：
   • 使用异步接口减少延迟。
   • 限制工具调用次数，避免无限循环。
5. 调试：
   • 启用 debug=True 查看详细日志。
   • 使用 graph.get_graph().to_dot() 可视化状态图。

---

10. 与其他方法的对比

• 手动构建状态图：
  • 优势：完全灵活，支持复杂逻辑（分支、循环、多代理）。
  • 劣势：代码量大，开发复杂。
• LangChain Agent：
  • 优势：简单，适合线性任务。
  • 劣势：不支持复杂状态管理和动态路由。
• create_react_agent：
  • 优势：开箱即用，适合标准 ReAct 场景。
  • 劣势：定制性有限，复杂逻辑需手动扩展。

---

11. 学习建议

• 基础知识：先掌握 LangChain 的 LLM、工具和提示管理。
• 官方文档：阅读 LangGraph 文档 和教程。
• 实践：从简单代理开始，逐步添加工具和状态持久化。
• 社区资源：加入 LangChain Discord，查看 GitHub 示例。
• 调试工具：使用可视化和日志分析工作流。

---

12. 总结

langgraph.prebuilt.create_react_agent 是一个强大的预构建函数，用于快速创建 ReAct 风格的代理。它通过封装 LLM、工具和状态管理，简化了开发流程，支持多轮对话、工具调用和流式输出。适用于聊天机器人、自动化工作流和智能助手等场景。高级功能如异步执行、自定义提示和检查点进一步增强了其灵活性。对于复杂需求，可结合 LangGraph 的手动状态图实现定制化。