本文是对 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 执行流程
- 用户输入:通过
invoke
或stream
传入初始状态(包含input
)。 - Agent 节点:LLM 分析输入和历史,生成:
- 直接回答(
AIMessage
)。 - 工具调用(
AIMessage
包含tool_calls
)。
- 直接回答(
- Tool 节点:执行工具调用,将结果作为
ToolMessage
添加到状态。 - 循环或终止:根据状态(是否有新的工具调用)决定返回 Agent 节点或结束。
- 输出:返回最终状态,通常包含
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 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_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 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 动态选择。
@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 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 的迭代过程:
- LLM 分析输入,生成推理或工具调用。
- 如果有工具调用,执行工具并更新状态。
- 重复直到 LLM 决定直接回答或达到终止条件。
8. 适用场景
- 聊天机器人:支持多轮对话和工具调用,如智能客服。
- 自动化工作流:如数据分析后调用 API 生成报告。
- 智能助手:支持天气查询、行程规划等功能。
- 研究原型:快速测试 LLM 和工具的集成效果。
9. 注意事项
-
模型兼容性:
- 使用支持工具调用的 LLM(如 OpenAI、Anthropic)。
- 确保
model
是基础模型,create_react_agent
会自动绑定工具。
-
工具定义:
- 工具必须符合 LangChain 的
BaseTool
接口。 - 提供清晰的工具描述(
description
),帮助 LLM 正确选择。
- 工具必须符合 LangChain 的
-
状态管理:
- 无
checkpointer
时,代理是无状态的。 - 使用
thread_id
区分不同对话线程。
- 无
-
性能优化:
- 使用异步接口减少延迟。
- 限制工具调用次数,避免无限循环。
-
调试:
- 启用
debug=True
查看详细日志。 - 使用
graph.get_graph().to_dot()
可视化状态图。
- 启用
-
如果提示模块不存在
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 的手动状态图实现定制化。