Orchestration

Kick off multi-phase, multi-agent sessions with a single API call.

Two-agent pair sessions are the atom. Orchestration is how you compose three or more of them into a pipeline.

The idea#

Describe a team of agents, a sequence of phases (who does what, then who does what next), and Hyperbolic will:

Create a session with all agents pre-joined.
Mint one agent token per participant.
Seed a notes document with the phase plan.
Send an initial handoff to the first agent.

Example: architect → coder → reviewer#

const { session, tokens } = await pair.orchestrate({
  name: "Build /billing page",
  agents: [
    { id: "architect", name: "Architect", capabilities: ["spec"] },
    { id: "coder",     name: "Coder",     capabilities: ["code"] },
    { id: "reviewer",  name: "Reviewer",  capabilities: ["review"] },
  ],
  phases: [
    { agent: "architect", task: "Write the requirements and component breakdown into the 'Spec' note.",        handoffTo: "coder" },
    { agent: "coder",     task: "Implement the page. Write code as files under pages/billing/*.",               handoffTo: "reviewer" },
    { agent: "reviewer",  task: "Review the diff. Leave comments as a note titled 'Review'. Complete if ready." },
  ],
});
 
console.log(session.id);
console.log(tokens.architect, tokens.coder, tokens.reviewer);

Each agent then boots with its own token and reads the current phase from the seeded note. Handoffs are regular handoff messages — the next agent's SDK picks them up over SSE.

Template-based orchestration#

If you orchestrate the same shape of pipeline often, extract it into a template:

const { session } = await pair.orchestrate({
  name: "Build /billing page",
  agents: [/* as above */],
  templateId: "tpl_three_phase_build",
});

REST#

curl -X POST https://api.hyperbolic.sh/api/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Build /billing page",
    "agents": [{"id":"architect"},{"id":"coder"},{"id":"reviewer"}],
    "phases": [
      {"agent":"architect","task":"…","handoffTo":"coder"},
      {"agent":"coder","task":"…","handoffTo":"reviewer"},
      {"agent":"reviewer","task":"…"}
    ]
  }'

Orchestration vs. DIY#

You can always build a pipeline yourself with multiple createSession / joinSession calls. Orchestration is a convenience for the common case — one session, one task, many agents, linear phases.

For fan-out/fan-in patterns or genuinely parallel work, spin up multiple sessions and coordinate them with a controller agent that watches their SSE streams.

Observers compose nicely

Hand the session's observer token to a human and they can watch the entire three-agent pipeline from one browser tab.

Observers

Compute jobs