在大模型智能体开发领域ReAct 模式推理行动是目前工业界最主流、最成熟的智能体运行范式。绝大多数工具调用、自动化任务、场景化智能体底层都依赖这套Think-Act 循环机制。本文将基于完整的类继承体系层层拆解BaseAgent → ReActAgent → ToolCallAgent → 场景化子类的完整源码设计、核心能力、执行流程帮你彻底搞懂工业级 ReAct 智能体的底层架构。一、整体类继承架构一览整套智能体框架采用分层抽象、逐级实现的设计上层定义标准下层落地场景能力架构清晰、扩展性极强BaseAgent (抽象基类) └── ReActAgent (抽象层实现核心 Think-Act 循环) ├── ToolCallAgent (通用工具调用核心实现) │ ├── BrowserAgent (浏览器自动化智能体) │ ├── MCPAgent (MCP 协议外部工具智能体) │ └── SWEAgent (软件工程专项智能体) └── SandboxAgent 等其他场景变体简单来说BaseAgent 搭骨架ReActAgent 定范式ToolCallAgent 做通用实现各子类适配专属业务场景。二、底层基石BaseAgent 基础抽象层BaseAgent是所有智能体的根抽象类位于app/agent/base.py:13负责封装所有智能体通用的基础能力是整个框架的底层支撑不区分具体业务场景。核心四大能力能力模块详细说明状态管理内置AgentState状态机严格管控智能体生命周期IDLE空闲→ RUNNING运行中→ FINISHED完成/ ERROR异常通过state_context上下文管理器保证状态切换安全、线程可控内存记忆管理依托Memory对象统一管理全局消息历史update_memory()支持user/system/assistant/tool四种角色消息的录入与更新完整留存对话与工具执行上下文核心主循环通过run()方法实现智能体主循环持续调用step()单步执行直至达到最大步数max_steps或状态切换为完成/异常自动终止任务卡死自愈检测内置is_stuck()卡死检测机制识别连续重复的模型回复超出阈值后自动注入策略优化提示解决智能体循环卡死、无效重试问题三、核心范式ReActAgent 抽象层ReActAgent是整套框架的核心灵魂继承自BaseAgent且为抽象类位于app/agent/react.py:11。它严格定义了 ReAct 智能体的标准运行范式先推理、后行动将智能体行为拆解为 Think、Act 两个核心步骤。核心源码设计通过两个抽象方法强制子类实现推理和执行能力通过step()串联成完整单步逻辑class ReActAgent(BaseAgent, ABC): abstractmethod async def think(self) - bool: # 思考阶段分析上下文决策下一步是否需要行动 ... abstractmethod async def act(self) - str: # 行动阶段执行think阶段确定的操作返回结果 ... async def step(self) - str: # 完整单步 推理 执行 should_act await self.think() if not should_act: return Thinking complete - no action needed return await self.act()核心设计思想Think 推理层纯逻辑决策基于当前对话内存、任务状态判断是否需要调用工具、调用哪个工具、传入什么参数返回布尔值标记是否需要执行行动Act 执行层纯动作落地执行 Think 阶段敲定的决策完成工具调用、命令执行、结果回写Step 步进封装标准化单步执行逻辑由BaseAgent.run()主循环持续驱动形成闭环 ReAct 循环这也是经典ReActReasoning Acting模式的核心智能体不再是单次问答而是「推理-执行-观察-再推理」的持续迭代闭环。四、通用落地ToolCallAgent 核心实现ToolCallAgent是框架中使用率最高的实体智能体继承自ReActAgent位于app/agent/toolcall.py:18。它完整实现了工具调用场景下的 Think、Act 逻辑是所有场景化工具智能体的父类。1. Think 推理阶段核心逻辑负责生成模型决策、解析工具调用指令核心流程如下若配置了next_step_prompt自动追加至当前消息列表补充阶段化提示信息调用LLM.ask_tool()与大模型交互获取携带tool_calls的结构化响应适配三种工具调用模式灵活适配不同任务场景NONE禁止工具调用仅纯文本对话交互REQUIRED强制必须调用工具无有效工具调用则主动抛异常保证任务落地AUTO智能自适应有工具调用需求则执行无则直接返回文本回复将模型返回的 assistant 消息含工具调用信息持久化存入内存返回布尔值标记是否存在待执行的工具调用用于驱动后续 Act 阶段2. Act 行动阶段核心逻辑负责落地工具调用、归集执行结果核心流程如下AUTO 模式下若无工具调用需求直接返回模型文本回复批量遍历所有tool_calls逐个调用execute_tool()执行工具将所有工具执行结果封装为标准tool_message存入对话内存留存完整上下文拼接所有工具执行结果作为本轮 step 的最终返回内容3. 工具执行核心方法 execute_tool校验工具调用命令格式合法性拦截非法请求通过全局tool_map匹配对应的工具实例解析校验工具入参 JSON 格式保证参数合规执行工具核心逻辑完成对应任务操作识别特殊终止工具Terminate自动将智能体状态置为 FINISHED结束任务标准化工具执行输出生成统一的 observation 观测结果4. 核心配置字段字段名称默认值功能说明available_toolsCreateChatCompletion、Terminate智能体当前可调用的工具集合tool_choicesAUTO工具调用模式NONE/REQUIRED/AUTOspecial_tool_names[terminate]可触发任务终止的特殊工具标识max_steps30单任务最大执行步数防止无限循环max_observeNone工具观测结果最大截断长度用于控参、避免上下文溢出五、场景化子类多专用智能体变体框架基于ToolCallAgent延伸出多个垂直场景智能体复用核心 ReAct 循环仅适配专属工具、状态和参数扩展性极强。1. BrowserAgent 浏览器智能体app/agent/browser.py:87继承自ToolCallAgent专属能力通过BrowserContextHelper在每次推理前同步浏览器状态URL、截图、标签页、页面元素可用工具BrowserUseTool浏览器操作 Terminate最大步数20 步适用场景网页自动化、爬虫、页面操作、UI 交互测试2. MCPAgent 外部协议智能体app/agent/mcp.py:13继承自ToolCallAgent专属能力基于 MCP 协议对接外部工具服务器支持 stdio、SSE 双传输方式动态能力每 5 步自动刷新工具列表支持外部工具实时增删改适配动态工具生态最大步数20 步适用场景对接第三方工具、远程服务、可动态扩展的工具集群3. SWEAgent 软件工程智能体app/agent/swe.py:10继承自ToolCallAgent专属定位专为软件工程、代码开发、问题修复场景设计可用工具Bash命令行操作 StrReplaceEditor代码编辑 Terminate最大步数20 步适用场景自动编码、代码调试、脚本执行、项目文件修改六、完整全局执行流程从用户输入到任务结束整套智能体的完整闭环流程如下用户输入 │ ▼ BaseAgent.run() 启动任务 │ ├─ 标记智能体状态为 RUNNING │ └─ 循环执行未达最大步数、未终止 │ ├─ ReActAgent.step() 单步执行 │ │ │ ├─ think() 推理阶段 │ │ ├─ 构建本轮 Prompt 上下文 │ │ ├─ 调用 LLM 获取工具调用决策 │ │ ├─ 解析结构化 tool_calls │ │ └─ 返回是否需要执行行动 │ │ │ └─ act() 执行阶段 │ ├─ 遍历所有工具调用指令 │ ├─ 逐个执行工具、获取观测结果 │ ├─ 结果写入内存上下文 │ └─ 归集返回执行结果 │ ├─ is_stuck() 卡死检测异常则注入优化策略 └─ 检测任务状态判断是否终止 任务结束返回最终结果七、核心总结1.分层设计是核心BaseAgent 管通用生命周期ReActAgent 管推理行动范式ToolCallAgent 管通用工具调用子类管场景定制各司其职、解耦彻底。2.ReAct 闭环是灵魂所有智能体都遵循「Think 推理决策 → Act 落地执行」的迭代循环完美复刻人类解决复杂任务的思考与行动逻辑。3.高扩展性适配多场景基于统一父类可快速衍生浏览器、代码工程、外部协议等垂直智能体无需重构底层逻辑。4.工业级健壮性内置状态管控、卡死自愈、步数限制、上下文管理可稳定运行复杂长周期任务。
