create_react

create_react_agent > 部分内容由豆包生成本文是「Day 25：LangChain Tools 与 Agent」的子文档，深入解析 **create_react_agent** 的底层原理、核心组件与执行流程，帮助你从"会用"进阶到"懂原理"。 # 概述 `create_react_agent` 是 LangChain（及 LangGraph）中用于快速构建 ReAct 模式智能体的工厂函数。它将大语言模型（LLM）、工具集（Tools）和提示词（Prompt）组装成一个能够自主推理并调用工具的 Agent，是 LangChain Agent 体系中最经典、最常用的入口之一。 ReAct（Reasoning + Acting）范式源自论文 *ReAct: Synergizing Reasoning and Acting in Language Models*，其核心思想是让模型在**思考（Thought）**与**行动（Action）**之间交替进行，通过观察（Observation）不断修正推理路径，最终完成复杂任务。ReAct 论文 (arXiv:2210.03629) # ReAct 范式原理 ## 核心循环：Thought → Action → Observation ReAct Agent 的每一步都遵循三段式循环： 1. **Thought（思考）**：模型根据当前问题和历史信息，推理下一步应该做什么。 2. **Action（行动）**：模型决定调用哪个工具，并生成工具所需的输入参数。 3. **Observation（观察）**：工具执行后返回结果，模型将结果纳入上下文继续推理。这个循环不断重复，直到模型判断任务已完成，输出最终答案。 ![流程图](https://static.developers.pub/a4051e852c0841559d2c437961a30f1b.png) ## 为什么 ReAct 有效 **推理可追溯** 每一步 Thought 都显式记录，便于调试和审计 Agent 的决策过程。 **工具即能力** 通过工具调用突破 LLM 的知识截止和计算能力限制，实现搜索、计算、代码执行等。 **迭代纠错** Observation 反馈机制让模型能根据工具结果修正推理方向，减少幻觉。 **上下文累积** 历史 Thought/Action/Observation 全部保留在对话中，形成完整的推理链。 # create_react_agent 核心架构 `create_react_agent` 本质上是一个**组装工厂**，它接收 LLM、Tools、Prompt 等组件，内部构建出一条完整的执行链（RunnableSequence），最终返回一个可调用的 Agent 对象。 ![流程图](https://static.developers.pub/754078745e9e4b978203b3e985288feb.png) ## 四大核心组件 | 组件 | 职责 | 说明 | |-|-|-| | **Prompt** | 指令与格式约束 | 定义 Agent 的角色、工具使用规范、输出格式（Thought/Action/Final Answer），是 ReAct 能否跑通的关键。 | | **LLM** | 推理决策引擎 | 绑定工具定义（tool_bind / function calling），根据上下文生成下一步行动或最终答案。 | | **Tools** | 外部能力扩展 | 每个 Tool 包含 name、description、args_schema，模型依据 description 决定何时调用。 | | **Output Parser** | 解析模型输出 | 从 LLM 返回的文本中提取 Action 名称和参数，或识别 Final Answer，驱动循环继续或终止。 | # 内部执行流程深度解析 ## 第一步：Prompt 组装 `create_react_agent` 内部使用的默认 Prompt 包含以下关键部分： ```python # 系统指令 Answer the following questions as best you can. You have access to the following tools: {tools} # 格式指令 Use the following format: Question: the input question you must answer Thought: you should always think about what to do Action: the action to take, should be one of [{tool_names}] Action Input: the input to the action Observation: the result of the action ... (this Thought/Action/Action Input/Observation can repeat N times) Thought: I now know the final answer Final Answer: the final answer to the original input question # 对话历史 {chat_history} # 当前输入 Question: {input} Thought: {agent_scratchpad} ``` **关键点**：`{agent_scratchpad}` 是 Agent 的"草稿本"，每一轮的 Thought/Action/Observation 都会追加到这里，让模型看到完整的推理历史。 ## 第二步：LLM 调用与工具绑定在新版 LangChain（v0.2+）和 LangGraph 中，`create_react_agent` 会自动将 Tools 绑定到 LLM 上（通过 `bind_tools`），使模型能够使用原生的 Function Calling 能力输出结构化的工具调用请求，而非纯文本解析。 ```python # create_react_agent 内部大致做了这件事 llm_with_tools = llm.bind_tools(tools) # 调用时，模型可以返回 tool_calls 字段 response = llm_with_tools.invoke(messages) # response.tool_calls = [{"name": "search", "args": {"query": "..."}}] ``` ## 第三步：Output Parser 解析 Output Parser 负责将 LLM 的输出转化为 Agent 可执行的指令： - **文本模式（旧版）**：用正则从文本中匹配 `Action:` 和 `Action Input:`。 - **Function Calling 模式（新版）**：直接读取 `tool_calls` 字段，更稳定可靠。 - **终止判断**：识别 `Final Answer` 或无 tool_calls 时，结束循环。 ## 第四步：AgentExecutor 循环 AgentExecutor 是运行时的循环控制器，伪代码如下： ```python def agent_executor_loop(agent, input, max_iterations=15): intermediate_steps = [] # 保存 (AgentAction, observation) 元组 for iteration in range(max_iterations): # 1. 调用 Agent（Prompt + LLM + Parser） action = agent.invoke({ "input": input, "agent_scratchpad": format_steps(intermediate_steps) }) # 2. 如果是最终答案，返回 if isinstance(action, AgentFinish): return action.return_values # 3. 否则执行工具 tool = get_tool_by_name(action.tool) observation = tool.invoke(action.tool_input) # 4. 记录中间步骤，进入下一轮 intermediate_steps.append((action, observation)) # 超过最大迭代次数 return {"output": "Agent stopped due to max iterations"} ``` # 源码级解析 ## create_react_agent 函数签名 ```python def create_react_agent( model: BaseLanguageModel, tools: Sequence[BaseTool], prompt: ChatPromptTemplate = None, output_parser: AgentOutputParser = None, tools_renderer: Callable = None, ) -> Runnable: """创建一个 ReAct Agent。 Args: model: 用于推理的 LLM tools: Agent 可调用的工具列表 prompt: 自定义 Prompt（不传则用默认） output_parser: 自定义输出解析器 tools_renderer: 工具描述渲染函数 """ ``` LangChain v0.3 源码：langchain.agents.react.agent ## 组装链的内部结构函数返回的是一个 `RunnableSequence`，其执行链如下： ![流程图](https://static.developers.pub/07caeef0c594429a903c382aa6aaf4e6.png) # 实战示例 ## 最小可运行示例 ```python from langchain.agents import create_react_agent, AgentExecutor from langchain_core.tools import tool from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate # 1. 定义工具 @tool def calculator(expression: str) -> str: """计算数学表达式，输入如 '2 + 3 * 4'""" return str(eval(expression)) @tool def get_current_time(unit: str = "Beijing") -> str: """获取当前时间，unit 为时区，默认北京时间""" from datetime import datetime return datetime.now().strftime("%Y-%m-%d %H:%M:%S") tools = [calculator, get_current_time] # 2. 初始化 LLM llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) # 3. 创建 Agent agent = create_react_agent(llm, tools) # 4. 用 AgentExecutor 包装并运行 executor = AgentExecutor( agent=agent, tools=tools, verbose=True, max_iterations=10, handle_parsing_errors=True ) result = executor.invoke({"input": "现在时间的小时数乘以 7 等于多少？"}) print(result["output"]) ``` ## 自定义 Prompt ```python from langchain_core.prompts import ChatPromptTemplate custom_prompt = ChatPromptTemplate.from_template(""" 你是一个专业的数据分析助手。请严格按照以下格式回答：可用工具： {tools} 格式要求： Question: ${{用户问题}} Thought: ${{你的推理过程}} Action: ${{工具名，必须是 [{tool_names}] 之一}} Action Input: ${{工具参数（JSON格式）}} Observation: ${{工具返回结果}} ...（可重复） Thought: 我已经得到最终答案 Final Answer: ${{最终答案}} 对话历史： {chat_history} 当前问题： Question: {input} Thought: {agent_scratchpad} """) agent = create_react_agent(llm, tools, prompt=custom_prompt) ``` # 与手写 ReAct Agent 的对比回顾 Day 12 手写的 ReAct Agent，`create_react_agent` 在以下方面做了工程化封装： | 维度 | 手写 ReAct（Day 12） | create_react_agent | |-|-|-| | Prompt 管理 | 硬编码字符串，手动拼接 | ChatPromptTemplate，支持变量注入和消息格式化 | | 工具定义 | 手动维护 name/func/description 字典 | @tool 装饰器 + BaseTool 抽象，自动生成 args_schema | | 输出解析 | 手写正则匹配，容易出错 | 内置 ReActOutputParser，支持 Function Calling 原生解析 | | 循环控制 | 手动 while 循环，需自己处理终止条件 | AgentExecutor 封装，支持 max_iterations、early stopping | | 错误处理 | 需自行捕获和重试 | handle_parsing_errors、工具异常自动回传 Observation | | 可组合性 | 独立脚本，难以嵌入更大流程 | 返回 Runnable，可与其他 LCEL 组件链式组合 | | 可观测性 | print 调试 | verbose 模式 + LangSmith 追踪，中间步骤结构化 | # 最佳实践与注意事项 ## 工具设计原则 1. **描述清晰**：Tool 的 description 是模型选择工具的唯一依据，必须写清楚"何时用"和"输入格式"。 2. **单一职责**：每个工具只做一件事，避免一个工具包含多个不相关的功能。 3. **参数明确**：使用类型注解和 docstring 定义 args_schema，减少模型传参错误。 4. **返回简洁**：Observation 应精简，过长的返回会占用上下文并干扰后续推理。 ## 常见问题排查 **问题：模型反复调用同一个工具不停止** 原因：工具返回结果没有给模型足够的"已完成"信号，或 Prompt 中缺少终止引导。解决：在工具返回中加入状态提示，设置合理的 max_iterations。 **问题：OutputParser 解析失败** 原因：模型输出格式不规范。解决：启用 `handle_parsing_errors=True`，让 Agent 将错误信息作为 Observation 反馈给模型自行修正。 **问题：工具调用参数错误** 原因：args_schema 定义不清晰或模型理解偏差。解决：在 description 中给出参数示例，或使用 Pydantic 模型严格校验。 ## 性能优化建议 - **控制工具数量**：过多工具会增加 Prompt 长度和模型选择难度，按需挂载。 - **精简 Observation**：工具返回结果做摘要处理，避免上下文爆炸。 - **设置 max_iterations**：防止 Agent 陷入死循环，默认 15 通常足够。 - **使用 Function Calling**：优先使用支持原生 tool_calls 的模型，比文本解析更稳定。 # 版本演进说明 LangChain 的 Agent API 经历了多次迭代： - **v0.1 及以前**：`initialize_agent` + `AgentExecutor`，基于文本解析。 - **v0.2 / v0.3**：`create_react_agent`（langchain.agents），支持 Function Calling。 - **LangGraph 时代**：`create_react_agent` 迁移到 `langgraph.prebuilt`，基于图状态机，支持更复杂的控制流和持久化。 - **最新（v1.0+）**：统一入口 `langchain.agents.create_agent`，向后兼容 ReAct 模式。本文以 `langchain.agents.create_react_agent` 为主线讲解，核心原理在各版本中通用。 LangChain 官方文档：Agents # 参考资料 1. [ReAct: Synergizing Reasoning and Acting in Language Models (arXiv)](https://arxiv.org/abs/2210.03629) 2. [LangChain v0.3 源码：create_react_agent](https://reference.langchain.com/v0.3/python/_modules/langchain/agents/react/agent.html) 3. [LangChain 官方文档：Agents 概览](https://docs.langchain.com/oss/python/langchain-agents) 4. [LangGraph Prebuilt：create_react_agent](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) 5. [The Neural Base：create_react_agent 标准模式解析](https://theneuralbase.com/langchain/learn/intermediate/create-react-agent-the-standard-agent-pattern/) --- — 本文为 Day 25 学习计划的原理教程子文档 —

create_react_agent

关联知识库

create_react_agent

关于作者 📝

关联知识库

目录

评论