Multi-Agent Orchestration with Claude Code: Patterns and Pitfalls

A single well-built Claude agent can do remarkable things. A coordinated team of agents — each specialized, each isolated, each observable — can do things that no single agent could handle alone. Multi-agent architecture isn’t just “more agents.” It’s a different operational model.

It’s also a different set of failure modes. Getting multi-agent right requires thinking carefully about isolation, identity, communication, and control.

Why Multi-Agent

The obvious reason is scale: some tasks are too large for a single agent’s context window or too time-consuming to run sequentially. But there are better reasons:

Specialization. A code-review agent configured for thoroughness operates differently than a deploy agent configured for speed. Mixing their contexts and instructions produces worse results than keeping them separate.

Isolation. A billing-automation project shouldn’t share credentials, audit trails, or error blast radius with a code-generation project. Separate agents means separate blast radii.

Parallelism. Independent subtasks can run simultaneously. A research agent gathering data in parallel with a summarization agent processing earlier results. Wallclock time drops even if total token cost is the same.

Redundancy and verification. Two independent agents analyzing the same dataset and comparing results is a validity check you can’t get from a single agent reviewing its own work.

Common Patterns

Pipeline (sequential). Agent A produces an artifact. Agent B takes that artifact as input and produces the next. Agent C takes B’s output and produces the final result. Each agent has a narrow scope and well-defined inputs/outputs.

Example: data-extractor agent pulls raw data from a source → normalizer agent cleans and structures it → reporter agent generates a formatted output document.

When to use: When steps have clear dependencies and each agent’s output can be fully specified before the next agent runs.

Fan-out (parallel, then merge). An orchestrator agent splits a large task into independent subtasks and dispatches them to worker agents. Workers run in parallel. Orchestrator collects results and produces a final output.

Example: research-orchestrator receives “analyze these 50 competitor websites” → dispatches to 5 researcher agents (10 sites each) → merges their findings into a final report.

When to use: When subtasks are genuinely independent and the bottleneck is throughput rather than sequential dependencies.

Hierarchical (supervisor/worker). A supervisor agent manages the overall task and has authority to direct worker agents. Workers report back and receive further instructions. The supervisor maintains the high-level context while workers handle implementation detail.

Example: project-manager agent breaks down a feature request → directs code-agent to implement → directs test-agent to write tests → directs review-agent to check the work → produces a summary for human review.

When to use: Complex tasks that require judgment at each step, where the next step depends on the result of the previous one.

A2A Messaging

A common way for agents to coordinate is A2A (agent-to-agent) messaging: a structured channel for agents to pass context, results, and instructions to each other, separate from the human-facing communication channels.

A2A messaging is preferable to having agents share a database or file system because:

• Messages can be logged, so every handoff is reviewable later
• Messages can be typed and validated before they are delivered
• Failed deliveries can be retried or surfaced instead of silently lost
• The communication graph between agents is visible

A typical A2A message in a fan-out pattern:

{
  "from": "research-orchestrator",
  "to": "researcher-03",
  "task": "analyze_website",
  "payload": {
    "url": "https://competitor-c.com",
    "focus_areas": ["pricing", "features", "positioning"]
  },
  "callback_session": "orchestrator-session-id"
}

The orchestrator knows when all workers have completed because whatever carries the messages tracks delivery and response.

The Isolation Problem

Multi-agent systems fail when isolation is inadequate. The most common failures:

Shared credentials. If all agents in a project use the same API keys, you can’t audit which agent took which action, can’t revoke one agent without breaking all of them, and can’t have per-agent policies. Every agent needs its own identity.

Cross-project contamination. Agent A from billing-project shouldn’t be able to read data from hr-project, even if they’re running on the same infrastructure. Enforce project-level isolation: agents should only be able to communicate with agents in the same project unless explicitly configured otherwise.

Shared state via the filesystem. Agents that write to shared directories without coordination produce race conditions that are extremely hard to debug. Use structured A2A messaging or explicit coordination patterns instead of relying on filesystem state.

Cascading failures. In a pipeline, a bug in Agent B will cause every downstream agent to fail or produce garbage. Design pipelines with explicit validation at each handoff. If Agent B produces output that Agent C can’t use, Agent C should fail loudly rather than silently propagate bad data.

Per-Agent Policies in Multi-Agent Contexts

In a multi-agent setup, each agent should have its own policy scoped to its specific role:

project: invoice-processing-pipeline

agents:
  data-extractor:
    allow:
      - service: aws
        actions: ["s3:GetObject"]
        resources: ["arn:aws:s3:::invoice-raw/*"]
      - service: internal
        actions: ["database:read"]
        resources: ["invoices.pending"]
    # No write access, no git access, no external calls

  normalizer:
    allow:
      - service: aws
        actions: ["s3:GetObject", "s3:PutObject"]
        resources: ["arn:aws:s3:::invoice-raw/*", "arn:aws:s3:::invoice-normalized/*"]
    # Can read raw, write normalized — nothing else

  reporter:
    allow:
      - service: aws
        actions: ["s3:GetObject"]
        resources: ["arn:aws:s3:::invoice-normalized/*"]
      - service: email
        actions: ["send"]
        resources: ["finance@acme.com"]
    require_approval:
      - service: email
        actions: ["send"]

Each agent can only do its part of the pipeline. If normalizer is compromised or goes wrong, it can corrupt normalized data — but it cannot touch raw data, cannot send emails, cannot push code. The blast radius of any single agent is bounded.

Monitoring a Fleet

Multi-agent systems require a different monitoring posture than single agents. You’re not watching one session — you’re watching a graph of sessions with dependencies.

Useful things to track at the fleet level:

• Overall pipeline progress (how far through the work are we?)
• Per-agent session status (running, completed, errored, stuck)
• Inter-agent message queue depth (are messages piling up at a bottleneck?)
• Aggregate token consumption across the fleet
• Failed agent handoffs (Agent B produced output Agent C rejected)

Whatever tooling you use, aim for a live view across all agents in a project. When a pipeline stalls, you want to see exactly which agent is stuck, what it was trying to do, and where it got blocked.

Start Smaller Than You Think

The biggest mistake in multi-agent systems is architectural over-ambition. Teams design a 15-agent pipeline before they’ve run a single agent in production.

Start with two agents and a clear handoff. Get that working in production. Understand the failure modes. Then add a third agent. The architecture of a mature multi-agent system emerges from operational experience, not from upfront design.

A two-agent system you understand is worth more than a ten-agent system you don’t.

If you’d rather not run this yourself

Sentrely is a managed AI team, backed by real engineers, that builds, ships and monitors production-grade software in accounts you own. Our AI employees work through an agent in your team’s Slack, every change runs through automated safety checks, and important changes get human sign-off. Book a free 30-minute call to see how it works.