多 Agent 编排
Multi-Agent Orchestration
多个专职 Agent 如何协调执行顺序、并行分发任务、汇聚结果。核心挑战是在灵活性和可控性之间找到平衡。
子问题
1.任务分解：将复杂任务拆分为可并行的子任务
2.执行编排：DAG 调度、顺序/并行/条件分支
3.状态同步：多 Agent 间共享上下文和中间结果
4.结果汇聚：多个子 Agent 结果的合并与冲突解决
5.动态路由：根据任务类型动态选择合适的 Agent
6.多模型竞赛评估：相同任务条件下不同 LLM 独立运行并通过结果排名对比
7.供应商 API 兼容：不同 LLM 供应商的 tool_calls 返回格式差异修复
8.运行时配置隔离：并行进程间如何通过独立配置文件避免全局状态污染
9.人格化命令派发：如何通过 persona trait-strength 参数调整子 Agent 的决策风格
10.事件紧急度分级调度：如何基于 urgency 四级动态计算延迟执行时间
11.传输无关的模块通信：如何让本地插件和远程插件共享同一事件 API
12.能力贡献与依赖发现：模块如何声明能力并等待依赖模块就绪
13.协议版本协商：模块与宿主如何在连接时协商兼容的协议版本
14.Orchestrator 自身 Agent 化：如何将编排者本身建模为一个可管理的 Agent session
15.多 AI 工具统一适配：同一编排逻辑如何通过插件接口驱动 claude/codex/aider 等不同工具
16.元数据格式选择：session 状态存储选择 key=value 扁平文件 vs JSON vs SQLite 的权衡
17.PR 自动检测：对无 hook 机制的 Agent 如何通过 SCM 插件按分支名自动发现 PR
18.反应升级策略：自动处理失败后如何基于重试次数和时间窗口升级到人类干预
19.进程级隔离：如何为每个 Agent 提供独立的运行时环境和代码工作区
20.批量去重：批量派发时如何检测已有 session 和同批次重复 issue
21.Agent 工具适配：同一编排逻辑如何驱动不同 AI 编码工具（claude/codex/aider）
22.Session 恢复：崩溃的 Agent session 如何从归档 metadata 恢复并重新启动
23.Metadata Hook 自动化：Agent 执行 git/gh 命令后如何自动更新编排系统的 session 元数据
24.异构 Agent 活性检测：不同 AI 工具（JSONL/终端输出/进程探测）的活性检测统一抽象
25.Orchestrator-Worker 双层编排：编排 Agent 本身也是一个 Agent session，如何避免递归和权限混淆
26.订阅关系自动清理：如何在 MsgHub 退出时自动移除订阅关系防止内存泄漏
27.消息深拷贝开销：并行扇出时 deepcopy 对大消息对象的性能影响
28.多 MsgHub 隔离：同一 Agent 同时参与多个 MsgHub 时的订阅关系隔离
29.流式输出异常处理：Agent 执行出错时如何先 yield 已打印消息再抛异常
30.查询分解粒度控制：LLM 如何决定拆分为几个子查询以及拆分边界
31.归约器设计：子图结果如何通过自定义 reducer 安全汇入主图状态
32.压缩阈值自适应：如何根据已压缩摘要大小动态调整触发压缩的 token 阈值
33.中间件栈继承策略：子 Agent 如何选择性继承父级的中间件组件而非全量复制
34.声明式子 Agent 热加载：运行时扫描文件系统新增子 Agent 而无需重启主 Agent
35.子 Agent 结果格式约束：如何确保子 Agent 返回的最终消息符合主 Agent 期望的格式
36.双流水线复用：同一系统如何支持多条不同长度的编排流水线并共享公共阶段
37.写后清空记忆：长实现循环中如何在保留必要上下文的同时防止 token 爆炸
38.完整性评估：如何自动判断 LLM 输出是否被截断并触发自适应重试
39.多路径采样预算分配：如何在初始轨迹、部分采样和补充轨迹间分配有限的计算预算
40.困惑度驱动分支：如何利用 token 级 logprobs 识别推理链中的高不确定性决策点
41.轨迹压缩聚合：多条完整推理轨迹如何压缩为结构化报告再批判性合并
42.写后记忆清空：长文写作中如何在保留写作结果的同时清空已消费的检索内容
43.模式选型：同一系统内不同任务类型如何选择不同的编排模式
44.迭代收敛：如何判断 Agent 循环何时应该终止（should_stop 信号设计）
45.动态队列扩展：研究过程中发现新主题时如何动态加入调度队列
46.后端轮询 vs LLM 轮询：谁负责检查子任务完成状态的架构选择
47.双线程池死锁预防：调度线程等待超时时如何不阻塞新任务提交
48.tool_call_id 复用：如何将 LLM 工具调用 ID 与后台任务 ID 统一简化追踪
49.子代理能力声明：如何通过 prompt + 工具裁剪双重约束限定子代理行为边界
50.自适应迭代参数：如何根据查询复杂度动态调整迭代轮数、置信度阈值和资源预算
51.ROI 停滞检测：如何通过连续轮次的置信度增益和行数 ROI 判断迭代是否值得继续
52.可视化画布到 DAG 的双向序列化：前端 JSON 与后端 Graph 对象的实时同步
53.循环边首次启动放宽：cycle vertex 首次执行时如何安全跳过未完成的循环前驱
54.条件排除与循环重置冲突：同一顶点同时参与条件路由和循环时的状态隔离
55.同层并行异常传播：asyncio.gather 中一个任务失败时如何取消同批次其他任务
56.frozen vertex 缓存跳过：如何让已缓存的顶点跳过重建但仍参与依赖传递
57.SOP 编码：如何将人类团队的标准操作流程编码为 Agent 间的消息订阅关系
58.消息总线路由：Environment 如何根据 send_to/cause_by 精确路由消息到目标 Role
59.双模式切换：同一 Team 如何在 SOP 固定流水线和 TeamLeader 动态路由间切换
60.预算熔断：如何在多 Agent 并行执行中实施全局成本控制
61.工具注册表零拷贝过滤：如何用 Arc 共享实现高效的工具子集创建
62.子代理 Hook 继承策略：子代理是否应继承父级的生命周期钩子
63.子代理模型降级：如何让子代理使用更便宜的模型以控制成本
64.递归防护：如何防止子 Agent 无限 spawn 新的子 Agent
65.结果自然化：子 Agent 结果如何转化为面向用户的自然语言回复
66.并发切片溢出处理：超出并发上限的 tool_calls 如何返回错误引导 LLM 重新规划
67.压缩模型独立配置：子 Agent 结果压缩使用独立模型避免主模型上下文污染
68.渐进式截断重试：token 超限时按 0.9 倍递减截断 findings 直到成功
69.双版本编排共存：同一项目同时维护 Send API 静态扇出和 tool_call 动态派发两套方案
70.Canvas 互斥执行：同一画布同时只允许一个工作流执行的并发控制
71.轮询间隔调优：轮询频率与系统负载的平衡（Refly 默认 1.5s）
72.非 Skill 节点透传：DAG 中非执行节点（document/image）如何自动标记完成
73.Gemini 工具签名修复：Vertex AI 返回的 signatures 数组与 tool_calls 数量不匹配时的修复策略
74.对抗性辩论编排：如何在 Agent 间构建结构化的正反方辩论并控制收敛
75.多方轮转调度：3方以上辩论如何设计固定轮转顺序和终止条件
76.辩论裁决机制：如何设计裁决者综合多方论点做出最终决策
77.角色记忆隔离：同一编排中不同角色如何维护独立的经验记忆
78.阶段间消息清洗：顺序流水线中如何在阶段切换时清空累积消息防止上下文污染
79.意图分类前置：如何用轻量级 LLM 在编排前过滤简单问答避免不必要的规划开销
80.Agent 能力声明式发现：Planner 如何通过工具调用动态查询可用 Agent 而非硬编码
81.规划结果幻觉防护：如何校验 LLM Planner 输出的 agent_name 在合法注册表中
82.SSE 连接与任务执行解耦：消费者断开后如何保证后台任务（尤其定时任务）继续执行
83.跨层线程关联：SuperAgent handoff 到 Subagent 时如何保留 parent thread_id 实现全链路追踪
84.结构验证前置：如何在编排启动前检测 DAG 中的环、断连、依赖反转等结构缺陷
85.Agent 身份统一：如何将 Agent 建模为与任务同构的数据实体而非独立注册表
86.单 issue 自动包装：如何将非 epic 的单个 issue 自动包装为可 swarm 的 epic 结构
87.Agent 市场化分发：如何将 Agent+Command+MCP 打包为可安装的 Workflow 单元
88.权限继承开关：子 Agent 如何通过布尔开关选择继承或隔离父级工具权限
89.Agent 模型验证：执行前如何自动检测模型兼容性并推荐替代模型
90.Hook 生命周期覆盖：如何用 9 种事件类型覆盖 Agent 从启动到停止的完整生命周期
91.配图异步解耦：耗时子任务如何不阻塞主流水线且避免序列化问题
92.Generator-Critic Loop：段落级评估-改进循环的多维度评分与收敛检测
93.配置预设套餐：如何将散落的 44 处条件判断收拢为 StyleProfile 查表
94.中间件透明包装：如何在不修改节点代码的情况下注入追踪/预算/降级逻辑
各项目的解法27 solutions
横向对比
| 维度 | DeerFlow | GPT-Researcher | MiroThinker | AI-Trader | AIRI | Agent | AgentOrchestrator | AgentScope | agentic-rag-for-dummies | DeepAgents | DeepCode | DeepResearch | DeepTutor | FastCode | Langflow | MetaGPT | Moltis | Nanobot | OpenClaw | Open | OpenManus | Refly | TradingAgents | ValueCell | beads | iflow-cli | vibe-blog |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 编排模式 | Lead Agent → task_tool 动态委派 | DeepResearchSkill 树状递归 | run_sub_agent() 子 Agent 即工具 | 进程级并行竞赛：每个 LLM 模型独立子进程，无协作无通信 | Spark 三事件协议（notify/command/emit）+ LLM 决策中枢 | Orchestrator-Worker 两层架构，Orchestrator 本身也是 Agent session | 进程级隔离 + 轮询状态机，每个 Agent 独立 tmux session | Sequential + Fanout 双模式，函数式+类式双接口 | 双层 StateGraph：主图线性流水线 + 子图 ReAct 循环 | 中间件注入 task 工具，LLM 自主决策何时委托子 Agent | 8阶段顺序流水线 + ParallelLLM fan-in/fan-out 并行 | 双系统：WebWeaver 两阶段流水线 + ParallelMuse 多路径并行推理 | 联邦制多模式：Dual-Loop/DynamicQueue/Pipeline/StateMachine 按模块选型 | Spawn 异步派生 + 迭代检索双编排，子代理 asyncio.Task 后台执行 | 自研 Graph 引擎 + 分层拓扑排序波前推进 | 双模式：SOP 隐式 DAG（_watch 订阅）+ MGX TeamLeader 动态路由 | LLM 自主委托：spawn_agent 作为普通工具，LLM 决定何时 spawn | Spawn-and-Forget：主 Agent 通过 spawn 工具异步派生子 Agent | — | 三层子图嵌套：主图→Supervisor子图→Researcher子图，LLM tool_call 驱动派发 | — | BullMQ 双队列轮询：runWorkflow 执行 + pollWorkflow 调度，1.5s 间隔 | LangGraph StateGraph 5阶段顺序流水线 + 2个辩论环（2方+3方） | 三层顺序流水线：SuperAgent→Planner→Orchestrator→TaskExecutor | DAG 拓扑排序 + Ready Front 波次调度，无固定流水线 | SubAgent 类型分发 + Workflow 目录约定流水线 | LangGraph StateGraph 声明式 DAG，20+ 节点 + 6 条件边 + 3 循环回路 |
| 并行能力 | 双线程池 _scheduler_pool + _execution_pool | asyncio.Semaphore(2) 异步并发 | 顺序执行（子 Agent 独立轮次） | asyncio.create_subprocess_exec + gather，模型数=进程数 | ChannelGateway fan-out 广播，多通道并行接收 | batch-spawn 批量创建，每个 Agent 独立 tmux+worktree 进程级并行 | batch-spawn 顺序派发 N 个 Agent，500ms 间隔防竞争 | asyncio.gather 并发，enable_gather 可切换顺序执行 | Send API Map-Reduce，子查询数由 LLM 动态决定（1-3） | 支持单消息多 tool_call 并行派发，无显式并发限制 | mcp_agent ParallelLLM 原语，fan-out 并行 + fan-in 汇聚 | ThreadPool 线程并行 + asyncio 协程并行，三类资源独立信号量 | Research 模块 Semaphore 控制并行，asyncio.gather 批量执行 | 子代理间天然并行（独立 asyncio.Task），无显式并发限制 | 同层 asyncio.gather 真并行，跨层串行 | asyncio.gather 并行执行所有非 idle Role，无并发上限 | 同轮多 tool_call 并发执行，但子代理间无通信 | 原生并行：asyncio.create_task 支持多个子 Agent 同时运行 | — | asyncio.gather 并行执行 Researcher 子图，切片控制并发上限 | — | 节点间 DAG 并行 + 节点内 pLimit 工具并行（默认 10 并发） | 无并行，4类分析师严格顺序执行 | Task 列表顺序执行，无 DAG 并行 | Kahn 算法自动发现最大并行度，按波次释放 | SubAgent 独立会话串行执行，无内置并行 | ParallelTaskExecutor 统一引擎，ThreadPool + 串行/并行自动切换 |
| 状态管理 | SubagentConfig + SubagentResult + 5 态状态机 | visited_urls + learnings 跨层传递 | 独立 message_history 不污染主 Agent | 每个 signature 独立 .runtime_env.json + position.jsonl | XState 17 步状态机 + Pinia reactive store | 16 态状态机 + LifecycleManager 30s 轮询 + 扁平 key=value 元数据文件 | 14 态状态机 + flat-file metadata（key=value 纯文本） | 订阅者模式，Agent 维护 _subscribers 字典 | State/AgentState 双层隔离，accumulate_or_reset 归约器 | _EXCLUDED_STATE_KEYS 过滤父状态，子 Agent 独立 messages | 函数参数传递 dir_info Dict + ConciseMemoryAgent 写后清空 | JSONL 文件传递中间状态，page_info/url2id 动态累积 | 三层 Memory 持久化 + GuidedSession 会话状态机 | 子代理独立 messages 列表，不共享主代理会话历史 | Vertex 三态 + 动态 Pydantic StateModel | RoleContext 封装 memory/msg_buffer/state/todo，Pydantic 序列化 | 子代理完全无状态：无历史、无 hooks、独立消息链 | 完全隔离：子 Agent 独立 messages 列表，不共享主 Agent 上下文 | — | 三层独立 State + override_reducer 支持状态覆盖/追加双模式 | — | Prisma/PostgreSQL 持久化 + Redis 分布式锁 + CAS 乐观并发 | MessagesState 扩展 TypedDict，嵌套 InvestDebateState/RiskDebateState 子结构 | ExecutionContext 内存字典 + TTL 过期 + 用户身份校验 | 无冗余状态表，每次从 beads 实时计算 swarm status | IFLOW.md 分层记忆 + Hook 环境变量传递 | TypedDict SharedState 50+ 字段，ReducerMiddleware 合并并发写入 |
| 并发限制 | SubagentLimitMiddleware MAX_CONCURRENT=3 | Semaphore(2) + breadth 逐层减半 | 无（顺序执行） | 无显式限制，模型数即并发数 | 单 Orchestrator 串行处理，processing 锁防并发 | 500ms spawn 间隔 + O_EXCL 原子 ID 预留，无全局并发上限 | 无硬性上限，受 tmux session 数和系统资源限制 | — | 无显式并发限制，依赖 LangGraph 框架默认行为 | — | ParallelLLM 内部管理，无显式并发限制配置 | 三类信号量独立控制：LLM/Search/Visit 各默认 32 | asyncio.Semaphore(max_parallel) + asyncio.Lock 保护共享状态 | 无硬性限制，_running_tasks dict 跟踪但不限制数量 | asyncio.Lock 保护调度状态，无显式并发上限 | 无内置信号量，依赖 n_round 轮次限制和 NoMoneyException 预算熔断 | session 级 Semaphore 单并发 + 子代理迭代上限 25 | 无显式限制：_running_tasks 字典跟踪但不限制数量 | — | max_concurrent_research_units 切片，超出部分返回错误消息 | — | 环境变量 WORKFLOW_TOOL_PARALLEL_CONCURRENCY 可配置，默认 10 | recursion_limit=100 防止无限循环，无并发控制 | per-agent asyncio.Lock 防止并发 start_agent | MaxParallelism 由 DAG 结构决定，无硬编码上限 | — | 环境变量 BLOG_GENERATOR_MAX_WORKERS 默认 3，TaskConfig 单任务超时 300s |
| 工具隔离 | disallowed_tools=["task"] 防递归嵌套 | 每个子查询独立 GPTResearcher 实例 | YAML 配置独立工具集 per sub_agent | 共享 MCP 服务端口，Agent 间工具集相同 | 每个插件独立 Eventa context + 独立传输通道 | 8 插件槽位完全解耦，Agent 接口抽象驱动 claude/codex/aider | 8 插件槽位（Runtime/Agent/Workspace/SCM/Tracker/Notifier/Terminal） | — | ToolFactory 封装，所有子图共享同一 tools 实例 | 子 Agent 可声明独立 tools 或继承主 Agent 工具集 | 每个 Agent 通过 server_names 绑定独立 MCP Server | — | Research 统一 _call_tool 路由，Solve 通过 ToolAgent 隔离 | 子代理 ToolRegistry 排除 spawn/message，架构级递归防护 | — | 每个 Role 独立 tool_execution_map，TeamLeader 通过 @register_tool 暴露 | clone_without 排除 spawn_agent，Arc 零拷贝过滤 | 白名单注册：子 Agent 显式排除 message/spawn 工具防止递归 | — | Supervisor 绑定 3 工具，Researcher 绑定搜索+MCP 工具，互不交叉 | — | 每个 Agent 节点独立 StateGraph，工具集按节点 metadata 配置 | 4类分析师各绑定独立 ToolNode，工具按数据源分组 | Planner 仅暴露 get_enabled_agents/get_agent_description 两个工具 | Agent 通过 pin/hook 机制独占 issue，label 标记 gt:agent | isInheritTools/isInheritMcps 布尔开关继承或白名单隔离 | TieredLLMProxy 按 Agent 角色路由 fast/smart/strategic 三级模型 |
| 模块自治 | 声明式 SubagentConfig dataclass，新增类型只需加配置文件 | — | — | AGENT_REGISTRY + importlib 动态加载，新增类型零改编排 | 插件自主声明能力，host 不干预内部实现 | 每个 Worker Agent 独立 worktree + tmux，崩溃不影响其他 Agent | 每个 Agent 完全自治，编排器仅通过 sendMessage 干预 | — | — | 子 Agent 拥有独立中间件栈（5 层），不依赖主 Agent 运行时 | 7 个专业 Agent 各自独立，通过 async 函数链串联 | — | 5 个独立编排器各自选择最适合的编排模式 | 子代理拥有独立 system prompt + 独立工具集 + 独立迭代上限 | — | Role 自主 observe→think→act，Environment 仅做消息路由不干预决策 | 子代理运行完整独立 agent loop，拥有独立迭代计数和消息历史 | 高自治：子 Agent 独立运行 15 轮循环，完成后通过 MessageBus 回传 | — | Researcher 子图独立编译，有自己的 State/OutputState/退出条件 | — | — | — | AgentCard JSON 声明能力，Agent 增删无需改 Planner 代码 | Agent 即 Bead，复用 issue 基础设施，8 态状态机自报告 | 每个 Agent 独立 Markdown 配置文件，独立 systemPrompt | — |
| 迭代收敛 | — | — | — | STOP_SIGNAL 自主收敛 + max_steps 硬上限双保险 | — | — | — | — | MAX_ITERATIONS=10 + MAX_TOOL_CALLS=8 双重熔断 | — | — | MAX_LLM_CALL_PER_RUN=40 轮次上限 + token 超限强制终止 | — | 置信度驱动四维停止信号：confidence/iterations/budget/ROI | MAX_CYCLE_APPEARANCES=2 硬限制 + should_continue 计数 | — | — | — | — | 三重退出：迭代超限 OR 无 tool_calls OR ResearchComplete 信号 | — | — | count 计数器 + max_rounds 硬上限，无置信度动态终止 | — | — | — | 三重保护：最大轮数 + 分数增益阈值 0.3 + StyleProfile 预设 |
| 结果回传 | SubagentResult 5 态状态机 + 后端 5s 轮询 + SSE 实时推送 | — | — | 各 Agent 独立 position.jsonl，无汇聚层 | spark:emit 六态回传（queued/working/done/dropped/blocked/expired） | Worker 通过 git push + PR 回传结果，Orchestrator 通过 SCM 插件检测 | Agent 自行创建 PR，编排器通过 SCM 插件轮询 PR 状态 | — | agent_answers 列表按 index 排序后 LLM 聚合 | 提取子 Agent 最终消息为 ToolMessage，通过 Command update 回传 | fan-in Agent 自动接收所有 fan-out 结果，流水线通过返回值传递 | Report-Integrate 两阶段聚合：先压缩轨迹再批判性合并 | — | MessageBus system channel 异步注入，主代理 LLM 自然化摘要 | — | Role.publish_message → Environment → TeamLeader 感知完成状态 | 同步阻塞返回 JSON {text, iterations, tool_calls_made, model} | MessageBus 注入：结果作为 system 消息触发主 Agent 自然回复 | — | Researcher 压缩后以 ToolMessage 回传 Supervisor | — | ToolMessage 按原始索引排序回传，保持 LLM 上下文顺序一致性 | Risk Judge 输出 final_trade_decision，SignalProcessor 提取 BUY/SELL/HOLD | A2A TaskStatusUpdateEvent 流式回传 + EventResponseService 统一 emit | Agent 通过 bd close --reason 回传结果，comment 补充上下文 | Task Tool 返回值回传主会话 | ParallelTaskExecutor 返回 TaskResult 列表，按 _section_id 回写到 state |
| 异步解耦 | execute_async 立即返回 task_id，后端轮询替代 LLM 轮询 | — | — | 子进程完全解耦，通过 asyncio.gather 等待 | ReadableStream 驱动通道泵送，事件异步分发 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | BullMQ 队列解耦执行与调度，Worker 独立消费 | — | — | — | — | 配图 Future 存实例字典避免序列化，wait_for_images 节点汇合 |
| 多模型兼容 | model='inherit' 继承父模型，或指定独立模型名 | — | — | DeepSeekChatOpenAI 子类修复 tool_calls 格式差异 | 通过 xsai providers 抽象支持多 LLM 提供商 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 执行前自动验证模型兼容性，不兼容时推荐替代模型 | — |
| 竞赛评估 | — | — | — | 同条件独立运行，通过收益率排名对比模型能力 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 生命周期钩子 | — | — | — | — | 17 步状态机覆盖 loading→ready 全生命周期 | — | — | — | — | 子 Agent 支持独立 interrupt_on 配置实现 HITL 审批 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 9 种 Hook 类型覆盖完整 Agent 生命周期 | — |
| 条件路由 | — | — | — | — | GatewayRoute.match 函数式匹配 + fan-out/first/all 模式 | — | — | — | 三路路由：tools/collect_answer/fallback_response | LLM 根据 subagent_type 参数自主路由，无预定义条件边 | — | — | — | — | 双系统排除：ACTIVE/INACTIVE 循环管理 + conditionally_excluded 持久排除 | — | — | — | — | clarify_with_user 条件分支：需澄清→END / 不需要→write_research_brief | — | — | — | — | — | 自然语言意图识别自动匹配 Agent 类型 | — |
| 递归防护 | 配置层 disallowed_tools 默认排除 task + 工具注册 subagent_enabled=False | — | — | — | processing 锁 + maxAttempts 限制防止无限重试 | Orchestrator 通过 CLI 命令管理 Worker，Worker 无 spawn 权限 | — | — | recursion_limit=50 全局递归上限 | 子 Agent 中间件栈不含 SubAgentMiddleware，天然阻断递归 | — | — | — | — | cycle_vertices 集合 + ran_at_least_once 严格模式 | — | 双重保险：_spawn_depth 计数器(MAX=3) + 工具过滤移除 spawn_agent | — | — | Researcher 子图无法再派发子 Agent，天然防止递归 | — | 三重：recursionLimit=51 + 连续相同签名检测(3次) + 迭代上限(25次) | — | 三层架构天然隔离，SuperAgent 不能调用自身 | swarm validate 前置检测环依赖，有环则 Swarmable=false 拒绝创建 | SubAgent 通过 Task Tool 调用，无显式递归深度限制 | 动态 recursion_limit = base_nodes + max_loops + 5，基于 StyleProfile 计算 |
| 懒初始化 | SubAgent 中间件 lazy_init=True 复用父 Agent 沙箱和路径 | — | — | — | 插件 load 与 init 分离，支持批量加载后统一初始化 | — | PluginRegistry 按需 get，未使用的插件不实例化 | — | — | SubAgentMiddleware.__init__ 时预编译所有子 Agent 图，非懒加载 | Agent 使用 async with 上下文管理器按需初始化和释放 | — | Solve Loop Agents 首次使用时才创建，减少启动开销 | — | asyncio.Lock 和 TracingService 均懒初始化 | model_validator(mode='after') 延迟初始化 actions/tools/memory | — | 按需创建：每次 spawn 创建新的 ToolRegistry 和 messages | — | — | — | — | — | SuperAgent/Planner/RemoteConnections 均首次调用时初始化 | — | — | — |
| 市场化分发 | — | — | — | — | ManifestV1 标准化插件清单 + 多运行时入口点 | — | — | — | — | AGENTS.md + YAML frontmatter 声明式定义，文件系统即注册表 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | XinLiu Open Market 一键安装 Agent/Command/Workflow | — |
| 定时任务支持 | — | — | — | — | tick 定时器轮询 + notebook 到期任务自动转 spark:notify | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | pollWorkflow 延迟入队实现定时轮询，scheduleId 支持定时触发 | — | TaskPattern.RECURRING + ScheduleConfig 原生周期执行 | — | — | — |
| 经验记忆 | — | — | — | — | SparkCommand guidance.type=memory-recall 触发记忆回溯 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | BM25 词法检索历史相似情境反思，5个角色各持独立记忆实例 | — | — | IFLOW.md 持久化 + /memory add 动态写入 | — |
| Spark事件协议 | — | — | — | — | 三事件闭环：notify 上报 → command 下发 → emit 回传 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 人格化决策 | — | — | — | — | guidance.persona 支持 trait-strength 人格参数调整子 Agent 行为 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 反应式自愈 | — | — | — | — | — | reaction 引擎：事件→动作映射 + 重试计数 + 时间/次数升级到人类 | Reaction 引擎：CI 失败/Review 变更自动转发 Agent + 重试升级 | — | — | — | — | — | — | 子代理异常 catch 后 announce error，主代理继续运行 | _execute_tasks 中异常取消剩余任务，不自动重试 | — | — | — | — | — | — | — | — | SuperAgent/Planner 懒初始化失败优雅降级，不抛异常 | Witness 通过 heartbeat 超时检测 dead Agent，可触发重新分配 | — | GracefulDegradationMiddleware 可降级节点白名单 + on_error 钩子 |
| 结构验证 | Registry dict 查找 + _clamp_subagent_limit 范围校验 [2,4] | — | — | — | — | spawn 前验证 issue 存在 + 项目配置有效 + 插件可用 | — | — | — | — | — | — | — | — | NetworkX 强连通分量检测循环，DFS 检测环边 | — | — | — | — | — | — | prepareNodeExecutions 构建 DAG 时验证 startNodes 存在性 | — | Planner 输出的 agent_name 校验合法性，防止 LLM 幻觉 | 5 项前置检查：环/断连/依赖反转/根节点/叶节点 | — | LayerValidator 层间数据契约校验（可选），仅日志警告不阻断 |
| 原子性保障 | — | — | — | — | — | — | O_EXCL 文件创建防并发 Session ID 冲突 | — | — | — | — | — | — | — | async with lock 保护 get_next_runnable_vertices 的状态更新 | — | — | — | — | — | — | — | — | — | Dolt 数据库事务 + git sync 保证数据一致性 | — | — |
| 消息隔离 | — | — | — | — | — | — | — | deepcopy(msg) 确保并行 Agent 间消息独立 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 订阅机制 | — | — | — | — | — | — | — | MsgHub 上下文管理器自动注册/清理订阅关系 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 动态参与者 | — | — | — | — | — | — | — | 运行时 add/delete 方法动态管理 MsgHub 参与者 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 流式监控 | — | — | — | — | — | — | — | stream_printing_messages 实时获取 Agent 中间输出 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 资源清理 | — | — | — | — | — | — | — | __aexit__ 自动清理订阅关系防止内存泄漏 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 调试友好 | — | — | — | — | — | — | — | enable_gather=False 支持顺序执行便于调试 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 极简设计 | — | — | — | — | — | — | — | sequential_pipeline 仅 4 行核心代码 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 记忆压缩 | — | — | — | — | — | — | — | — | token 超阈值触发 LLM 摘要 + retrieval_keys 去重标记 | — | ConciseMemoryAgent 每次 write_file 后清空历史只保留 plan | Write-Agent 写后清空上一步 tool_response 原文 | — | IterativeAgent 行预算控制 + smart_prune 裁剪低相关元素 | — | RoleZeroLongTermMemory 支持向量检索，memory_k 限制短期记忆条数 | — | — | — | compress_research 独立压缩模型，3 次重试 + 消息裁剪 | — | compressAgentLoopMessages 按 token 预算归档早期消息为 DriveFile | create_msg_delete 在分析师阶段间清空消息，辩论历史用字符串拼接 | — | — | — | — |
| 自适应参数 | — | — | — | — | — | — | — | — | TOKEN_GROWTH_FACTOR=0.9 随摘要增长动态调整压缩阈值 | — | — | 熵驱动部分采样：按 token 困惑度动态选择分支点 | — | 根据 query_complexity 动态调整迭代轮数/阈值/行预算 | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 查询分解策略 | — | — | — | — | — | — | — | — | LLM 结构化输出 QueryAnalysis，最多拆分 3 个子查询 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 子代理模型降级 | — | — | — | — | — | — | — | — | — | SubAgent.model 字段支持指定更便宜的模型 | — | — | — | — | — | — | — | — | — | compression_model 可配置为更便宜的模型（默认 gpt-4.1 vs 研究用同款） | — | — | — | — | — | — | — |
| 双流水线 | — | — | — | — | — | — | — | — | — | — | Paper-to-Code(8阶段) 和 Chat-to-Code(4阶段) 共享实现层 | Search→Write 和 多Rollout→Report→Integrate 两条独立流水线 | — | — | — | 经典 SOP（use_fixed_sop）和 MGX 动态路由（use_mgx）共存于同一 Team | — | — | — | 同时维护 legacy(Send API 扇出) 和新版(ConductResearch tool_call) 两套编排 | — | — | — | — | — | — | mini/short 精简流水线（跳过知识增强/事实核查）vs medium/long 完整流水线 |
| 对抗性推理 | — | — | — | — | — | — | — | — | — | — | — | INTEGRATE_PROMPT 要求批判性评估多份报告的一致性与可信度 | — | — | — | — | — | — | — | — | — | — | Bull/Bear 2方投资辩论 + Aggressive/Conservative/Neutral 3方风险辩论 | — | — | — | — |
| 多路径采样 | — | — | — | — | — | — | — | — | — | — | — | sampling_budget 控制总路径数，支持全轨迹和部分采样两种模式 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 困惑度分支 | — | — | — | — | — | — | — | — | — | — | — | 基于 logprobs 计算 think/tool_call/mixed 三种困惑度模式选择分支点 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 可视化驱动 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 图结构直接映射画布拖拽连线，前端 JSON 双向序列化 | — | — | — | — | — | — | — | — | — | — | — | — |
| 双层LLM策略 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 子代理可指定不同 model 参数使用更便宜的模型 | — | — | research_model 用于 Supervisor+Researcher，compression_model 用于压缩，final_report_model 用于报告 | — | — | quick_think 用于分析/辩论，deep_think 仅用于 Manager/Judge 裁决 | — | — | — | 13 个 Agent 分配到 fast/smart/strategic 三级，环境变量可逐 Agent 覆盖 |
| 生产者消费者解耦 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | NestJS @Processor 装饰器自动注册 BullMQ Worker | — | asyncio.Queue 解耦 SSE 消费者与 pipeline 生产者 | — | — | — |
| A2A协议集成 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 基于 a2a.types.AgentCard 标准化能力声明与跨进程通信 | — | — | — |
| Generator-Critic Loop | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | section_evaluate(Critic) ↔ section_improve(Generator) 循环，4 维度评分 |
最佳实践
1.从简单开始：单 Agent + 多工具往往比多 Agent 更容易调试
2.明确角色边界：每个 Agent 的职责要清晰，避免职责重叠
3.状态要可序列化：Agent 间传递的状态必须可序列化，便于持久化和恢复
4.超时和熔断：并行 Agent 需要超时机制，防止单个 Agent 阻塞整体
5.结果验证：汇聚结果时要检查一致性，处理冲突
6.进程级隔离优于线程级：避免 asyncio 事件循环冲突和 GIL 限制
7.自复用脚本模式：子进程复用同一入口脚本 + --signature 过滤，减少代码重复
8.STOP_SIGNAL + max_steps 双保险：LLM 自主收敛为主，硬上限为兜底
9.事件不可变性：使用 deepFreeze 保证事件 payload 在传播过程中不被篡改
10.origin 回声抑制：路由分发时跳过事件来源通道，防止消息回环
11.load 与 init 分离：批量加载插件后统一初始化，支持加载后检查和补丁
12.验证前置：spawn 前先验证 issue 存在和插件可用，避免创建孤儿资源
13.原子性 ID 预留：用 O_EXCL 文件创建防止并发 spawn 的 ID 冲突
14.元数据 Bash 兼容：key=value 格式让外部脚本和 hook 可直接读写 session 状态
15.enrichment 超时保护：session 列表查询时每个 session 的 runtime 探测限时 2s
16.反应引擎与通知解耦：reaction 处理事件时抑制重复通知，避免绕过升级策略
17.原子性 ID 预留：用 O_EXCL 文件创建防止并发 spawn 时 Session ID 冲突
18.轮询重入保护：polling flag 防止上一轮未完成时下一轮重入
19.2s 超时保护：list 枚举时每个 session 的 runtime 探测设 2s 上限，防止慢探测阻塞全局
20.逆序销毁：kill 时按 runtime → workspace → metadata 逆序清理，每步 best-effort 不阻塞
21.原子 ID 预留：用 O_EXCL 文件锁防止并发 spawn 冲突，比数据库锁更轻量
22.逆序资源清理：spawn 流水线每步失败都清理前面已创建的资源，不留残留
23.Agent 名称持久化：metadata 中记录 agent 插件名，LifecycleManager 据此选择正确的检测策略
24.上下文管理器模式：用 __aenter__/__aexit__ 自动管理资源生命周期
25.订阅者过滤自己：reset_subscribers 时过滤掉自己避免自循环
26.函数式+类式双接口：函数式适合一次性使用，类式适合参数预配置复用
27.并发/顺序可切换：enable_gather 参数支持生产并发、调试顺序
28.Send API 初始状态最小化：只传 question 和 index，不传主图的 messages，确保子图状态干净
29.双重去重：状态层 retrieval_keys 追踪 + prompt 层指令约束，防止重复检索
30.默认注入 general-purpose 子 Agent：确保主 Agent 始终有兜底的任务委托能力
31.状态过滤白名单优于黑名单：明确排除 key 比传递全部状态更安全
32.子 Agent 中间件栈不含编排中间件：天然阻断递归 spawn 无需额外计数器
33.MCP Server 绑定实现工具隔离：每个 Agent 只看到自己需要的工具，减少工具选择干扰
34.fan-in/fan-out 用于独立分析任务：概念分析和算法分析无依赖时并行可节省约 50% 时间
35.分析循环检测：跟踪最近 N 次工具调用，全部为读操作时注入写操作纠正指令
36.用计算换准确率：对高价值任务启动多条独立推理路径交叉验证
37.分类限流：不同类型资源（LLM/搜索/访问）用独立信号量避免互相阻塞
38.批判性聚合优于投票：让 LLM 评估多份报告的可信度比简单多数投票更可靠
39.JSONL 流式写入：每完成一条结果立即追加写入，天然支持断点续传
40.联邦制编排：不同模块可以有不同的编排模式，不必强行统一
41.懒初始化：非必需的 Agent 延迟到首次使用时创建，减少资源浪费
42.Async Wrapper：为非线程安全组件提供异步包装，支持并行模式平滑切换
43.中间件硬截断比 prompt 软约束更可靠：LLM 不一定遵守数量限制
44.双线程池分离调度与执行：避免超时等待占用执行资源导致死锁
45.子代理配置用 dataclass 声明式定义：新增类型只需加文件不改代码
46.工具裁剪优于权限检查：通过不注册工具而非运行时拦截来实现子代理能力限制，更简单更安全
47.结果自然化指令嵌入：在 announce 内容中直接包含摘要指令，让主代理 LLM 自动生成面向用户的自然语言
48.四维停止信号互为兜底：confidence/iterations/budget/ROI 四个独立条件确保迭代一定会终止
49.调度状态与图结构分离：RunnableVerticesManager 独立管理运行时状态，图结构保持不可变
50.循环顶点区分首次与后续执行：首次放宽前驱约束允许启动，后续严格等待防止数据竞争
51.条件排除需要同源清除：同一路由器重新评估时先清除之前的排除记录再设置新的
52.消息路由解耦：Role 不直接调用 Role，通过 Environment 消息总线解耦
53.idle 三条件检测：msg_buffer 为空 + 无 todo + 无 news 才判定为 idle
54.TeamLeader 暂停等待：分配任务后 _set_state(-1) 暂停自身，等待成员反馈再继续
55.双重递归防护：深度计数器和工具过滤同时使用，单一机制可能被绕过
56.子代理上下文隔离：不传递历史和 hooks，防止父级对话污染子任务推理
57.事件冒泡可观测：SubAgentStart/End 事件包含 depth/iterations/model 完整指标
58.工具白名单优于黑名单：子 Agent 只注册被明确授予的工具，比排除危险工具更安全
59.结果通过消息总线回传：避免子 Agent 直接持有主 Agent 引用，降低耦合
60.工具调用即编排：让 LLM 通过 tool_calls 自主决定子任务拆分，比硬编码 DAG 更灵活
61.压缩即出口：子 Agent 必须经过压缩节点才能回传结果，防止上下文爆炸
62.并发切片而非静默丢弃：超限调用返回明确错误消息，让 LLM 学会控制并发数
63.override_reducer 双模式：同一 reducer 支持追加和覆盖，简化状态重置逻辑
64.CAS 乐观并发：用 updateMany + where status 条件替代悲观锁，天然幂等
65.轮询自终止：每次轮询检查是否还有 pending 节点，无则停止重新入队
66.工具调用签名去重：将 tool_calls 序列化为排序后的签名字符串检测循环
67.辩论用轻量模型、裁决用强模型：双层 LLM 策略平衡成本与决策质量
68.辩论轮次硬上限：用 count 计数器而非语义判断控制辩论终止，确保可预测的执行时间
69.角色独立记忆：每个辩论角色持有独立的 BM25 记忆实例，避免跨角色经验污染
70.阶段间消息清空：分析师完成后清空 messages，防止后续节点被无关 tool-call 消息干扰
71.三层分离：意图分类、任务规划、执行协调各自独立，避免单层 Orchestrator 过载
72.Schema 驱动层间通信：用 Pydantic 模型约束每层的输入输出，编译时类型安全 + 运行时校验
73.懒初始化 LLM Agent：避免启动时 API key 缺失导致全局失败，首次调用时才创建
74.Agent 名称校验：Planner 输出的 agent_name 必须在合法注册表中，防止 LLM 幻觉路由到不存在的 Agent
75.计算而非存储：编排状态应从底层数据实时计算，避免冗余状态表导致不一致
76.结构验证前置：在创建 swarm 前执行 DAG 结构检查，比运行时检测 + 超时更可靠
77.依赖类型分级：区分 blocking 和 non-blocking 依赖，只有 blocking 类型参与调度计算
78.权限默认继承、按需隔离：isInheritTools 默认 true 减少配置，安全场景显式设为 false
79.目录即配置：用约定的目录结构（agents/ + commands/ + settings.json）替代复杂的编排 DSL
80.Hook 不阻塞主流程：Hook 超时和错误不应中断 Agent 执行，仅记录警告
81.动态计算 recursion_limit：基于实际节点数和最大循环次数，避免硬编码
82.收敛检测用分数增益阈值而非固定轮数：防止无效迭代浪费 token
83.Future 对象不放入 DAG state：避免序列化框架（msgpack/pickle）失败
84.环境变量 AND StyleProfile 双开关：全局禁用和运行时禁用互不干扰