How to Build a Claude-Powered Multi-Agent System

What a Claude-powered multi-agent system actually is

A multi-agent system splits a complex task across several Claude instances, each with a narrow role, instead of asking one giant prompt to do everything. One agent plans, another researches, another writes code, another reviews it — and an orchestrator ties the outputs together. This matters because single-prompt setups degrade fast once a task requires multiple steps, tool calls, or conflicting priorities (speed vs. accuracy, breadth vs. depth).

The practical answer to "how to build" one is: define agent roles, give each a clear system prompt and scoped tools, pick an orchestration pattern (sequential, supervisor, or peer-to-peer), add shared state, and route everything through a single API layer so you can monitor cost and latency across all agents at once. Below is a working breakdown you can implement directly.

Step 1: Decide the agent roles

Most production multi-agent systems fall into one of three shapes:

• Sequential pipeline — Agent A's output becomes Agent B's input (research → draft → edit). Simple to debug, easy to reason about failures.
• Supervisor/worker — One orchestrator agent decomposes the task and dispatches subtasks to specialized workers (coder, tester, reviewer), then merges results.
• Peer-to-peer debate — Two or more agents critique each other's output iteratively until convergence (useful for red-teaming or fact-checking).

Start with sequential or supervisor/worker. Peer-to-peer is powerful but burns tokens fast and is harder to bound — only reach for it when quality matters more than cost.

Step 2: Give each agent a tight system prompt

The biggest failure mode in multi-agent systems isn't the orchestration logic — it's vague roles. Each agent should have a system prompt that states its only job, its output format, and what it should refuse to do.

SYSTEM (Researcher agent):
You research facts only. You never write final prose.
Return findings as a JSON array of {claim, source, confidence}.
If you cannot verify a claim, mark confidence as "low".

SYSTEM (Writer agent):
You write final copy from structured research input only.
You never invent facts not present in the input JSON.
Return plain markdown, no preamble.

Narrow roles reduce hallucination because each agent has less surface area to go wrong on, and it makes individual agents easy to test in isolation.

Step 3: Build the orchestrator

The orchestrator is just code — not necessarily a model call — that routes messages between agents and manages state. A minimal supervisor loop looks like this:

async function callAgent(systemPrompt, userMessage) {
  const res = await fetch("https://api.subtoapi.app/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-5",
      system: systemPrompt,
      max_tokens: 1024,
      messages: [{ role: "user", content: userMessage }]
    })
  });
  return (await res.json()).content[0].text;
}

async function runPipeline(topic) {
  const research = await callAgent(RESEARCHER_PROMPT, `Research: ${topic}`);
  const draft = await callAgent(WRITER_PROMPT, research);
  const review = await callAgent(REVIEWER_PROMPT, draft);
  return review;
}

This is deliberately simple — three sequential calls, each with a different system prompt, through one API key. The orchestration logic lives in plain JavaScript, not inside a prompt. That separation is what keeps multi-agent systems debuggable as they grow.

Step 4: Add tool use for agents that need to act, not just talk

Agents that only read and write text are limited. Give specific agents access to tools — a code execution sandbox, a database lookup, a web search — and let the model decide when to call them.

{
  "model": "claude-sonnet-4-5",
  "system": "You are a data agent. Use the lookup_order tool when asked about order status.",
  "tools": [
    {
      "name": "lookup_order",
      "description": "Fetch order status by ID",
      "input_schema": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      }
    }
  ],
  "messages": [{ "role": "user", "content": "Where is order 4821?" }]
}

Only give tools to the agents that need them. A reviewer agent that critiques prose doesn't need database access — scoping tools per agent is both a cost control and a safety boundary. See /docs/tools for the full tool-use request/response cycle.

Step 5: Manage shared state and token cost

Multi-agent systems multiply your token usage — three agents each with full context can cost 3-5x a single well-crafted prompt. A few practical rules:

• Pass summaries, not full conversation history, between agents.
• Cap each agent's max_tokens tightly to its actual job (a reviewer rarely needs 4000 tokens of output).
• Stream long-running agent outputs so your UI shows progress instead of a blank wait (/docs/streaming).
• Log every agent call's usage metadata so you can see which agent in the pipeline is actually driving cost — this is usually not the one you'd guess.

If you're building this on raw model access, you'll likely end up writing your own logging, retry, and key-management layer for every agent. SubToAPI turns that access into a standard HTTPS API with per-key usage metadata, so each agent in your pipeline can have its own sub_live_ key, its own rate limit, and its own line item in your dashboard — useful when you want to know exactly which agent is burning budget. Check /docs/quickstart to get a key running in a few minutes, or /docs/messages for the full request format used in the examples above.

Step 6: Handle failure and retries per agent

Treat each agent as a service with its own failure mode:

• Researcher fails to find sources → fall back to "low confidence" output rather than blocking the pipeline.
• Writer produces malformed output → validate against a schema and retry once with a stricter prompt before escalating to a human.
• Reviewer rejects the draft → loop back to the writer with the reviewer's specific objections, capped at 2-3 iterations to avoid infinite loops.

Bounded retries with explicit exit conditions are what separate a multi-agent system that ships from one that spins forever in a demo.

A minimal starting architecture

For most teams, this is enough to start:

1. One supervisor function (plain code) that defines the pipeline order.
2. 2-4 agents with narrow system prompts and scoped tools.
3. One shared API layer for keys, rate limits, and usage tracking — see /pricing for plan options if you're scaling this across a team.
4. Structured intermediate outputs (JSON) between agents, not free text.

Resist adding more agents than the task needs. Three well-scoped agents with clear handoffs will outperform six overlapping ones nearly every time.

FAQ

Do I need a special framework to build a multi-agent system with Claude? No. A supervisor loop in plain JavaScript or Python that makes sequential or parallel API calls is enough for most use cases. Frameworks help at scale but add debugging overhead early on.

How many agents should a first version have? Two or three. A researcher/writer/reviewer pipeline covers most content and analysis tasks. Add agents only when you can name a specific failure the current setup can't handle.

How do I control cost across multiple agents? Scope tools per agent, pass summaries instead of full history between steps, cap max_tokens per role, and track usage per API key so you can see which agent is driving spend — try it with a free trial at /signup.