本文从技术架构 出发，建立智能体架构的认知框架与分类体系，说明各架构的设计动机、适用场景与取舍，并在文末对应到可运行的代码示例，并会持续更新。
代码仓库 ：https://github.com/WenSongWang/AgenticArchitectures --- 后续会继续补充、优化，欢迎 Star / Watch 以便获取更新。
目录
- [架构总览（当前仓库 01--14）](#架构总览（当前仓库 01–14）)
- 学习路径导览（按主题分组）
- 各架构流程示意
- 一、智能体架构在解决什么问题
- 二、控制流：线性、循环与条件分支
- [2.1 线性流水线](#2.1 线性流水线)
- [2.2 循环：直到满足终止条件](#2.2 循环：直到满足终止条件)
- [2.3 条件分支与路由](#2.3 条件分支与路由)
- [三、规划与执行：先规划 vs 边想边做 vs 带验证的闭环](#三、规划与执行：先规划 vs 边想边做 vs 带验证的闭环)
- [3.1 先规划再执行（Plan-then-Execute）](#3.1 先规划再执行（Plan-then-Execute）)
- [3.2 边想边做（ReAct）](#3.2 边想边做（ReAct）)
- [3.3 规划---执行---验证闭环](#3.3 规划—执行—验证闭环)
- [四、多智能体协调：固定顺序 vs 动态调度](#四、多智能体协调：固定顺序 vs 动态调度)
- [4.1 固定顺序多角色（流水线式协作）](#4.1 固定顺序多角色（流水线式协作）)
- [4.2 黑板 + 动态控制器（机会主义激活）](#4.2 黑板 + 动态控制器（机会主义激活）)
- [4.3 元控制器（入口路由，专家并行可选）](#4.3 元控制器（入口路由，专家并行可选）)
- 五、记忆与状态：从无状态到长期记忆
- [5.1 无状态 / 仅会话内状态](#5.1 无状态 / 仅会话内状态)
- [5.2 情景记忆 + 语义记忆](#5.2 情景记忆 + 语义记忆)
- [六、推理与搜索策略：单路径 vs 多路径 vs 先模拟后执行](#六、推理与搜索策略：单路径 vs 多路径 vs 先模拟后执行)
- [6.1 单路径（链式思考）](#6.1 单路径（链式思考）)
- [6.2 思维树（多路径探索与剪枝）](#6.2 思维树（多路径探索与剪枝）)
- [6.3 思维模型循环（先模拟后执行）](#6.3 思维模型循环（先模拟后执行）)
- 七、架构选型与对比小结
- 八、在本项目中的代码对应关系
- 技术栈与环境（当前仓库）
- 九、总结与后续更新
架构总览（当前仓库 01--14）
当前仓库已实现 14 种架构（GitHub 已更新至 14），覆盖线性/循环/条件路由、规划与验证、多智能体、记忆与推理、试跑外壳等。
| # | 架构 | 核心思想 / TL;DR | 典型场景 | 文件 |
|---|---|---|---|---|
| 01 | Reflection（反思） | 由单次生成升级为多步推理，通过自我批判与改写提升质量 | 高质量代码生成、复杂摘要 | 01_reflection.py |
| 02 | Tool Use（工具使用） | 通过外部 API/函数扩展认知与行动力 | 实时研究助理、企业机器人 | 02_tool_use.py |
| 03 | ReAct | 将「推理」与「动作」交替迭代，适应多步复杂任务 | 多跳问答、Web 导航与研究 | 03_react.py |
| 04 | Planning（规划） | 先出详尽计划再执行，保障流程可追踪与稳定 | 报告生成、项目管理 | 04_planning.py |
| 05 | Multi-Agent（多智能体） | 专家团队协作，分工提升深度与结构化品质 | 软件流水线、创意头脑风暴 | 05_multi_agent.py |
| 06 | PEV（计划-执行-验证） | 引入验证器逐步校验结果，容错并动态恢复 | 高风险自动化、金融、易错工具 | 06_planner_executor_verifier.py |
| 07 | Blackboard（黑板系统） | 共享中央记忆与机会式协作，由控制器动态调度 | 复杂诊断、动态意义建构 | 07_blackboard.py |
| 08 | Episodic + Semantic Memory | 向量检索的会话记忆 + 图谱/结构存储的事实 | 长期个人助理、个性化导师 | 08_episodic_with_semantic_cn.py |
| 09 | Tree of Thoughts（思维树） | 以树探索多条推理路径，评估与剪枝以求最优 | 逻辑谜题、受约束规划 | 09_tree_of_thoughts_cn.py |
| 10 | Mental Loop（内部模拟器） | 在内在模型中试运行动作，预判风险与效果 | 机器人、量化交易、安全关键系统 | 10_mental_loop_cn.py |
| 11 | Meta-Controller（元控制器） | 任务分析并路由到最合适的专家子智能体 | 多服务平台、可适应助理 | 11_meta_controller_cn.py |
| 12 | Graph（图/世界模型记忆） | 文本→知识图谱抽取→Cypher 查询→多跳推理与合成答案 | 知识库问答、关系推理 | 12_graph_cn.py |
| 13 | Ensemble（并行探索+集成决策） | 多路分析师并行分析，聚合者（如 CIO）综合结论 | 复杂推理、事实核查、高 stakes 决策 | 13_ensemble_cn.py |
| 14 | Dry-Run Harness（试跑外壳） | 拟稿→试跑预览→人工审核（approve/reject）→执行或取消 | 发帖/发邮件/改库等不可逆操作的前置校验 | 14_dry_run_cn.py |
学习路径导览（按主题分组）
- 基础模式（01--04）：Reflection 提升输出质量 → Tool Use 赋能外部工具 → ReAct 推理与行动交替 → Planning 先规划后执行。
- 多智能体协作（05, 07, 11, 13）：Multi-Agent 固定顺序协作 → Blackboard 共享黑板与动态调度 → Meta-Controller 入口路由到最佳专家 → Ensemble 多路并行分析+聚合决策。
- 记忆与推理（08, 09, 12）：Episodic + Semantic Memory 双记忆系统 → Tree of Thoughts 多路径探索与剪枝 → Graph 知识图谱与 Text-to-Cypher 多跳问答。
- 安全与可靠（06, 10, 14）：PEV 自动验证与恢复 → Mental Loop 先模拟后执行 → Dry-Run 试跑+人工审核再执行。
各架构流程示意
以下为 14 种架构的流程示意（Mermaid），便于对照理解控制流与节点关系。
01 反思（Reflection）
用户请求
生成初稿
评审
改写
最终输出
02 工具使用（Tool Use）
用户请求
规划
执行工具
汇总
最终输出
03 ReAct
否
是
思考
行动
观察
任务完成?
最终输出
04 规划（Planning）
用户请求
规划器
执行器
合成器
最终输出
05 多智能体（Multi-Agent）
输入
角色 A
角色 B
角色 C
最终输出
06 计划-执行-验证（PEV）
否
是
规划
执行
验证
通过?
最终输出
07 黑板系统（Blackboard）
否
是
控制器
选下一专家
专家 A
专家 B
专家 C
黑板
完成?
最终输出
08 情景记忆 + 语义记忆（Episodic + Semantic Memory）
检索
用户输入
情景向量检索
语义图查询
增强生成
响应
记忆写入
情景存储
语义图
09 思维树（Tree of Thoughts）
否
是
根状态
扩展路径 1
扩展路径 2
扩展路径 3
评估/剪枝
保留最优
收敛?
合成解
10 思维模型循环（Mental Loop）
观察环境
提议策略
模拟执行
评估风险
真实执行
最终输出
11 元控制器（Meta-Controller）
用户请求
Meta-Controller
通用智能体
研究智能体
编码智能体
最终响应
12 图/世界模型记忆（Graph）
文本
知识图谱抽取
图存储
自然语言问题
Text-to-Cypher
执行查询
合成答案
13 并行探索+集成决策（Ensemble）
用户问题
分析师 1
分析师 2
分析师 3
CIO 综合
最终建议
14 可观测与试跑外壳（Dry-Run Harness）
approve
reject
用户请求
拟稿
试跑预览
人工审核
正式执行
取消
最终状态
一、智能体架构在解决什么问题
单轮「提问---回答」的 LLM 调用存在明显边界：无法多步推理、无法可靠调用工具、无法在多次对话间保持状态、无法在多个角色间协调。智能体架构 要解决的是：在保留 LLM 生成能力的前提下，通过控制流、状态、记忆与多角色协作，把「一次生成」升级为「可规划、可执行、可验证、可迭代」的系统。
因此，讨论架构时至少要区分四个维度：
- 控制流：线性流水线、循环（直到满足条件）、条件分支与路由。
- 规划与执行：先规划再执行、边想边做（ReAct）、规划---执行---验证闭环。
- 记忆与状态：无状态、会话内状态、长期情景记忆、语义/知识记忆。
- 多角色协调：单智能体、固定流水线多角色、动态调度（黑板、元控制器）。
下面按这四个维度展开，再归纳选型思路，最后对应到本项目中的实现文件。
二、控制流：线性、循环与条件分支
2.1 线性流水线
设计动机：任务可拆成固定顺序的若干阶段，每阶段输入明确、输出交给下一阶段，无需根据中间结果「改道」。
典型形态：阶段 A → 阶段 B → 阶段 C → 结束。例如：生成 → 评审 → 改写（反思）；规划 → 执行 → 汇总（工具使用）；规划 → 执行 → 合成（规划架构）。
特点：实现简单、行为可预期、易于调试；不适合需要「根据结果再决定下一步」的场景。
在本项目中：
- 反思（Reflection）：生成 → 评审 → 改写，对应
01_reflection.py。 - 工具使用（Tool Use）：规划 → 执行 → 汇总，对应
02_tool_use.py。 - 规划（Planning）：规划 → 执行 → 合成，对应
04_planning.py。
2.2 循环：直到满足终止条件
设计动机 ：下一步依赖上一步的观察结果，无法事先固定步骤数，需要「执行---观察---再决策」的循环。
典型形态：思考 → 行动 → 观察 →（若未完成）再思考 → 行动 → ... → 结束。步数由数据与模型决策共同决定，通常配合最大步数防止死循环。
特点：灵活、适合探索型任务与工具调用；代价是调用次数与延迟不确定，需要设计好终止条件与步数上限。
在本项目中 ：ReAct（Reasoning + Acting），对应 03_react.py。
2.3 条件分支与路由
设计动机 ：不同请求应走不同处理路径（不同子图或不同专家），需要在运行时根据请求内容做路由。
典型形态：入口节点（如「元控制器」）分析输入 → 根据决策将请求路由到专家 A / B / C，各专家内部可以是线性或带循环的子图。
特点：单一入口、多路分发，便于扩展新专家；路由质量成为系统瓶颈，需要精心设计路由提示与评估。
在本项目中 ：元控制器（Meta-Controller），对应 11_meta_controller_cn.py。
三、规划与执行：先规划 vs 边想边做 vs 带验证的闭环
3.1 先规划再执行（Plan-then-Execute）
设计动机：先把「做什么」想清楚，再严格按步骤执行，减少执行阶段的随意性与工具误用。
典型形态：规划器输出结构化步骤（如步骤列表、工具调用计划）→ 执行器按序执行并收集结果 → 汇总/合成最终答案。规划与执行分离，规划阶段不调用外部工具。
特点：步骤可解释、易做合规与审计；规划一旦偏差，执行阶段无法自行纠偏。
在本项目中 ：工具使用（02_tool_use.py）、规划（04_planning.py）均属此类；差异在于规划粒度与是否强调「工具调用计划」。
3.2 边想边做（ReAct）
设计动机 ：规划与执行交织，根据实时观察决定下一步，适合环境反馈敏感、难以一次性规划完整的任务。
典型形态：每轮「思考---选工具---执行---观察」，循环直到模型认为任务完成或达到步数上限。
特点：适应性强，能根据工具返回动态调整；单轮推理成本与步数不可控，需设上限与超时。
在本项目中 ：ReAct，对应 03_react.py。
3.3 规划---执行---验证闭环（Planner--Executor--Verifier）
设计动机 ：执行结果可能不符合预期（错误、不完整），需要验证环节，不通过则回到规划或执行，形成闭环。
典型形态：规划 → 执行 → 验证 →（若失败）重新规划或重试执行 → 直至通过或达到最大迭代次数。
特点：具备自纠错能力，适合对正确性要求高的任务；迭代次数与延迟增加，验证标准需要明确定义。
在本项目中 ：规划→执行→验证，对应 06_planner_executor_verifier.py。
四、多智能体协调：固定顺序 vs 动态调度
4.1 固定顺序多角色（流水线式协作）
设计动机：多个「专家」按固定顺序依次贡献，例如先研究员、再分析师、再撰写员，角色顺序在图中写死。
典型形态：节点 1（角色 A）→ 节点 2（角色 B）→ 节点 3（角色 C）→ 结束。状态在节点间传递，无动态选人。
特点：实现简单、行为稳定；无法根据中间结果「换人」或跳过某角色。
在本项目中 ：多智能体（Multi-Agent）示例，对应 05_multi_agent.py（可对比黑板与元控制器的「动态」调度）。
4.2 黑板 + 动态控制器（机会主义激活）
设计动机 ：多个专家共享一块「黑板」（共享状态），由动态控制器 根据当前黑板内容决定下一步由谁写，谁「有机会」谁上，而非固定顺序。
典型形态：控制器观察黑板 → 选择下一个专家 → 该专家读黑板、执行、写回黑板 → 再交给控制器，循环直到满足结束条件。
特点：灵活、适合问题分解不唯一、需多轮协作求解的场景；控制器设计难度高，黑板结构需要约定好。
在本项目中 ：黑板系统（Blackboard），对应 07_blackboard.py。
4.3 元控制器（入口路由，专家并行可选）
设计动机 ：请求先进「元控制器」，由它一次性决定把请求交给哪一个专家（或哪条子流水线），专家之间通常不串行协作，而是各管一类请求。
典型形态：元控制器（LLM）分析请求 → 路由到专家 A / B / C 之一 → 该专家独立完成并返回；下次请求再次从元控制器进入。
特点：单一入口、易扩展新专家、职责清晰；不适合「一个请求需要多个专家轮流贡献」的深度协作，那种更接近黑板。
在本项目中 ：元控制器（Meta-Controller），对应 11_meta_controller_cn.py。
元控制器流程示意 （与 11_meta_controller_cn.py 对应）：
Analyzes Request
User Request
Meta-Controller
Routes to Specialist
Generalist Agent
Research Agent
Coding Agent
Final Response
五、记忆与状态：从无状态到长期记忆
5.1 无状态 / 仅会话内状态
设计动机：每次请求独立处理，或仅在当前会话的「状态图」内传递变量，不跨会话持久化。
典型形态：LangGraph 的 state 在单次 invoke 内流动，不写外部存储。大多数单次任务、工具调用、规划---执行类示例都属于此类。
在本项目中：01--07、09--11 的默认行为均为会话内状态；是否持久化由是否接入外部存储决定。
5.2 情景记忆 + 语义记忆（长期个性化）
设计动机：需要跨会话记住「发生过什么」（情景）和「提炼出的知识」（语义），以支持长期助手、个性化推荐等。
典型形态：
- 情景记忆：按时间/事件存储交互摘要，用向量检索「与当前查询相似」的过去片段，注入上下文。
- 语义记忆：从交互中抽取实体与关系，写入图或结构化存储，查询时做关系推理。
- 检索到的情景 + 语义一起参与当前轮生成；生成后再做「记忆写入」（摘要 + 抽取）。
特点：真正跨会话的个性化；实现复杂，需考虑记忆膨胀、修剪与一致性。
在本项目中 ：情景记忆 + 语义记忆栈，对应 08_episodic_with_semantic_cn.py（含向量库与 Mock 图库）；图/世界模型记忆（Text-to-Cypher 多跳问答）对应 12_graph_cn.py。
六、推理与搜索策略：单路径 vs 多路径 vs 先模拟后执行
6.1 单路径（链式思考）
设计动机：一次生成或一条主推理链到底，成本低、延迟小，适合简单、低风险任务。
典型形态：单次或线性多步调用，无分支探索、无显式剪枝。
在本项目中：多数架构的「默认推理」即单路径；反思、规划---执行等是在「步骤」上线性推进，推理本身仍可视为单路径。
6.2 思维树（多路径探索与剪枝）
设计动机 ：对复杂推理或搜索问题，单一路径容易陷入局部；显式维护多条候选路径，定期评估、剪枝，最后从存活路径中合成解。
典型形态：并行或顺序扩展多个「思路」→ 对每条路径打分/评估 → 剪掉差路径 → 继续扩展或收敛到最优路径并输出。
特点：提高复杂问题的求解稳健性；计算与调用次数显著增加。
在本项目中 ：思维树（Tree-of-Thoughts），对应 09_tree_of_thoughts_cn.py。
6.3 思维模型循环（先模拟后执行）
设计动机 ：在真实环境执行前，先在沙盒/模拟器里跑一跑策略，根据模拟结果评估风险与收益，再决定真实执行什么，降低「试错成本」。
典型形态：观察真实状态 → 提出策略 → 在模拟环境中运行策略 → 评估模拟结果 → 修正决策 → 在真实环境中执行（或放弃）。
特点：适合高风险决策（金融、控制、机器人）；依赖可信的模拟器与评估指标。
在本项目中 ：思维模型循环（Mental-Model-in-the-Loop），对应 10_mental_loop_cn.py。与 ReAct 的对比：ReAct 是「边在真实环境行动边观察」；思维模型循环是「先在模拟里试，再在真实环境执行一次」。多路径并行+聚合 ：Ensemble（13）多路分析师并行分析后由 CIO 综合；试跑+人审：Dry-Run Harness（14）拟稿→试跑→approve/reject→执行或取消。
七、架构选型与对比小结
| 关注点 | 可选架构 | 简要说明 |
|---|---|---|
| 提升单次输出质量 | 反思（Reflection） | 生成→评审→改写，线性三步，适合代码/文案打磨 |
| 多步工具调用、步骤可解释 | 工具使用、规划 | 先规划再执行，步骤结构化；要自纠错选规划---执行---验证 |
| 环境依赖强、需边做边看 | ReAct | 思考---行动---观察 循环，步数由条件与上限控制 |
| 多角色固定顺序协作 | 多智能体（流水线） | 角色顺序固定，状态顺序传递 |
| 多角色动态协作、共享黑板 | 黑板系统 | 控制器按黑板状态选下一个专家，机会主义激活 |
| 单入口、按请求类型路由 | 元控制器 | 元控制器路由到某一专家，专家独立完成任务 |
| 多路并行+聚合决策 | 并行探索+集成（Ensemble） | 多路分析师并行分析，聚合者综合结论，适合复杂推理与高 stakes |
| 长期个性化、跨会话记忆 | 情景+语义记忆 | 向量情景 + 图/结构语义，检索后增强生成 |
| 知识图谱与多跳问答 | 图/世界模型记忆（Graph） | 文本→图谱抽取→Cypher 查询→合成答案 |
| 复杂推理/搜索、要稳健解 | 思维树 | 多路径探索与剪枝，合成最优 |
| 高风险决策、先试再干 | 思维模型循环 | 模拟→评估→再真实执行 |
| 不可逆操作前先预览与人审 | 试跑外壳（Dry-Run） | 试跑→人工 approve/reject→再执行或取消 |
- 控制流：线性（01、02、04）→ 循环（03）→ 条件路由（11）→ 扇出/扇入（13）。
- 规划：先规划（02、04）→ 边想边做（03）→ 带验证闭环（06）→ 试跑后人审（14）。
- 多智能体：固定顺序（05）→ 动态黑板（07）→ 入口路由（11）→ 并行+聚合（13）。
- 记忆：无/会话内（多数）→ 长期情景+语义（08）→ 知识图谱（12）。
- 推理：单路径（默认）→ 多路径思维树（09）→ 先模拟后执行（10）。
八、在本项目中的代码对应关系
仓库地址 ：https://github.com/WenSongWang/AgenticArchitectures
以下仅作「架构 → 实现文件」的索引，便于按架构查代码；克隆后每个 py 均可一键运行，具体命令与环境配置见仓库 README 与各文件头部注释。
| 架构 | 文件 | 架构要点在代码中的体现 |
|---|---|---|
| 反思（Reflection） | 01_reflection.py |
StateGraph 线性三节点：generator → critic → refiner；Pydantic 约束 Draft/Critique/Refined |
| 工具使用（Tool Use） | 02_tool_use.py |
规划器输出 ToolPlan，执行器按序执行并支持变量引用，汇总层产出最终答案 |
| ReAct | 03_react.py |
思考---行动---观察 循环，条件边控制是否继续 |
| 规划（Planning） | 04_planning.py |
规划→执行→合成 线性三阶段 |
| 多智能体 | 05_multi_agent.py |
多节点固定顺序协作，状态在节点间传递 |
| 规划---执行---验证 | 06_planner_executor_verifier.py |
验证失败时回到规划/执行，条件边实现迭代 |
| 黑板系统 | 07_blackboard.py |
共享状态（黑板）+ 动态控制器选择下一专家 |
| 情景+语义记忆 | 08_episodic_with_semantic_cn.py |
向量检索情景、图/结构存储语义，检索增强生成与记忆写入 |
| 思维树 | 09_tree_of_thoughts_cn.py |
多路径状态、评估与剪枝、最优路径合成 |
| 思维模型循环 | 10_mental_loop_cn.py |
策略→模拟→评估→真实执行 四阶段 |
| 元控制器 | 11_meta_controller_cn.py |
元控制器节点 + 条件边按决策路由到各专家节点 |
| 图/世界模型记忆 | 12_graph_cn.py |
文本摄入→实体关系抽取→图存储；问题→Text-to-Cypher→执行→合成答案 |
| 并行探索+集成决策 | 13_ensemble_cn.py |
多路分析师节点（可并行或顺序）→ CIO 综合节点，结构化最终建议 |
| 试跑外壳 | 14_dry_run_cn.py |
拟稿→试跑（dry_run=True）→人工审核→条件边执行或拒绝 |
项目还提供 agentic_architecture_visualizer.py（Streamlit）用于查看各架构的图结构（含 01--14），便于与上述分类对照理解。
技术栈与环境（当前仓库）
| 组件 | 用途 |
|---|---|
| Python 3.10+ | 项目基础语言 |
| LangGraph | 编排复杂、具状态与回环的工作流 |
| LangChain 1.0 | LLM/工具交互的组件 |
| ModelScope API | 大模型推理（OpenAI 兼容接口），当前仓库仅使用主模型 |
| Pydantic v2 | 结构化数据建模与 LLM 输出约束 |
| Rich | 终端美化输出 |
| Tavily Search | 研究型智能体的搜索工具（部分示例） |
| Streamlit | 架构可视化 |
配置 .env 中的 MODELSCOPE_API_KEY、MODELSCOPE_BASE_URL、MODELSCOPE_MODEL_ID 等即可运行；详见仓库 README。
九、总结与后续更新
智能体架构的「章法」可以归纳为：先按控制流、规划策略、多智能体协调、记忆与推理方式四个维度分类 ，再根据业务需求（质量、可解释性、灵活性、风险、个性化等）做选型，最后在具体实现中体现为「图结构、节点职责与状态形状」。本文建立了这一框架，并将 AgenticArchitectures 中 14 个可一键运行的 py 示例（01--14）分别归入对应架构，便于做系统性的技术分享与二次设计；代码细节以仓库内 README 与各 py 文件为准。后续会继续补充更多架构（如自改进循环、细胞自动机、反思式元认知等），欢迎 Star / Watch 获取更新。