Building Multi-Agent Workflows With Claude Code

You're running a workflow that feels like it should work. Maybe it's processing donor data, generating customized reports, and sending personalized follow-ups. The logic is sound. The steps are clear. But when you try to cram everything into one Claude conversation, it collapses under its own weight. The context gets muddled. The prompt gets too long. One small failure breaks the whole thing.

You know the workflow needs to happen, but single-agent execution isn't cutting it. What you need is an architecture that breaks complexity into manageable pieces without losing the thread of what you're trying to accomplish.

Multi-agent workflows solve this. You build a controller agent that knows how to delegate. It spawns specialized sub-agents to handle discrete tasks, collects their outputs, and stitches everything together. The work gets done through clean separation instead of brittle monolithic prompts.

What Multi-Agent Workflows Actually Are

A multi-agent workflow is not multiple Claude windows you're managing by hand. It's an architecture where one agent orchestrates others programmatically.

Here's the structure: You have a controller agent that understands the overall workflow. It knows what needs to happen and in what order. When it encounters a task that requires specialized work, it spawns a sub-agent with specific instructions and limited context. That sub-agent completes its job and returns output. The controller evaluates the result, decides what to do next, and either spawns another sub-agent or moves to the next phase.

The controller doesn't do the work. It plans, delegates, and synthesizes. The sub-agents don't know about the big picture. They execute narrow tasks well.

This matters because complexity breaks single-agent systems in predictable ways. When you ask one Claude instance to handle data validation, content generation, formatting, and delivery logic all at once, you get fragile execution. Any step can fail. Context bleeds between phases. The prompt becomes a maintenance nightmare.

Multi-agent architecture accounts for this. Each agent has a clear job. Failures are isolated. You can swap out how one phase works without rewriting the entire system.

The Common Approach: Duct-Taping Everything Together

Most people try to solve workflow complexity by making their prompts longer and more detailed. They write elaborate instructions covering every edge case. They add sections for error handling. They nest conditional logic inside the prompt itself.

Here's what that looks like in practice:

You are processing donor data for our annual campaign.

First, validate the CSV file:
- Check that email addresses are properly formatted
- Verify donation amounts are numeric
- Flag any missing required fields
- If more than 10% of records are invalid, stop and report errors

Then generate personalized thank-you letters:
- Use the donor's name and donation amount
- Reference their giving history if available
- Adjust tone based on donation tier (under $100, $100-$500, over $500)
- Include the correct program name from the "designation" field

Then format each letter as a PDF:
- Use our letterhead template
- Set proper margins and spacing
- Save with filename format: ThankYou_[LastName]_[Date].pdf

Finally, prepare email delivery:
- Create email subject lines
- Write brief email body text
- Attach the PDF
- Generate a send list with proper recipient addresses

If anything fails at any step, provide detailed error information and stop processing.

This prompt tries to be comprehensive. It covers the workflow. But watch what happens when you run it: Claude attempts to do everything in sequence, holding all the context simultaneously. If donor validation takes longer than expected, the letter generation context starts to drift. If PDF formatting hits an error, you lose everything downstream. When you need to adjust how thank-you letters are written, you have to edit a massive prompt and risk breaking validation logic.

The problem isn't that the prompt is wrong. The problem is that it's treating distinct workflow phases as one continuous task when they should be separate, orchestrated operations.

The Better Approach: Controller and Sub-Agent Architecture

A multi-agent workflow splits this into layers. You have one controller that manages the process and multiple sub-agents that handle execution.

Here's how to build it:

1. Design the Controller Agent

The controller's job is to understand the workflow and make decisions. It doesn't validate data or write letters. It knows what needs to happen and in what order. It spawns sub-agents and evaluates their outputs.

Your controller prompt looks like this:

You are the workflow controller for our donor thank-you automation.

Your job is to orchestrate the process, not execute individual tasks.

Workflow phases:
1. Data validation (handled by validation sub-agent)
2. Letter generation (handled by content sub-agent)
3. PDF creation (handled by formatting sub-agent)
4. Email preparation (handled by delivery sub-agent)

For each phase:
- Spawn the appropriate sub-agent with specific instructions
- Evaluate the output
- Decide whether to proceed, retry, or halt
- Pass necessary context to the next sub-agent

If any phase fails:
- Log the error with context
- Determine if the failure is recoverable
- Either retry with adjusted parameters or stop the workflow

Your output should be structured decisions, not task execution.

This prompt doesn't try to do the work. It manages the work.

2. Build Specialized Sub-Agents

Each sub-agent handles one thing. The validation sub-agent only validates. The content sub-agent only writes letters. The formatting sub-agent only creates PDFs.

Here's what a sub-agent prompt looks like:

You are a data validation agent.

Your only job: validate donor records in the provided CSV.

Validation rules:
- Email must be properly formatted
- Donation amount must be numeric and greater than zero
- Required fields: first_name, last_name, email, amount, date

Output format:
{
  "valid_count": [number],
  "invalid_count": [number],
  "error_rate": [percentage],
  "errors": [
    {"row": [number], "field": [field_name], "issue": [description]}
  ],
  "recommendation": "proceed" or "halt"
}

Do not generate letters. Do not format anything. Only validate data.

Notice the constraint. This agent can't drift into other tasks because its instructions are narrow and its output format is strict.

3. Implement the Orchestration Logic

The controller spawns sub-agents programmatically. If you're using Claude Code locally, you can write a Python script that handles this. If you're using the API, you make separate API calls for each agent.

Here's the logical flow:

1. Controller reads the donor CSV file path
2. Controller spawns validation sub-agent, passes file path
3. Validation sub-agent returns structured JSON
4. Controller evaluates: error rate under 10%?
5. If yes, controller spawns content sub-agent for each valid donor
6. Content sub-agent returns personalized letter text
7. Controller spawns formatting sub-agent, passes letter text
8. Formatting sub-agent returns PDF file path
9. Controller spawns delivery sub-agent, passes PDF and donor email
10. Delivery sub-agent returns email preparation details
11. Controller logs completion or errors

Each step is isolated. If formatting fails for one donor, the controller can retry just that step without re-validating the entire dataset or regenerating all the letters.

4. Handle Communication Between Agents

Sub-agents don't talk to each other directly. The controller passes context forward.

When the validation sub-agent finishes, the controller takes its output and decides what the content sub-agent needs to know. The content sub-agent doesn't see the validation errors. It only gets the clean donor record and instructions to write a letter.

This keeps context clean. Each sub-agent operates in a minimal information environment. The controller maintains state and makes decisions about what flows where.

5. Build Resilience Into the Architecture

Multi-agent workflows are more resilient than monolithic ones, but only if you design for failure.

Add these patterns:

• Retry logic: If a sub-agent fails, the controller should retry with adjusted parameters before halting.
• Validation gates: Before spawning the next sub-agent, the controller validates the previous output.
• Fallback paths: If PDF generation fails, the controller can fall back to plain-text output rather than stopping entirely.
• Logging: Every agent interaction gets logged with input, output, and timestamp so you can debug failures.

These aren't optional. They're what make the architecture work reliably.

Try It Today

Start small. Don't try to automate your entire donor workflow on day one.

Open Claude Code (or your preferred local environment). Create a simple two-agent system:

1. Controller agent: reads a text file and decides whether it needs summarizing
2. Summarizer sub-agent: takes long text and returns a 3-sentence summary

Write the controller prompt so it evaluates word count. If the file is under 200 words, it outputs "no summary needed." If over 200 words, it spawns the summarizer sub-agent and returns the result.

Test it with three files: one short, one medium, one long. Watch how the controller makes decisions and delegates work.

Once that works, add a third agent. Maybe a formatting sub-agent that takes the summary and converts it to Markdown with a header and bullet points. Now you have a three-agent pipeline: evaluate, summarize, format.

The pattern scales from there. Add validation. Add error handling. Add parallel processing for multiple files. Each piece builds on the same architecture: controller orchestrates, sub-agents execute.