AgentChat多智能体架构详解：ReAct、Plan-Execute、Text2SQL等8类Agent实现原理完全指南

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• 后端
• 前端

AgentChat 是一个基于 LLM 的智能体交流平台，其多智能体架构内置了 ReAct、Plan-Execute、CodeAct、Text2SQL、MCP、Skill 等 8 类 Agent，通过"推理-行动循环"与"规划-执行"两种核心范式，配合工具调用、知识检索与沙箱执行，让 AI 能够自主完成复杂任务。本文用通俗语言拆解这 8 类 Agent 的实现原理与适用场景，帮助新手快速理解多智能体系统的运作机制。

如上图所示，AgentChat 采用分层架构：最上层是应用交互层，中间是智能体编排层（ReAct 推理与行动、规划与执行、HITL 人机协同），底层则是能力模型层、知识记忆层和数据基础设施。所有 Agent 都运行在"智能体编排层"这一核心位置。

一、8类Agent总览：一张表看懂分工

AgentChat 的智能体代码集中在 src/backend/agentchat/core/agents/ 目录下，每个 Agent 对应一个独立模块，官方参考文档见 docs/reference/core.md。

用户在"智能体"页面看到的每一个 Agent 卡片，背后都由上表中的引擎驱动。

二、ReAct Agent：最经典的"思考-行动"循环

ReAct（Reasoning + Acting）是当前最主流的智能体范式，react_agent.py 基于 LangGraph 实现，核心是两张"状态图"节点：

1. call_tool_node（推理节点）：把用户消息和可用工具一起交给模型，模型要么发起tool_calls（要调哪个工具、传什么参数），要么直接给出最终回答；
2. execute_tool_node（执行节点）：真正调用工具，把结果作为ToolMessage塞回上下文，再跳回推理节点。

条件边_should_continue负责判断循环是否继续：只要模型还在发起工具调用就继续转圈，一旦模型不再调用工具，流程走向END。

这个设计有两个新手友好的细节：

• 全程流式事件：每次"选工具/执行工具"都会通过stream_writer发出 START/END/ERROR 事件，前端因此能实时展示"正在调用插件工具 xxx"的过程；
• 兜底容错：工具执行失败时，错误信息会作为ToolMessage回传给模型，让它有机会换一条路。

会话界面底部的工具过程提示，正是 ReAct 循环中这些流式事件驱动的。

三、GeneralAgent：把一切能力"组装"成一个Agent

如果说 ReactAgent 是"发动机"，那么 general_agent.py 中的 GeneralAgent 就是"整车"——它是用户自定义 Agent 的实际执行引擎，职责是把各种能力拼装起来：

• 插件工具：从数据库按tool_ids加载，用户自定义的 OpenAPI 工具会自动适配成标准 Tool；
• MCP 子 Agent：每个绑定的 MCP 服务被封装成一个"工具"，由 MCPAgent 负责执行；
• Skill 子 Agent：每个 Skill 也被包装成工具，由 SkillAgent 执行；
• 知识库：绑定了知识库后，会自动多出一个"检索知识库"工具（RAG 检索）；
• 智能工具搜索：当工具数量超过阈值（MAX_TOOLS_SIZE = 10）时，会先只暴露一个search_available_tools搜索工具，先"搜"出相关工具再激活，避免大量工具描述撑爆上下文。

它通过create_agent+ 中间件（Middleware）机制实现事件上报和工具名美化展示，例如把mcp_filesystem展示成"执行MCP：文件系统"。

四、Plan-Execute Agent：先画地图，再开车

plan_execute_agent.py 实现了"规划-执行"范式，分两个阶段：

阶段一：规划。借助 StructuredResponseAgent 让模型输出一个结构化 JSON 计划（PlanToolFlow），内容以 "step_1"、"step_2" 组织，每一步声明要调用的工具、参数来源和推理依据。规划提示词（completion.py 中的PLAN_CALL_TOOL_PROMPT）特别约定了三类情况：

• 串行调用：工具 B 依赖工具 A 的输出 → 分步执行；
• 并行调用：多个工具互不影响 → 放在同一个 step；
• 参数缺失：主动调用call_user向用户追问缺失参数。

阶段二：执行。按计划逐步调用工具，每步执行结果累积进上下文供后续步骤引用。如果模型输出的 JSON 格式坏了，还会触发一个JSON 自动修复流程：把原 JSON 和报错信息交给模型重新修复后再解析。

适合"查天气→对比→给建议"这种长链条任务；简单问题则直接输出空计划跳过工具调用。

五、CodeAct Agent：让模型直接写代码

codeact_agent.py 采用CodeAct（Code as Action）思路：与其让模型一个一个调工具，不如让它直接写 Python 代码，然后在Pyodide 沙箱（WebAssembly 版 CPython）中执行。

工作流程：

1. 模型输出要么是一段代码块，要么是最终文字回答；
2. 代码被提取后注入沙箱，可引用上一步定义的变量和所有工具函数；
3. 执行结果（stdout / 报错）回传给模型，继续迭代。

代码在浏览器端的沙箱里跑，天然隔离了风险，适合数据分析、批量计算等"用代码比用工具调用更高效"的任务。

六、MCP Agent：把外部服务接入智能体

MCPAgent 是 MCP（Model Context Protocol）协议的智能体封装。它通过MCPManager动态连接 SSE / HTTP 类型的 MCP 服务，拉取远端工具列表后挂载到 ReAct 循环上。

两个值得新手注意的设计：

• 中间件注入用户配置：像高德地图、邮箱这类需要鉴权的 MCP 服务，会通过中间件在每次工具调用前自动把该用户的个人配置（如 API Key）合并进参数，用户无感知；
• 终止协议：MCP 子 Agent 使用专门的CALL_END_PROMPT，要求它在完成任务后只输出固定终止语，防止子 Agent "抢戏"替主 Agent 回答用户。

七、Skill Agent：用一份文档定义一种能力

SkillAgent 的灵感来自"技能文件夹"：每个 Skill 是一个目录，核心是SKILL.md技能说明文档，旁边可附带参考资料。

它的工作方式很朴素但有效：

1. 把SKILL.md内容作为系统提示词，告诉模型"你现在的职责和标准作业流程"；
2. 只给模型两个工具：list_skill_files（列出技能文件）和get_file_content（按需读取文件）；
3. 模型在回答时"缺什么资料就查什么文件"，实现渐进式加载，避免一次性把所有资料塞进上下文。

内置的研究报告、代码审查、邮件写作等 Skill（见 src/backend/agentchat/config/skills/）都是这种结构。

八、StructuredResponse 与 Text2SQL：两个"专科医生"

StructuredResponseAgent（structured_response_agent.py）：用 Pydantic 模型作为"模具"，强制模型输出合法的结构化 JSON。它本身就是 Plan-Execute 规划阶段的"幕后功臣"——计划能不能稳定生成，靠的就是它。

Text2SQLAgent（text2sql_agent.py）：实现"自然语言查数据库"，内置了一个自我修正循环：

1. 自动读取数据库 Schema（表结构）注入提示词；
2. 让模型生成 SQL，并只允许 SELECT语句执行，防止误操作；
3. 执行报错时，把错误信息连同原 SQL 回传给模型修正，最多重试 3 次；
4. 查询成功后，再让模型把结果"翻译"成自然语言回答。

九、多智能体如何协作：Agent as Tool

AgentChat 多智能体架构最巧妙的地方是"Agent as Tool"模式：GeneralAgent 并不把所有 MCP 工具、Skill 工具平铺到同一个上下文里，而是把每个子能力封装成一个子 Agent，再把这个子 Agent 当作工具挂到主 Agent 上。

好处很直观：

• 上下文隔离：MCP 子 Agent 和 Skill 子 Agent 各自有独立的提示词与消息历史，互不污染；
• 按需深入：主 Agent 只看到"高德地图 MCP"、"研究报告 Skill"这样的入口，决定需要时才"下钻"调用；
• 统一事件流：所有子 Agent 的执行事件都通过流式通道上报，用户能看到完整的任务推进过程。

在工作台发起的复杂任务（如深度调研），就是由这套"主 Agent + 子 Agent + 工具"的编排体系在后台协作完成的。

十、新手选型指南：该用哪种Agent？

总结

AgentChat 的多智能体架构可以概括为一句话：用 ReAct 循环解决"怎么调工具"，用 Plan-Execute 解决"先想后做"，用 Agent-as-Tool 解决"谁来协调谁"。8 类 Agent 各司其职，共享同一套模型管理（ModelManager）、流式事件和 Token 统计回调，既保证了扩展性，也让新手无需理解全部细节，就能在界面上组合出符合自己场景的智能体。

想深入代码细节，建议按这个顺序阅读：react_agent.py → general_agent.py → plan_execute_agent.py，再配合 docs/reference/core.md 的架构说明，基本就能掌握整个多智能体体系。

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• 后端
• 前端