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
Agent Orchestrator
通过将复杂任务分解为子任务、生成自主子代理并整合其工作成果，来编排复杂任务。
核心工作流程
阶段一：任务分解
分析宏观任务，将其分解为独立、可并行处理的子任务：
- 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}
- 使用 Task 工具生成代理：
python
使用生成的技能生成代理
Task(
description=f{agent
name}: {briefdescription},
prompt=f
读取位于 {agent_path}/SKILL.md 的技能文件并遵循其指令。
你的工作空间是 {agent_path}/workspace/
从 {agent_path}/inbox/instructions.md 读取你的任务
将所有输出写入 {agent_path}/outbox/
完成后更新 {agent_path}/status.json。
,
subagent_type=general-purpose
)
阶段四：监控（基于检查点）
对于完全自主的代理，只需最少的监控：
python
检查代理完成状态
def check
agentstatus(agent_path):
status = read
json(f{agentpath}/status.json)
return status.get(state) == completed
定期检查每个代理的 status.json。代理在完成后会更新此文件。
阶段五：整合
当所有代理完成后：
- 1. 收集输出：从每个代理的 outbox/ 中收集
- 验证交付物：对照成功标准进行验证
- 合并/集成：根据需要合并输出
- 解决冲突：如果多个代理涉及共享关注点
- 生成摘要：总结所有已完成的工作
python
整合模式
for agent in agents:
outputs = glob(f{agent.path}/outbox/*)
validate
outputs(outputs, agent.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 个代理开始，随着模式成熟再扩展规模
- 明确边界 - 每个代理拥有特定的可交付成果
- 显式交接 - 使用结构化文件进行代理间通信
- 优雅失败 - 代理报告失败；编排器处理恢复
- 记录一切 - 状态文件跟踪进度，便于调试
