Agent Orchestration — Quick Reference
Simple patterns for multi-agent coordination. For advanced dynamic orchestration, see cord-trees.
Core Primitives
| Tool | Purpose |
|---|
| INLINECODE0 | Create isolated sub-agent with task |
| INLINECODE1 |
Check status of running agents |
|
subagents steer | Send guidance to running agent |
|
subagents kill | Terminate an agent |
|
sessions_send | Message another session |
Spawn vs Fork
Two context strategies for sub-agents:
Spawn (Clean Slate)
Sub-agent gets only its task prompt. No parent context.
CODEBLOCK0
Example: "Research competitor X" — doesn't need to know about competitors Y and Z.
Fork (Context-Inheriting)
Sub-agent receives accumulated results from siblings.
CODEBLOCK1
Implementation: Include sibling results in the task prompt:
CODEBLOCK2
Patterns
1. Parallel Fan-Out
Spawn N independent agents, wait for all to complete.
CODEBLOCK3
See: references/fan-out.md
2. Pipeline (Sequential)
Each agent's output feeds the next.
CODEBLOCK4
Implementation: Spawn agent 1, wait for completion, spawn agent 2 with agent 1's result, etc.
See: references/pipeline.md
3. Dependency Tree
Tasks with explicit dependencies. Don't start X until Y completes.
CODEBLOCK5
Implementation: Track state in a JSON file. Poll and spawn when dependencies clear.
See: references/dependency-tree.md
4. Human-in-the-Loop
Pause workflow for human input at checkpoints.
CODEBLOCK6
Implementation: Agent 1 completes, orchestrator messages human via sessions_send or channel message, waits for response before spawning agent 2.
5. Supervisor Pattern
Orchestrator monitors agents and intervenes when stuck.
CODEBLOCK7
State Management
For complex orchestrations, track state in a file:
CODEBLOCK8
Update after each spawn, completion check, or state change.
Best Practices
- 1. Label agents clearly — Use descriptive labels for
subagents list readability - Set timeouts — Use
runTimeoutSeconds to prevent runaways - Don't over-parallelize — More agents ≠ better. Consider token costs.
- Checkpoint expensive work — Write intermediate results to files
- Handle failures — Decide: retry, skip, or escalate to human
- Keep tasks focused — One clear goal per agent. Easier to debug.
Anti-Patterns
❌ Polling in tight loops — Use reasonable intervals (30s+)
❌ Spawning agents for trivial tasks — Just do it yourself
❌ Giant context dumps — Summarize, don't copy entire histories
❌ No failure handling — Agents fail. Plan for it.
Choosing a Pattern
| Situation | Pattern |
|---|
| N independent research tasks | Fan-out |
| Step A → Step B → Step C |
Pipeline |
| Complex task with prerequisites | Dependency tree |
| Need human approval mid-flow | Human-in-the-loop |
| Long-running with potential issues | Supervisor |
| Simple one-off subtask | Just spawn one agent |
Quick Reference
CODEBLOCK9
智能体编排 — 快速参考
多智能体协调的简单模式。关于高级动态编排，请参阅 cord-trees。
核心原语
| 工具 | 用途 |
|---|
| sessions_spawn | 创建带有任务的独立子智能体 |
| subagents list |
检查运行中智能体的状态 |
| subagents steer | 向运行中的智能体发送指导 |
| subagents kill | 终止一个智能体 |
| sessions_send | 向另一个会话发送消息 |
Spawn 与 Fork
子智能体的两种上下文策略：
Spawn（全新开始）
子智能体仅获得其任务提示。无父级上下文。
使用场景：
- - 任务是自包含的
- 需要隔离（无上下文泄漏）
- 子任务不需要同级结果
- 更便宜/更快（上下文更小）
示例：研究竞争对手 X — 不需要了解竞争对手 Y 和 Z。
Fork（继承上下文）
子智能体接收来自同级的累积结果。
使用场景：
- - 需要对先前工作进行综合/分析
- 任务建立在他人发现的基础上
- 最终整合步骤
实现：在同级结果中包含任务提示：
任务：将发现综合为建议。
先前研究：
- - 竞争对手 A：[来自智能体 1 的结果]
- 竞争对手 B：[来自智能体 2 的结果]
- 市场趋势：[来自智能体 3 的结果]
模式
1. 并行扇出
生成 N 个独立智能体，等待所有完成。
python
伪代码
tasks = [研究 A, 研究 B, 研究 C]
for task in tasks:
sessions_spawn(task=task, label=fresearch-{i})
轮询直到全部完成
while not all_complete(subagents list):
wait(30s)
从会话历史中收集结果
参见：references/fan-out.md
2. 流水线（顺序执行）
每个智能体的输出作为下一个的输入。
智能体 1：研究 →
智能体 2：分析（使用研究结果）→
智能体 3：撰写（使用分析结果）
实现：生成智能体 1，等待完成，用智能体 1 的结果生成智能体 2，以此类推。
参见：references/pipeline.md
3. 依赖树
具有显式依赖关系的任务。在 Y 完成之前不要启动 X。
#1 研究 API 接口
#2 研究 GraphQL 权衡
#3 分析（依赖：#1, #2）
#4 建议（依赖：#3）
实现：在 JSON 文件中跟踪状态。当依赖关系解除时进行轮询和生成。
参见：references/dependency-tree.md
4. 人机协同
在检查点暂停工作流以等待人工输入。
智能体 1：起草提案 →
[检查点：人工批准/拒绝] →
智能体 2：实施已批准的提案
实现：智能体 1 完成，编排器通过 sessions_send 或频道消息向人工发送消息，等待响应后再生成智能体 2。
5. 监督者模式
编排器监控智能体并在卡住时进行干预。
python
while agents_running:
status = subagents list
for agent in status:
if stucktoolong(agent):
subagents steer(target=agent, message=尝试替代方法...)
if clearly_failed(agent):
subagents kill(target=agent)
# 重试或升级
状态管理
对于复杂编排，在文件中跟踪状态：
json
// orchestration-state.json
{
tasks: {
research-a: {status: complete, result: ..., sessionKey: ...},
research-b: {status: running, sessionKey: ...},
synthesis: {status: blocked, blockedBy: [research-a, research-b]}
}
}
每次生成、完成检查或状态变更后更新。
最佳实践
- 1. 清晰标记智能体 — 使用描述性标签以便 subagents list 可读
- 设置超时 — 使用 runTimeoutSeconds 防止失控
- 不要过度并行化 — 智能体越多 ≠ 效果越好。考虑 Token 成本。
- 对重要工作进行检查点 — 将中间结果写入文件
- 处理失败 — 决定：重试、跳过或升级给人工
- 保持任务聚焦 — 每个智能体一个明确目标。更易于调试。
反模式
❌ 紧密循环轮询 — 使用合理间隔（30 秒以上）
❌ 为琐碎任务生成智能体 — 直接自己做
❌ 巨大的上下文转储 — 总结，不要复制整个历史
❌ 没有失败处理 — 智能体会失败。提前规划。
选择模式
| 场景 | 模式 |
|---|
| N 个独立研究任务 | 扇出 |
| 步骤 A → 步骤 B → 步骤 C |
流水线 |
| 具有前置条件的复杂任务 | 依赖树 |
| 流程中需要人工批准 | 人机协同 |
| 长时间运行且可能有问题的任务 | 监督者 |
| 简单的一次性子任务 | 只生成一个智能体 |
快速参考
bash
生成子智能体
sessions_spawn(task=执行 X, label=my-task, runTimeoutSeconds=300)
检查状态
subagents(action=list)
发送指导
subagents(action=steer, target=my-task, message=改为聚焦于 Y)
终止失控智能体
subagents(action=kill, target=my-task)
