Skip to main content

Building Multi-Agent Systems

Master the art of orchestrating multiple Claude agents for complex workflows, from sub-agents to meta-agents

Introduction to Multi-Agent Systems

Imagine starting your day, opening the terminal, firing up Claude Code, then kicking off a single prompt /cook that does the work it used to take you hours in minutes. This isn't science fiction—it's the reality of multi-agent systems.

As we scale from one Claude instance to many, we unlock exponential productivity gains. But with great power comes great complexity. In this module, we'll master the art of building, orchestrating, and observing multi-agent systems that work together seamlessly.

💡

Key Insight: Code is a commodity. Your fine-tuned prompts and agent architectures are where the real value lies. Master multi-agent systems, and you master the future of software development.

Why Multi-Agent Systems Matter

Single agents are powerful, but they have limitations:

  • Context limits: One agent can only hold so much in memory
  • Task specialization: General-purpose agents aren't optimal for specific tasks
  • Parallel execution: One agent = one task at a time
  • Fault isolation: If one agent fails, everything stops

Multi-agent systems solve these problems through:

  • Distributed context: Each agent maintains its own focused context
  • Specialization: Agents optimized for specific domains
  • Parallelization: Multiple agents working simultaneously
  • Resilience: Failures isolated to individual agents

Understanding Sub-Agent Architecture

Sub-agents are not just parallel Claude instances—they're a fundamentally different architecture where agents communicate through a primary orchestrator.

The Communication Flow

Sub-Agent Architecture

⚠️

Critical Understanding: Sub-agents respond to your PRIMARY agent, not to you. This changes everything about how you design their prompts and communication protocols.

Sub-Agent Configuration Structure

Sub-Agent YAML Configuration

The Two Big Mistakes to Avoid

Mistake #1: Misunderstanding the System Prompt

Wrong vs Right Sub-Agent Design

Mistake #2: Assuming Context

Sub-agents start with a completely fresh context. They know nothing about your conversation, your project, or even what you're trying to accomplish.

Context-Aware Sub-Agent Design

Creating Effective Sub-Agents

Each sub-agent should have a single, well-defined purpose:

Specialized Agent Examples

Step 2: Design Communication Protocols

Effective Communication Patterns

Step 3: Implement Tool Restrictions

Minimal Tool Assignment

Building Meta-Agents

Meta-agents are agents that create other agents—automation creating automation.

The Meta-Agent Pattern

Meta-Agent Configuration

Meta-Agent in Action

Using Meta-Agent to Build Agents

Multi-Agent Orchestration Patterns

Sequential Agent Pipeline

Pattern 2: Parallel Specialization

Parallel Agent Execution

Pattern 3: Hierarchical Delegation

Hierarchical Agent Structure

Pattern 4: Event-Driven Agents

Event-Triggered Agent Activation

Observability at Scale

As you scale to 10+ agents, observability becomes critical.

Building a Real-Time Observatory

Multi-Agent Observability Architecture

Key Observability Metrics

Agent Performance Tracking

💡

Scaling Tip: Use AI summarization (Claude Haiku) for event descriptions. Thousands of summaries cost < $0.20 and provide instant context.

Build a Complete Multi-Agent System

Let's build a production-ready multi-agent system for automated code review and deployment.

Project Requirements

Build a system that:

  1. Monitors your repository for changes
  2. Automatically reviews code with specialized agents
  3. Generates tests for new features
  4. Updates documentation
  5. Deploys to staging after all checks pass

Step 1: Create the Agent Ecosystem

Project Agent Structure

Step 2: Implement the Orchestrator

Main Orchestration Script

Step 3: Add Comprehensive Observability

Observability Integration

Step 4: Implement Conflict Resolution

Conflict Detection and Resolution

Step 5: Deploy and Monitor

Deployment Configuration

Knowledge Check

1. What is the fundamental difference between parallel Claude sessions and sub-agents?

  • A)Sub-agents are faster
  • B)Sub-agents communicate with the primary agent, not with you
  • C)Sub-agents have more memory
  • D)Sub-agents can use different models
Show Answer

Correct Answer: B

Sub-agents communicate with your primary agent, creating a delegation pattern. They never communicate directly with you, which fundamentally changes how you design their prompts and workflows.

2. When designing a sub-agent prompt, what must you always remember?

  • A)Make it as long as possible
  • B)Include your API keys
  • C)It has no conversation context
  • D)Use special formatting
Show Answer

Correct Answer: C

Sub-agents start with zero context. They only know what the primary agent explicitly provides, so prompts must be completely self-contained.

3. What is a meta-agent?

  • A)An agent that monitors other agents
  • B)An agent that creates other agents
  • C)An agent with metadata
  • D)An agent that runs faster
Show Answer

Correct Answer: B

A meta-agent is designed to create other agents. It analyzes requirements and generates complete agent configurations, automating the automation process itself.

4. Which orchestration pattern is best for dependent tasks?

  • A)Parallel execution
  • B)Event-driven activation
  • C)Sequential pipeline
  • D)Random assignment
Show Answer

Correct Answer: C

Sequential pipelines ensure dependent tasks execute in order, with each agent's output feeding into the next agent's input.

5. What's the most cost-effective way to add context to observability events?

  • A)Store full conversation logs
  • B)Use Claude Opus for summaries
  • C)Use Claude Haiku for quick summaries
  • D)Skip summaries entirely
Show Answer

Correct Answer: C

Claude Haiku provides ultra-fast, cheap summarization. Thousands of event summaries cost less than $0.20 while providing valuable context.