Agent Orchestrator
Orchestrate complex tasks by decomposing them into subtasks, spawning autonomous sub-agents, and consolidating their work.
Core Workflow
Phase 1: Task Decomposition
Analyze the macro task and break it into independent, parallelizable subtasks:
CODEBLOCK0
Decomposition Principles:
- - Each subtask should be completable in isolation
- Minimize inter-agent dependencies
- Prefer broader, autonomous tasks over narrow, interdependent ones
- Include clear success criteria for each subtask
Phase 2: Agent Generation
For each subtask, create a sub-agent workspace:
CODEBLOCK1
This creates:
CODEBLOCK2
Generate SKILL.md dynamically with:
- - Agent's specific role and objective
- Tools and capabilities needed
- Input/output specifications
- Success criteria
- Communication protocol
See references/sub-agent-templates.md for pre-built templates.
Phase 3: Agent Dispatch
Initialize each agent by:
- 1. Writing task instructions to INLINECODE0
- Copying required input files to INLINECODE1
- Setting
status.json to INLINECODE3 - Spawning the agent using the Task tool:
CODEBLOCK3
Phase 4: Monitoring (Checkpoint-based)
For fully autonomous agents, minimal monitoring is needed:
CODEBLOCK4
Periodically check status.json for each agent. Agents update this file upon completion.
Phase 5: Consolidation
Once all agents complete:
- 1. Collect outputs from each agent's INLINECODE5
- Validate deliverables against success criteria
- Merge/integrate outputs as needed
- Resolve conflicts if multiple agents touched shared concerns
- Generate summary of all work completed
CODEBLOCK5
Phase 6: Dissolution & Summary
After consolidation:
- 1. Archive agent workspaces (optional)
- Clean up temporary files
- Generate final summary:
- What was accomplished per agent
- Any issues encountered
- Final deliverables location
- Time/resource metrics
CODEBLOCK6
File-Based Communication Protocol
See references/communication-protocol.md for detailed specs.
Quick Reference:
- -
inbox/ - Read-only for agent, written by orchestrator - INLINECODE7 - Write-only for agent, read by orchestrator
- INLINECODE8 - Agent updates state:
pending â running â completed | INLINECODE12
Example: Research Report Task
CODEBLOCK7
Sub-Agent Templates
Pre-built templates for common agent types in references/sub-agent-templates.md:
- - Research Agent - Web search, data gathering
- Code Agent - Implementation, testing
- Analysis Agent - Data processing, pattern finding
- Writer Agent - Content creation, documentation
- Review Agent - Quality assurance, editing
- Integration Agent - Merging outputs, conflict resolution
Best Practices
- 1. Start small - Begin with 2-3 agents, scale as patterns emerge
- Clear boundaries - Each agent owns specific deliverables
- Explicit handoffs - Use structured files for agent communication
- Fail gracefully - Agents report failures; orchestrator handles recovery
- Log everything - Status files track progress for debugging
智能体编排器
通过将复杂任务分解为子任务、生成自主子智能体并整合其工作成果，来编排复杂任务。
核心工作流
第一阶段：任务分解
分析宏观任务，并将其分解为独立、可并行处理的子任务：
- 1. 明确最终目标和成功标准
- 列出所需的所有主要组件/交付物
- 确定各组件之间的依赖关系
- 将独立工作分组为并行子任务
- 为顺序工作创建依赖关系图
分解原则：
- - 每个子任务应能独立完成
- 尽量减少智能体间的依赖
- 优先选择范围更广、自主性更强的任务，而非狭窄、相互依赖的任务
- 为每个子任务包含明确的成功标准
第二阶段：智能体生成
为每个子任务创建一个子智能体工作空间：
bash
python3 scripts/create_agent.py <智能体名称> --workspace <路径>
这将创建：
<工作空间>/<智能体名称>/
├── SKILL.md # 为智能体生成的技能文件
├── inbox/ # 接收输入文件和指令
├── outbox/ # 交付已完成的工作
├── workspace/ # 智能体的工作区域
└── status.json # 智能体状态跟踪
动态生成 SKILL.md，包含：
- - 智能体的具体角色和目标
- 所需的工具和能力
- 输入/输出规范
- 成功标准
- 通信协议
预构建模板请参见 references/sub-agent-templates.md。
第三阶段：智能体调度
通过以下方式初始化每个智能体：
- 1. 将任务指令写入 inbox/instructions.md
- 将所需的输入文件复制到 inbox/
- 将 status.json 设置为 {state: pending, started: null}
- 使用任务工具生成智能体：
python
使用生成的技能生成智能体
Task(
description=f{智能体名称}: {简要描述},
prompt=f
读取位于 {智能体路径}/SKILL.md 的技能文件并遵循其指令。
你的工作空间是 {智能体路径}/workspace/
从 {智能体路径}/inbox/instructions.md 读取你的任务
将所有输出写入 {智能体路径}/outbox/
完成后更新 {智能体路径}/status.json。
,
subagent_type=通用型
)
第四阶段：监控（基于检查点）
对于完全自主的智能体，只需最少的监控：
python
检查智能体完成状态
def check
agentstatus(智能体路径):
status = read_json(f{智能体路径}/status.json)
return status.get(state) == completed
定期检查每个智能体的 status.json。智能体在完成后会更新此文件。
第五阶段：整合
当所有智能体完成后：
- 1. 收集输出 从每个智能体的 outbox/
- 验证交付物 是否符合成功标准
- 合并/集成 输出（根据需要）
- 解决冲突 如果多个智能体涉及共享关注点
- 生成摘要 所有已完成工作的总结
python
整合模式
for 智能体 in 智能体列表:
outputs = glob(f{智能体.path}/outbox/*)
validate
outputs(outputs, 智能体.successcriteria)
consolidated_results.extend(outputs)
第六阶段：解散与总结
整合后：
- 1. 归档智能体工作空间（可选）
- 清理临时文件
- 生成最终总结：
- 每个智能体完成了什么
- 遇到的任何问题
- 最终交付物位置
- 时间/资源指标
python
python3 scripts/dissolve_agents.py --workspace <路径> --archive
基于文件的通信协议
详细规范请参见 references/communication-protocol.md。
快速参考：
- - inbox/ - 对智能体只读，由编排器写入
- outbox/ - 对智能体只写，由编排器读取
- status.json - 智能体更新状态：pending → running → completed | failed
示例：研究报告任务
宏观任务：创建一份全面的市场分析报告
分解：
├── 智能体：数据收集器
│ └── 收集市场数据、竞争对手信息、趋势
├── 智能体：分析师
│ └── 分析收集的数据，识别模式
├── 智能体：撰稿人
│ └── 根据分析起草报告章节
└── 智能体：审阅者
└── 审阅、编辑并定稿报告
依赖关系：数据收集器 → 分析师 → 撰稿人 → 审阅者
子智能体模板
常见智能体类型的预构建模板位于 references/sub-agent-templates.md：
- - 研究智能体 - 网络搜索、数据收集
- 代码智能体 - 实现、测试
- 分析智能体 - 数据处理、模式发现
- 撰稿智能体 - 内容创作、文档编写
- 审阅智能体 - 质量保证、编辑
- 集成智能体 - 合并输出、解决冲突
最佳实践
- 1. 从小处着手 - 从2-3个智能体开始，随着模式成熟再扩展
- 边界清晰 - 每个智能体拥有特定的交付物
- 明确交接 - 使用结构化文件进行智能体间通信
- 优雅失败 - 智能体报告失败；编排器处理恢复
- 记录一切 - 状态文件跟踪进度，便于调试
