How to Build Multi Agent Workflows (Full Guide)

I used Single Agents to do everything for 12 months.

Then I switched to Multi Agent Workflows for 2 days.

Here is what I found

Overview

Multi-agent systems in 2026 have a single defining question: how do you coordinate agents that cannot share context without poisoning each other? The answer determines whether your system scales or collapses.

This course builds your mental model from primitives up, then connects every concept directly to what Claude Code’s Dynamic Workflows gives you today.

By the end you will know: when to use each orchestration topology, how to design inter-agent communication that does not corrupt, which failure modes kill production systems, and how to wire all of this using Claude’s native orchestration stack.

Module 1 : What a Multi-Agent System Actually Is

The Unit and the Runtime

An agent is the unit: one LLM instance with its own system prompt, tool set, memory window, and sometimes its own model. A multi-agent system is the runtime: the machinery that coordinates two or more agents, routes tasks between them, handles handoffs, and enforces a governance layer.

The distinction matters because most failures in multi-agent systems are runtime failures, not agent failures. Individual agents often reason correctly. The system fails at coordination, context propagation, and permission boundaries.

Why Single Agents Break

A single agent handling a large task runs into three hard limits:

• Context saturation: Every intermediate result consumes the context window. At scale, the agent is reasoning over a pile of its own history rather than the actual problem.

• Sequential bottleneck: The agent executes one step at a time. A 200-file migration that could parallelize runs serially for hours.

• Fragile recovery: If the agent crashes or drifts mid-task, the entire job restarts. There are no checkpoints.

Multi-agent systems solve all three by distributing work across isolated agents, storing intermediate state outside any agent’s context, and adding phase-level recovery points.

Module 2 : Claude’s Three Orchestration Primitives

Before picking a topology, understand the three coordination primitives Claude Code gives you. Picking the wrong one for the job is the most common architectural mistake.

PrimitiveWhat It IsWhere State LivesRepeatableMax ScaleSubagentsIsolated Claude instances spawned by the main session, report only to the orchestratorMain session’s contextNoA few per turnAgent TeamsMultiple Claude Code sessions coordinated by a team lead, can message each other directly via mailboxEach session’s own contextNoParallel sessionsDynamic WorkflowsJavaScript orchestration script Claude writes; a separate runtime executes it across up to 1,000 agentsScript variables, outside all contextsYes (save as slash command)1,000 agents / 16 concurrent

The decision rule:

• Use subagents when you need one or two isolated investigations that report back to a single session.

• Use agent teams when teammates need to communicate directly with each other and with you, without going through a central orchestrator.

• Use dynamic workflows when the orchestration itself should be repeatable, the plan must survive context limits, or the job takes hours to days.

Module 3 :The Six Orchestration Topologies

Every multi-agent system you build uses one of six topologies or a combination of them. Match the topology to the problem, not to the framework.

1. Sequential Pipeline

Agents arranged in a chain. Agent A produces output, passes it to Agent B, which passes to Agent C.

markdowntext[Agent A: Parse] -> [Agent B: Analyze] -> [Agent C: Format]

Use when: Work is strictly dependent. Each step must complete before the next begins. Easy to debug because data has one path.

Claude implementation: Prompt chain inside a single dynamic workflow script. Each phase runs one subagent, waits for completion, passes the result as input to the next phase.

Failure mode: Latency compounds. If Agent B is slow, the entire pipeline waits. Do not use for work with independent parallel paths.

2. Coordinator-Worker (Hub and Spoke)

One coordinator agent receives the top-level task, decomposes it into subtasks, and routes each to a specialist worker. Workers return results to the coordinator, which synthesizes.

markdowntext[Coordinator] / |
[Security] [Perf] [Auth] [Coverage] \ | / [Coordinator: Synthesize]

Use when: Work decomposes into distinct specialist domains. The routing logic is stable and knowable at plan time.

Claude implementation: This is the default shape of a Claude dynamic workflow. The workflow script is the coordinator; subagents are the workers. Claude writes the decomposition logic into the script, not into a conversation.

Failure mode: Single point of failure at the coordinator. If the coordinator’s context fills up or drifts, the entire system degrades. Fix by keeping the coordinator’s job narrow: decompose and route only, no domain reasoning.

3. Parallel Fan-Out with Merge

Multiple agents work simultaneously on independent subtasks. A merge step collects and reconciles their outputs.

markdowntext[Orchestrator] | | | | [A][B][C][D] <- simultaneous | | | | [Merge + Reconcile]

Use when: Subtasks have no dependencies between them. Classic use cases: auditing 200 files, querying multiple data sources, running five bug class investigations simultaneously.

Claude implementation: Claude’s dynamic workflows run up to 16 concurrent agents by default. Structure your workflow phases so the fan-out tasks are genuinely independent. Results land in script variables, not in the orchestrator’s context.

Performance gain: Parallel execution cuts processing time 60-80% for tasks with no step dependencies.

Failure mode: Merge logic is the hard part. If agents return inconsistent schemas or conflicting findings, a naive merge produces garbage. Design the output contract before writing the fan-out.

4. Generator-Verifier

One agent generates output. A second agent evaluates it against explicit criteria. The result feeds back to the generator. The loop runs until output passes or a max iteration count is hit.

markdowntext[Generator] -> [Verifier] -> passes? -> done ^ | |– feedback –| fails? -> iterate

Use when: Output quality is critical and evaluation criteria can be written down explicitly. Test writing, security findings, migration plans.

Claude implementation: Two-phase dynamic workflow. Phase 1 runs generator agents in parallel. Phase 2 runs independent verifier agents on each generator output. Only outputs that survive verification get merged. This is the adversarial verification built into all Claude dynamic workflows by default.

Failure mode: If the verifier’s criteria are vague, it becomes a rubber stamp. Write the verification criteria as explicit, checkable rules in the workflow prompt.

5. Shared-State

Agents coordinate through a persistent store they all read and write directly. No central orchestrator routes messages; the shared store is the coordination mechanism.

markdowntext[Agent A] —| [Agent B] —|–> [Shared Store: Markdown / JSON / DB] [Agent C] —|

Use when: Agents build on each other’s findings progressively. Context that one agent discovers is immediately useful to others working the same problem.

Claude implementation: In practice, this is the filesystem in a git worktree or a structured docs folder. My production Claude Code setup uses this: every decision, every plan, every completed item drops into a structured docs folder as a Markdown file. Agents downstream pick them up automatically.

Failure mode: Context poisoning (covered in Module 5). An agent writes a bad finding to the shared store. Every downstream agent reads it as ground truth. The error propagates across the entire system.

6. Debate (Adversarial Multi-Agent)

Two or more agents attack the same problem from opposing positions. A judge agent (or the orchestrator) reconciles the debate output.

markdowntext[Agent: Find Issues] -> claim [Agent: Refute Issues] -> counter-claim [Judge: Reconcile] -> verified finding

Use when: You want findings that survive adversarial pressure before they reach you. Security audits, migration risk assessments, any work where a false positive or false negative has real cost.

Claude implementation: Claude dynamic workflows include this pattern natively. “Agents address the problem from independent angles. Other agents then try to refute what they found. The run iterates until answers converge”. You get it without writing the debate logic explicitly; it runs as part of the workflow’s verification phase.

Module 4 : Communication Architecture

How agents pass information is where most systems break. The design decision is not which message format to use. It is whether agents communicate directly or through a substrate.

Direct vs. Substrate Communication

MethodHow It WorksRiskDirect agent-to-agentAgent A sends its output directly to Agent B’s contextAgent B inherits Agent A’s errors, biases, and hallucinationsSubstrate-mediatedAgents write to a shared store (script variables, filesystem, DB). Other agents read from itContext is controlled; bad writes are isolatable

The practical rule from production systems:

Agents should not talk to each other directly. They should write to a shared memory layer and read from it. Canonical knowledge sits in one place. Each agent operates in isolation with a defined role, defined tools, and defined outputs.

Claude’s dynamic workflows implement substrate-mediated communication by default. Intermediate results live in script variables, not in any agent’s context window. This is why the orchestration script being JavaScript matters architecturally: script variables are the substrate.

Output Contracts

Every agent in a production system needs an explicit output contract: a schema that defines exactly what it must return. Without it, the merge step and downstream agents have to guess what they received.

javascript/ Example output contract for a security audit agent { “finding_id”: “string”, “file_path”: “string”, “line_number”: “number”, “severity”: “critical | high | medium | low”, “description”: “string”, “confirmed”: “boolean”, “suggested_fix”: “string” }

Enforce this in your workflow prompt:

markdownReturn results in this exact JSON schema. If a field cannot be populated, return null for that field. Do not add fields not in the schema.

Context Window Budgeting

Every agent has a finite context window. In a multi-agent system, you are managing a fleet of context windows simultaneously. The design decisions that matter:

• Keep the orchestrator narrow. The orchestrator should decompose and route. Domain reasoning belongs to specialist agents. Narrow orchestrators do not fill their context with domain knowledge they are not using.

• Cap what agents receive. Pass only what the agent needs for its specific task. Do not pipe full file trees to agents that need three files.

• Use a hot path limit for short-term memory. In agentic loops, keep only the last 3-5 exchanges in active context. Drop older context to a shared store.

Module 5 : Failure Modes

These are the five failures that kill production multi-agent systems. Each is predictable and preventable.

1. Context Poisoning

An agent writes a bad output (hallucinated finding, wrong schema, corrupted state) to the shared store. Downstream agents read it as truth and build on it. The error compounds across the pipeline.

Signs in production: Findings that seem plausible but cannot be traced back to actual file content. Agents that confidently contradict each other on the same file.

Prevention:

• Schema validation at every write point. No agent writes raw text to the shared store; everything goes through a typed schema.

• Verifier agents check outputs before they hit the shared store, not after.

• Human review gates before results from one phase seed the next phase.

2. Cascading Failure

One agent fails. The orchestrator does not isolate the failure and routes the bad result downstream. Agents built on the failed output also fail. Multi-agent systems without proper orchestration have documented failure rates of 41-86.7%.

Prevention:

• Circuit breakers: if an agent returns an error or a null output, halt that branch, do not forward.

• Confidence scoring at pipeline checkpoints: outputs below a threshold do not pass through.

• Independent findings from multiple agents: one failure cannot corrupt the whole run if other agents independently reached the same or different conclusions.

3. Scope Creep

The orchestrator’s decomposition is too broad. Agents interpret their mandate expansively. An agent tasked with “audit the codebase” starts editing files it was not supposed to touch.

Prevention:

• Every agent gets an explicit, bounded scope in its task prompt: paths, file types, allowed actions.

• Edit policy: read-only unless explicitly granted write access for specific paths.

• Anthropic’s own design guidance: minimal footprint, request only necessary permissions, prefer reversible actions.

4. Silent Substitution

An agent cannot complete a step (API call fails, file is unreadable) and quietly inserts placeholder data behind a try/catch. It reports success. The pipeline treats the placeholder as a real result.

Prevention: In CLAUDE.md or your workflow’s agent system prompt:

markdown Error Handling

• NEVER substitute mock or placeholder data for a real result
• If a step fails, report the error and halt this agent’s execution
• A fallback is acceptable ONLY if explicitly logged as a fallback with the reason

5. Coordination Deadlock

Two agents wait on each other. Agent A cannot proceed until Agent B finishes. Agent B cannot start until Agent A writes to the shared store. The workflow stalls.

Prevention:

• Explicit dependency graphs in the workflow script. Claude’s orchestration scripts encode dependencies in code, not in implicit conversation order.

• Timeouts on every agent invocation. If an agent has not returned in X seconds, the orchestrator marks it failed and routes around it.

• Design phases to be truly independent before fanning out. Dependency mapping is Module 8’s pre-flight checklist.

Module 6 :The Governance Layer

Every multi-agent system needs three structural layers to work reliably:

LayerRoleWhat Breaks Without ItOrchestratorDecomposes tasks, routes to specialists, synthesizesNo coordination; agents duplicate or conflict workSpecialist AgentsExecute scoped operations with domain-focused prompts and toolsSingle context bottleneck; no parallelismGovernance LayerControls what each agent can access, when it can act, what it must logUnchecked tool access; missing audit trails; unvalidated outputs reaching downstream systems

The governance layer is what separates a demo from a production system.

What the Governance Layer Does

• Permission scoping: Each agent has a declared permission set. A security audit agent gets read-only access. A migration agent gets write access to specific paths only. No agent gets broader permissions than its task requires.

• Human-in-the-loop gates: Define which actions require human approval before execution. Irreversible operations (file deletions, production API calls, schema migrations) always go through a HITL gate.

• Audit trails: Every agent decision, every action, every tool call gets logged with the agent ID and the reasoning that led to it. When something breaks, you need to replay exactly what happened.

• Blast radius limits: Define the maximum scope of damage any single agent can cause if it misbehaves. Filesystem writes scoped to a worktree, not the repo root. API calls limited to staging environments without explicit production access.

Implementing Governance in Claude Dynamic Workflows

The governance layer translates into three concrete artifacts:

markdownCLAUDE.md rules (apply to all agents in the session):

t## Agent Permissions

• Read access: entire repository
• Write access: only paths listed in the task prompt
• Shell commands: only commands on the approved list
• Network: no external calls unless the task prompt specifies an endpoint

Error Handling

• Silent failures are not permitted
• Every error must be reported before halting

Irreversible Action Policy

• Database writes require explicit approval in the task prompt
• File deletions require explicit approval in the task prompt
• No production API calls without “production: true” in the task prompt

Module 7 : The Five Claude-Native Patterns in Production

These are the five patterns Anthropic documented from what works reliably in production Claude systems. Each maps directly to a dynamic workflow structure.

Pattern 1 : Prompt Chaining

• Break a complex task into a chain of simpler prompts. Output from one becomes input to the next. Each step is small enough that the agent can complete it reliably.

• When to use: The task has clear sequential stages. Document processing (extract then analyze then summarize), data transformation pipelines, code generation followed by testing followed by review.

Claude workflow shape:

markdownPhase 1: Parse and extract -> Phase 2: Analyze -> Phase 3: Generate report

Each phase is a separate agent invocation. The output of Phase 1 becomes the input to Phase 2 via script variables.

Pattern 2 : Routing

• A classifier agent reads the input and routes it to the appropriate specialist. The classifier does not process the task; it only routes.

• When to use: Tasks arrive in a heterogeneous stream. A coding task goes to the code agent, a security question goes to the security agent, a docs question goes to the docs agent.

Claude workflow shape:

markdowntext[Classifier Agent: reads task, returns agent_type] | -> dynamic dispatch to [Security | Code | Performance | Documentation]

Implement the dispatch in the workflow script’s routing logic.

Pattern 3 : Parallelization

Fan out independent subtasks to multiple agents simultaneously. Merge results at the end.

When to use: Subtasks have no dependencies on each other. Auditing multiple files, searching multiple data sources, running multiple analysis categories simultaneously.

Claude workflow shape:

javascript/ Workflow script structure const files = getFilesInScope(); const results = await Promise.all( files.map(file => runAgent({ task: ‘audit’, scope: file })) ); const merged = mergeAndDeduplicate(results);

Dynamic workflows run up to 16 concurrent agents. Token usage drops 60-90% versus sequential chaining because intermediate results stay in script variables.

Pattern 4 : Orchestrator-Subagents

• An orchestrator receives a high-level goal, breaks it into subtasks, dispatches to specialized subagents, and synthesizes their outputs.

• When to use: Work requires multiple specialist domains. A codebase audit that needs a security specialist, a performance specialist, and a coverage specialist running simultaneously.

Claude workflow shape:

markdown[Orchestrator: decompose goal into subtasks] | [Security Agent] [Perf Agent] [Coverage Agent] | | | [Orchestrator: synthesize findings]

The orchestrator’s only job is decomposition and synthesis. Domain reasoning belongs to the specialists.

Pattern 5 : Evaluator-Optimizer

• Generator agent produces output. Evaluator agent scores it against explicit criteria. Score plus feedback returns to the generator. Loop until the output passes or max iterations hit.

• When to use: Output quality is critical and evaluation criteria are writable as explicit rules. Security findings that must not be false positives. Migration plans that must survive adversarial review. Test cases that must cover specified edge cases.

Claude workflow shape:

markdownPhase 1: Generator agent produces initial output Phase 2: Evaluator agent scores against criteria schema

• Score >= threshold: forward to output
• Score < threshold: feedback -> Phase 1 with iteration count + 1 Phase 3: Max iterations reached: flag for human review

Set a hard max iteration count (3-5). Without it, the loop can run indefinitely on ambiguous evaluation criteria.

Module 8 : System Design from Scratch

A repeatable process for designing a multi-agent system before writing a single workflow prompt.

Step 1 : Task Decomposition

Write down the top-level task in one sentence. Then list every distinct operation needed to complete it. For each operation, answer two questions:

• Does this operation depend on another operation’s output? (sequential dependency)

• Can this operation run at the same time as other operations? (parallel candidate)

Group sequential-dependent operations into phases. Group parallel candidates into fan-outs within each phase.

Output: A phase diagram with explicit dependency arrows.

Step 2 : Specialist Identification

For each operation in your phase diagram, identify the specialist agent it needs. Define:

• The agent’s role (one sentence, no ambiguity)

• The agent’s tool access (read-only? write to which paths? which shell commands?)

• The agent’s output contract (exact JSON schema)

• The agent’s failure behavior (what it does when it cannot complete its task)

Avoid general-purpose agents. A “code agent” that does everything is a single agent with a bloated context, not a specialist.

Step 3 : Communication Design

Decide: substrate-mediated or direct? For most systems, the answer is substrate-mediated via the workflow’s script variables (for dynamic workflows) or a shared filesystem (for agent teams).

Map the data flow: which agent writes what, to which location, when. Draw the read/write graph. If any agent reads from a location that more than one other agent writes to, you have a potential context poisoning vector. Add a validation step before that read.

Step 4 : Governance Contracts

Write the CLAUDE.md agent rules before writing any workflow prompt. This forces you to specify permissions, error handling, and HITL gates as explicit decisions rather than afterthoughts. The artifacts from Module 6 are your template.

Step 5 : Pre-Flight Checklist

Before running any multi-agent workflow on a real repository:

• Working in a git worktree or feature branch, not main

• Each agent’s permission scope is explicitly bounded in the task prompt

• Output contracts defined for every agent that writes to the shared store

• Verifier/evaluator agents in place for every generator agent on critical paths

• HITL gates defined for all irreversible actions

• Max iteration counts set on all evaluator-optimizer loops

• Failure behavior defined for every agent (fail loud, never silent substitution)

• /usage checked before running to understand token budget

Module 9 : Building with Claude’s Orchestration Stack

The Practical Architecture: Dynamic Workflows + Agent Teams

For most production engineering tasks, the architecture combines two Claude primitives:

• Outer layer: Dynamic Workflow Claude writes the orchestration script. The script handles decomposition, fan-out, result collection, and phase sequencing. Intermediate state lives in script variables. The workflow is rerunnable: save it as a slash command and the entire orchestration becomes a team command.

• Inner layer: Specialist Subagents Each phase in the workflow dispatches specialist subagents. Each subagent has a scoped system prompt (via the task in the workflow), specific file paths, defined output schema, and a failure policy.

• For tasks requiring inter-agent communication: Agent Teams When specialists need to message each other directly (not just report back to the orchestrator), use Claude Code’s Agent Teams. Each teammate is a full Claude Code session with its own context. They communicate via mailbox. The team lead coordinates without micromanaging.

Claude Code’s Built-in Observability

The /workflows command gives you live observability into every running dynamic workflow:

• Phase-level status (running, complete, failed)

• Agent-level drill-down: task prompt, current status, output so far

• Ability to pause, restart individual agents, or stop the whole workflow

• Resume from checkpoint within the session

For agent teams, each teammate session is independently inspectable. You can interact directly with a teammate without going through the lead.

Module 10 : Scaling and Cost Control

Multi-agent systems do not have linear cost curves. Costs compound with agent count.

Token Cost Architecture

Token usage in a multi-agent system comes from three sources:

• Orchestration planning: Writing the workflow script or decomposing the task costs tokens upfront. This is fixed per job, not per agent.

• Agent execution: Each agent reads its task, reads its input files, calls tools, and produces output. Cost scales with agent count.

• Synthesis: The orchestrator reads all agent outputs and synthesizes. Cost scales with total output volume.

Dynamic workflows cut synthesis cost by keeping intermediate results in script variables rather than piping them all into the orchestrator’s context.

The 3-7 Agent Rule

Keep teams small. 3-7 agents per workflow phase. Beyond that, create hierarchical structures: one team lead per group, team leads report to a global orchestrator. Flat architectures with 20+ agents in one coordination layer have quadratic communication overhead and coordination deadlock risk.

Module 11 : Decision Guide: When to Build Multi-Agent

The most expensive mistake is building a multi-agent system for a job that one good agent (or one good function) can handle.

Build Multi-Agent When

• The task has genuinely independent parallel paths (and you can enumerate them)

• The work exceeds a single agent’s context window and cannot be summarized without loss

• You need adversarial verification (findings that survive refutation are worth more than findings from a single pass)

• The job runs for hours to days and needs checkpoint recovery

• The process is repeatable (audits, migrations, test generation) and the orchestration itself should be a reusable artifact

• Different phases require genuinely different specialist expertise or tool sets

Stay Single-Agent When

• The task is sequential with no parallelism

• The work fits comfortably in one context window

• Coordination overhead would exceed execution time

• You are still building and changing the system rapidly (multi-agent architectures are expensive to refactor)

The Single Biggest Architectural Mistake

Routing all agent results back through the orchestrator’s context. Once you do that, you have rebuilt the single-agent context bottleneck with extra network hops. Intermediate state belongs in the substrate (script variables, filesystem, structured docs), not in the orchestrator’s conversation history.

The orchestrator’s context should hold the plan and the final synthesis. Nothing else.

Disclaimer

This article was written by the author based on his notes, research, and personal experiences, and edited by an AI model (Sonnet 4.6).

The thumbnail image was taken from Pinterest and modified using AI