网站导航
> 技术文档 > 【LangGraph】langgraph.prebuilt.create_react_agent() 函数：快速创建基于 ReAct（Reasoning + Acting）架构的智能代理_langgraph react agent

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

网友: 技术文档 2025-08-15 16:32:23

本文是对 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_agentdef 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 osos.environ[\"OPENAI_API_KEY\"] = \"你的API密钥\"

4.2 定义工具

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

from langchain_core.tools import tool@tooldef search(query: str) -> str: \"\"\"模拟搜索引擎\"\"\" return f\"搜索结果：{query}\"

4.3 初始化 LLM

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

from langchain_openai import ChatOpenAIllm = ChatOpenAI(model=\"gpt-3.5-turbo\")

4.4 创建代理

调用 create_react_agent，传入 LLM 和工具。

from langgraph.prebuilt import create_react_agenttools = [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_agentfrom langgraph.checkpoint.memory import MemorySaverfrom langchain_openai import ChatOpenAIfrom langchain_core.tools import toolfrom langchain_core.messages import HumanMessage# 定义工具@tooldef search(query: str) -> str: \"\"\"模拟搜索引擎\"\"\" return f\"搜索结果：{query} 的相关文档\"# 初始化 LLMllm = 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 ChatPromptTemplateprompt = ChatPromptTemplate.from_template( \"你是一个专业助手，严格遵循用户指令。回答前仔细思考，并优先使用工具获取准确信息。\\n用户输入：{input}\")agent_executor = create_react_agent(llm, tools, state_modifier=prompt)

6.2 异步执行

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

import asyncioasync 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 动态选择。

@tooldef 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 SqliteSavercheckpointer = 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() 可视化状态图。

  6. 如果提示模块不存在

    from langgraph.prebuilt import create_react_agent
    ImportError: cannot import name ‘create_react_agent’ from ‘langgraph.prebuilt’ (unknown location)

    需要通过 pip install langgraph-prebuilt 安装 prebuilt 模块

10. 与其他方法的对比

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

11. 学习建议

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

12. 总结

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

网络标签：

相关问题