Orchestration Patterns

Overview

State-of-the-art patterns for multi-agent system orchestration. These patterns enable complex workflows while maintaining clear boundaries, efficient context flow, and debuggable execution.

Pattern Selection Framework

For detailed pattern definitions, see references/firewall-architecture.md.

Firewall Architecture

The foundational pattern for context-isolated multi-agent systems.

Core Concept

Main Session (CLEAN)
       │
       ▼
   ┌───────────────────┐
   │  FIREWALL         │
   │  Entry Agent      │  ← Only entry point
   │  (Thin Router)    │
   └───────────────────┘
       │
       ▼
   ┌───────────────────┐
   │  ISOLATED WORK    │
   │  Sub-Agents       │  ← Work happens here
   │  (coordinator-    │
   │   internal/)      │
   └───────────────────┘
       │
       ▼
   ┌───────────────────┐
   │  SANITIZED OUTPUT │
   │  Final Report     │  ← Only this returns
   └───────────────────┘

Key Rules

1. Entry agents are THIN ROUTERS - They route, not analyze
2. Work in isolation - Sub-agents do the actual work
3. Structured data only - No raw context passes through
4. Sanitized return - Only final report reaches main session

For implementation details, see references/firewall-architecture.md.

Phase-Based Execution

Workflow structure with clear stages:

phases:
  analyze:
    tier: FULL
    agents: [analyzer]
    output: analysis_results

  improve:
    tier: SELECTIVE
    agents: [optimizer, improver]
    input: analysis_summary
    output: improvements

  ground:
    tier: FILTERED
    agents: [checkers, validators]
    input: improvements_by_priority
    output: grounded_improvements

  synthesize:
    tier: METADATA
    agents: [synthesizer]
    input: selected_improvements
    output: final_report

For phase design guidance, see references/phase-execution.md.

Severity-Based Batching

Route items by priority to reduce operations:

routing:
  CRITICAL:
    validators: [all]          # 4 agents
    operations: ~16            # 4 findings × 4 validators

  HIGH:
    validators: [primary, secondary]  # 2 agents
    operations: ~10            # 5 findings × 2 validators

  MEDIUM:
    validators: [primary]      # 1 agent
    operations: ~8             # 8 findings × 1 validator

  LOW/INFO:
    validators: []             # Skip
    operations: 0

# Total: 34 operations vs 108 (all × all)
# Reduction: 68%

For batching strategies, see references/severity-batching.md.

Agent Hierarchy Patterns

Entry + Internal Structure

plugin/
├── agents/                    # ENTRY AGENTS (user-invocable)
│   ├── coordinator-a.md       # Firewall for workflow A
│   └── coordinator-b.md       # Firewall for workflow B
│
└── coordinator-internal/      # SUB-AGENTS (never directly invoked)
    ├── analyzer.md
    ├── processor.md
    ├── grounding/
    │   ├── checker-1.md
    │   └── checker-2.md
    └── synthesizer.md

Naming Conventions

Validation with Hooks

PostToolUse Pattern

{
  "event": "PostToolUse",
  "matcher": {
    "tool_name": "Task"
  },
  "hooks": [{
    "type": "prompt",
    "prompt": "Validate sub-agent output..."
  }]
}

Validation Flow

1. Sub-agent completes
2. Hook intercepts output
3. Validates against schema
4. Blocks if invalid → Coordinator retries
5. Passes if valid → Workflow continues

For hook configuration, see references/validation-hooks.md.

Anti-Patterns to Avoid

Quick Decision Guide

When to Add Firewall

• Complex analysis that shouldn't pollute main context
• Multiple sub-agents needed
• Intermediate work should be isolated

When to Add Phases

• 3+ distinct stages in workflow
• Different context needs per stage
• Clear sequential dependencies

When to Add Batching

• Variable priority items
• Not all items need same validation
• Want to reduce operations

Additional Resources

• references/firewall-architecture.md - Coordinator isolation patterns
• references/phase-execution.md - Phase-based workflow design
• references/severity-batching.md - CRITICAL→HIGH→MEDIUM→LOW routing
• references/validation-hooks.md - Pydantic + PostToolUse patterns