Agent Orchestrate

Agent Orchestration — Quick Reference

Simple patterns for multi-agent coordination. For advanced dynamic orchestration, see cord-trees.

Core Primitives

ToolPurposesessions_spawnCreate isolated sub-agent with tasksubagents listCheck status of running agentssubagents steerSend guidance to running agentsubagents killTerminate an agentsessions_sendMessage another session

Spawn vs Fork

Two context strategies for sub-agents:

Spawn (Clean Slate)

• Sub-agent gets only its task prompt. No parent context.
• Use when:
• Task is self-contained
• You want isolation (no context bleed)
• Subtask doesn't need sibling results
• Cheaper/faster (smaller context)
• Example: "Research competitor X" — doesn't need to know about competitors Y and Z.

Fork (Context-Inheriting)

• Sub-agent receives accumulated results from siblings.
• Use when:
• Synthesis/analysis across prior work
• Task builds on what others discovered
• Final integration step
• Implementation: Include sibling results in the task prompt:
• Task: Synthesize findings into recommendation.
• Prior research:
• Competitor A: [result from agent 1]
• Competitor B: [result from agent 2]
• Market trends: [result from agent 3]

1. Parallel Fan-Out

Spawn N independent agents, wait for all to complete. # Pseudocode tasks = ["research A", "research B", "research C"] for task in tasks: sessions_spawn(task=task, label=f"research-{i}") # Poll until all complete while not all_complete(subagents list): wait(30s) # Collect results from session histories See: references/fan-out.md

2. Pipeline (Sequential)

Each agent's output feeds the next. Agent 1: Research → Agent 2: Analyze (using research) → Agent 3: Write (using analysis) 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. #1 Research API surface #2 Research GraphQL tradeoffs #3 Analysis (blocked-by: #1, #2) #4 Recommendation (blocked-by: #3) 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. Agent 1: Draft proposal → [CHECKPOINT: Human approves/rejects] → Agent 2: Implement approved proposal 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. while agents_running: status = subagents list for agent in status: if stuck_too_long(agent): subagents steer(target=agent, message="Try alternative approach...") if clearly_failed(agent): subagents kill(target=agent) # Retry or escalate

State Management

For complex orchestrations, track state in a file: // orchestration-state.json { "tasks": { "research-a": {"status": "complete", "result": "...", "sessionKey": "..."}, "research-b": {"status": "running", "sessionKey": "..."}, "synthesis": {"status": "blocked", "blockedBy": ["research-a", "research-b"]} } } Update after each spawn, completion check, or state change.

Best Practices

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

SituationPatternN independent research tasksFan-outStep A → Step B → Step CPipelineComplex task with prerequisitesDependency treeNeed human approval mid-flowHuman-in-the-loopLong-running with potential issuesSupervisorSimple one-off subtaskJust spawn one agent

Quick Reference

# Spawn a sub-agent sessions_spawn(task="Do X", label="my-task", runTimeoutSeconds=300) # Check status subagents(action="list") # Send guidance subagents(action="steer", target="my-task", message="Focus on Y instead") # Kill runaway subagents(action="kill", target="my-task")