Agent Team

Orchestrate a dynamic team of agents: one Orchestrator (opus) plans + delegates + synthesizes; multiple Worker agents (sonnet) execute specialized subtasks and communicate bidirectionally.

Architecture

User
  └─► Orchestrator (opus)
        ├─ plans team composition dynamically
        ├─ spawns Worker A (sonnet) ──┐
        ├─ spawns Worker B (sonnet)   │ bidirectional
        ├─ spawns Worker C (sonnet) ◄─┘ via sessions_send
        └─ aggregates → final report to user

Workflow

Step 1 — Orchestrator Plans the Team

Analyze the task and define 2–4 worker roles. Each role needs:

• Name: short label (e.g. researcher, coder, reviewer)
• Task: specific, scoped instruction
• Inputs needed from other workers: what it needs to receive before finishing (for bidirectional flow)

See references/role-patterns.md for common role combinations per scenario.

Step 2 — Spawn Workers

Spawn each worker as a persistent sub-agent session. Always set streamTo: "parent" so the user sees real-time output in their chat window:

# Pseudocode — use sessions_spawn tool
sessions_spawn(
  task="You are the [ROLE] agent. [SPECIFIC TASK]. 
        When you need input from another agent, send a message to session [SESSION_KEY].
        Report your final result clearly structured.",
  runtime="subagent",
  mode="session",          # persistent — can receive follow-up messages
  model="sonnet",          # worker uses sonnet
  label="worker-[role]",
  streamTo="parent"        # stream output to user's chat in real time
)

Spawn all independent workers in parallel (single tool call block). Only spawn sequentially when a worker strictly depends on another's output.

Step 3 — Bidirectional Communication

Workers can message each other via sessions_send. The orchestrator:

1. Gives each worker the session keys of peers it may need to consult
2. Monitors via subagents(action=list) — check on-demand, not in a loop
3. Can steer any worker mid-task: subagents(action=steer, target=<label>, message=<redirect>)

Direct worker-to-worker message pattern:

Worker A finishes partial result
  → sessions_send(sessionKey=worker-B-key, message="Here's my output: ...")
Worker B incorporates it, finishes
  → sessions_send(sessionKey=orchestrator-key, message="Done: ...")

Step 3.5 — Relay Progress to User (Orchestrator Broadcast)

After each worker completes, send a status update to the user before moving on:

"[worker-researcher] 完成 ✅ — 找到 12 条相关数据，传给 worker-analyst"
"[worker-analyst] 处理中... 等待 worker-researcher 结果"
"[worker-reviewer] 完成 ✅ — 发现 3 个风险点"

This gives the user full visibility into the team's progress without needing to check logs manually.

Step 4 — Aggregate Results

Once all workers report back, the orchestrator:

1. Synthesizes outputs into a coherent final answer
2. Resolves conflicts between workers' findings
3. Delivers structured report to the user