Multi-Agent Orchestration

Complex work benefits from specialists. This part introduces the swarm completions endpoint and walks through the major orchestration architectures: sequential pipelines, parallel fan-outs, hierarchical teams, collaborative patterns, and directed graphs. You will learn to pick the right one on sight.

105 min · 9 lessons · checkpoint · 7-question quiz

Part 3 progress · 0/9 lessons0 pts · Recruit

You will learn to

Structure a SwarmSpec request for POST /v1/swarm/completions
Build sequential pipelines where each agent refines the last agent's output
Run independent analyses in parallel with ConcurrentWorkflow
Coordinate specialist teams with HierarchicalSwarm
Choose among GroupChat, MixtureOfAgents, MajorityVoting, and more
Express fan-out/fan-in DAGs with the GraphWorkflow endpoint
Stream every agent's tokens and fan swarms across multiple tasks

Lessons in this part

3.1From one agent to a swarm
3.2SequentialWorkflow: the pipeline
3.3ConcurrentWorkflow: the fan-out
3.4HierarchicalSwarm: the team with a director
3.5Collaboration patterns: debate, consensus, and councils
3.6Routing and dynamic architectures
3.7GraphWorkflow: directed acyclic graphs
3.8Streaming swarms and running multiple tasks
3.9Choosing the right architecture
✦Checkpoint project: an investment memo swarm
?Knowledge check (7 questions)

Lesson 3.1

From one agent to a swarm

A single agent with a long prompt tends to blur roles: the same context window is asked to research, critique, and summarize at once. A swarm splits those roles into separate agents, each with a focused system prompt, and an orchestration pattern that controls how they interact. The result is usually higher quality output and prompts that are far easier to maintain.

Every multi-agent request goes to one endpoint and uses the SwarmSpec schema:

POST/v1/swarm/completions

Field	What it does
name	Identifier for the swarm run
description	What this swarm accomplishes
swarm_type	The orchestration architecture (the heart of this part)
agents	Array of AgentSpec objects; everything from Parts 1 and 2 applies
task	The objective the swarm works on
max_loops	How many rounds the swarm may run
stream	Stream tokens from every agent in real time

The swarm_type field selects the architecture. You can list every supported value at any time:

GET/v1/swarms/available

Try it liveGET/v1/swarms/available

Free; consumes no credits.

Lesson 3.2

SequentialWorkflow: the pipeline

The simplest and most widely used architecture. Agents run in the order you list them, and each agent receives the previous agent's output. Use it whenever the work is a series of dependent steps: draft then edit, extract then analyze then summarize.

sequential_swarm.py

payload = {
    "name": "Content Pipeline",
    "description": "Research, write, and edit an article",
    "swarm_type": "SequentialWorkflow",
    "task": "Produce a short article on grid-scale battery storage.",
    "agents": [
        {
            "agent_name": "Researcher",
            "system_prompt": "Gather the key facts and figures on the topic.",
            "model_name": "gpt-4.1",
            "max_loops": 1,
        },
        {
            "agent_name": "Writer",
            "system_prompt": "Turn the research into a clear 400-word article.",
            "model_name": "claude-sonnet-4-20250514",
            "max_loops": 1,
        },
        {
            "agent_name": "Editor",
            "system_prompt": "Tighten the prose and fix any factual slips.",
            "model_name": "gpt-4.1",
            "max_loops": 1,
        },
    ],
}

response = requests.post(
    f"{BASE_URL}/v1/swarm/completions", headers=headers, json=payload
)
print(response.json()["output"])

Tip · Order is the design

In a sequential swarm, the agent list is the architecture. Put cheap extraction early and expensive synthesis late, and make each system prompt state what it receives and what it must pass on.

Run your first swarm right now. Two agents, in sequence, on a small task (expect this to take noticeably longer than a single-agent call, since the agents run one after another):

Try it livePOST/v1/swarm/completions

Runs two agents on your account; costs more than a single completion.

Lesson 3.3

ConcurrentWorkflow: the fan-out

When analyses are independent of each other, run them at the same time. Every agent receives the same task in parallel, and their outputs are collected together. This is the pattern for multi-angle analysis: four specialists examining one earnings call, or separate agents covering technology, market, and regulatory angles of the same question.

concurrent_swarm.py

payload = {
    "name": "Competitive Intelligence",
    "swarm_type": "ConcurrentWorkflow",
    "task": "Assess Tesla's position in the energy storage market.",
    "agents": [
        {
            "agent_name": "Technology Analyst",
            "system_prompt": "Evaluate the technology stack and moats.",
            "model_name": "gpt-4.1",
        },
        {
            "agent_name": "Market Analyst",
            "system_prompt": "Evaluate market share, pricing, and growth.",
            "model_name": "gpt-4.1",
        },
        {
            "agent_name": "Risk Analyst",
            "system_prompt": "Evaluate regulatory and supply chain risks.",
            "model_name": "gpt-4.1",
        },
    ],
}

Concurrent runs finish in roughly the time of the slowest agent rather than the sum of all agents, so this architecture also buys latency. A common composite pattern adds a final synthesizer: run the fan-out concurrently, then feed the collected outputs to one agent that writes the unified report.

Lesson 3.4

HierarchicalSwarm: the team with a director

A hierarchical swarm adds management: a director agent decomposes the task, assigns work to specialist workers, reviews what comes back, and synthesizes the final answer. Use it when the task is broad enough that deciding who does what is itself part of the work. This is the architecture behind due diligence swarms, code review teams, and clinical case conferences.

hierarchical_swarm.py

payload = {
    "name": "Investment Research Team",
    "swarm_type": "HierarchicalSwarm",
    "task": "Produce an investment memo on the AI infrastructure sector.",
    "agents": [
        {
            "agent_name": "Portfolio Director",
            "system_prompt": (
                "You direct a research team. Break the task down, "
                "delegate to your analysts, then synthesize their "
                "findings into a single memo with a recommendation."
            ),
            "model_name": "claude-sonnet-4-20250514",
            "role": "director",
        },
        {
            "agent_name": "Fundamentals Analyst",
            "system_prompt": "Analyze revenue, margins, and growth.",
            "model_name": "gpt-4.1",
            "role": "worker",
        },
        {
            "agent_name": "Macro Analyst",
            "system_prompt": "Analyze rates, spending cycles, and demand.",
            "model_name": "gpt-4.1",
            "role": "worker",
        },
    ],
}

Tip · Spend on the director

The director does the hardest cognitive work: decomposition and synthesis. Give it your strongest model and give workers cheaper ones. This single decision often halves swarm cost without hurting quality.

Lesson 3.5

Collaboration patterns: debate, consensus, and councils

Beyond pipelines and hierarchies, the API ships architectures where agents deliberate with each other. Each is a single swarm_type value away:

swarm_type	How it works	Reach for it when
GroupChat	Agents converse in a shared thread, building on each other's ideas	Brainstorming and cross-functional planning
MixtureOfAgents	Diverse specialists tackle the same task; outputs are combined	Problems that benefit from several kinds of expertise
MajorityVoting	Multiple agents answer independently; the majority wins	Quality assurance and high-stakes classification
DebateWithJudge	A Pro and Con agent argue; a judge synthesizes the verdict	Decisions where you want both sides argued hard
LLMCouncil	A council of different models peer-reviews, a chairman synthesizes	Reducing single-model bias on important answers
CouncilAsAJudge	A council evaluates a response across multiple dimensions	Scoring and evaluating AI output itself

These patterns trade tokens for reliability: five voters cost five times one answer. Use them where a wrong answer is expensive, and use a single agent where it is not.

Lesson 3.6

Routing and dynamic architectures

Three architectures handle work whose shape is not known in advance:

MultiAgentRouter: a dispatcher reads each incoming task and routes it to the best-suited agent. This is the IT-helpdesk pattern: one entry point, many specialists.
AgentRearrange: you describe the flow between agents in a rearrange_flow string, mixing sequential and parallel hops, and the swarm reorganizes to match.
HeavySwarm: the task is decomposed into specialized questions answered by dedicated research agents, then integrated. Built for deep, comprehensive analysis passes.

agent_rearrange.py

payload = {
    "name": "Custom Flow",
    "swarm_type": "AgentRearrange",
    "task": "Analyze this product launch plan.",
    "rearrange_flow": "Researcher -> Analyst1, Analyst2 -> Summarizer",
    "agents": [
        {"agent_name": "Researcher", "system_prompt": "Gather facts."},
        {"agent_name": "Analyst1", "system_prompt": "Assess strengths."},
        {"agent_name": "Analyst2", "system_prompt": "Assess risks."},
        {"agent_name": "Summarizer", "system_prompt": "Write the brief."},
    ],
}

The flow string reads left to right: commas mean those agents run in parallel, arrows mean the output moves to the next stage.

Lesson 3.7

GraphWorkflow: directed acyclic graphs

For production pipelines with genuine branching (fan-out into parallel branches that converge into a synthesis node), use the dedicated graph endpoint. Agents are nodes; edges define how data flows between them. The platform compiles the graph, runs independent branches in parallel, and joins them where edges converge:

POST/v1/graph-workflow/completions

graph_workflow.py

payload = {
    "name": "Lead Enrichment DAG",
    "task": "Research and score this sales lead: Acme Robotics.",
    "agents": [
        {"agent_name": "CompanyResearch", "system_prompt": "Research the company."},
        {"agent_name": "NewsResearch", "system_prompt": "Find recent news."},
        {"agent_name": "TechStack", "system_prompt": "Identify their tech stack."},
        {"agent_name": "Synthesizer", "system_prompt": "Merge all research."},
        {"agent_name": "Scorer", "system_prompt": "Score the lead 1-100."},
    ],
    "edges": [
        {"source": "CompanyResearch", "target": "Synthesizer"},
        {"source": "NewsResearch", "target": "Synthesizer"},
        {"source": "TechStack", "target": "Synthesizer"},
        {"source": "Synthesizer", "target": "Scorer"},
    ],
}

response = requests.post(
    f"{BASE_URL}/v1/graph-workflow/completions",
    headers=headers,
    json=payload,
)

The three research nodes run in parallel, the synthesizer waits for all of them, and the scorer runs last. Edges accept optional metadata (severity, priority, routing tags) so operations teams can filter and audit per-edge behavior in production.

Lesson 3.8

Streaming swarms and running multiple tasks

Everything you learned about single-agent streaming scales up. Set stream: true on the SwarmSpec and the endpoint emits tokens from every agent in the workflow as they generate, tagged by agent, so a UI can show a sequential pipeline handing off in real time or parallel agents interleaving:

swarm_streaming.py

payload = {
    "name": "Streaming Pipeline",
    "swarm_type": "SequentialWorkflow",
    "task": "Draft and refine a product announcement.",
    "stream": True,
    "agents": [
        {"agent_name": "Drafter", "system_prompt": "Write the first draft."},
        {"agent_name": "Refiner", "system_prompt": "Polish the draft."},
    ],
}

with requests.post(
    f"{BASE_URL}/v1/swarm/completions",
    headers=headers,
    json=payload,
    stream=True,
) as response:
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

Swarms can also carry more than one task. The tasks array runs a workflow across a list of objectives, and the dedicated BatchedGridWorkflow endpoint fans multiple agents across multiple tasks in a grid, all in a single request:

POST/v1/batched-grid-workflow/completions

grid_workflow.py

payload = {
    "name": "ETF Grid",
    "agents": [
        {"agent_name": "Tech Analyst", "system_prompt": "Analyze tech exposure."},
        {"agent_name": "Risk Analyst", "system_prompt": "Analyze risk profile."},
    ],
    "tasks": [
        "Evaluate the QQQ ETF.",
        "Evaluate the SPY ETF.",
    ],
}

response = requests.post(
    f"{BASE_URL}/v1/batched-grid-workflow/completions",
    headers=headers,
    json=payload,
)

Note · Grid is a premium feature

BatchedGridWorkflow, like the batch endpoints you will meet in Part 4, is available on Pro and Ultra plans. Every agent runs every task, so a 2-agent, 2-task grid executes 4 completions.

Lesson 3.9

Choosing the right architecture

Architecture selection is the highest-leverage decision in multi-agent design. A workable rule of thumb:

Your task looks like	Use
Dependent steps in a fixed order	SequentialWorkflow
Independent analyses of one input	ConcurrentWorkflow
Broad task needing decomposition and synthesis	HierarchicalSwarm
Open-ended ideation across functions	GroupChat
One entry point, many task types	MultiAgentRouter
High-stakes answer needing consensus	MajorityVoting or LLMCouncil
Branching pipeline with converging stages	GraphWorkflow

Tip · Start sequential, grow deliberately

Most production systems begin as a 2-3 agent SequentialWorkflow. Add parallelism when latency demands it and hierarchy when task decomposition demands it. Complexity you add before you need it is complexity you debug anyway.

Checkpoint · Part 3

Checkpoint project: an investment memo swarm

Build the same deliverable three ways and compare:

Produce a one-page investment memo on a sector you know, first with a single agent from Part 1
Rebuild it as a SequentialWorkflow (researcher, analyst, writer) and note the quality difference
Rebuild it as a HierarchicalSwarm with a director and two workers, giving the director a stronger model
Compare cost from the usage field of each run against the quality gain, and write down which you would ship

That cost-versus-quality judgment, made consciously, is exactly the skill Part 4 turns into production discipline.

Knowledge check · Part 3

Test what you remember

7 questions. Answer from memory before checking; look back at the lessons only after you see your score.

1.Which endpoint executes a multi-agent swarm?
2.Your task is four dependent steps: extract, analyze, draft, edit. Which architecture fits best?
3.In a HierarchicalSwarm, where should you spend your strongest (most expensive) model?
4.In an AgentRearrange flow string "A -> B, C -> D", what happens after A finishes?
5.How does GraphWorkflow differ from the other architectures in this part?
6.You need one high-stakes answer and can afford redundancy. Which pattern trades tokens for reliability?
7.A 3-agent, 4-task BatchedGridWorkflow executes how many completions?

0 of 7 answered

Previous · Part 2Single-Agent Capabilities Next · Part 4Production: Scale, Cost, and Operations