Docs/Multi-Agent/Coordination Patterns

Coordination Patterns

Four core patterns for orchestrating multi-agent collaboration: Sequential, Parallel, Hierarchical, and Mesh—each suited for different scenarios.

Pattern Overview

Pattern	Best For	Complexity	Speed
Sequential	Step-by-step workflows	Low	Slow
Parallel	Independent tasks	Medium	Fast
Hierarchical	Complex decisions	Medium	Medium
Mesh	Dynamic collaboration	High	Fast

Sequential Pattern

Agents execute one after another, each building on the previous agent's output. Simple to understand and debug, but slower than parallel execution.

┌─────────────┐
│   START     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Agent A    │  → Research market data
│  (Research) │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Agent B    │  → Analyze findings
│  (Analysis) │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Agent C    │  → Generate recommendations
│  (Writer)   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    END      │
└─────────────┘

Sequential Execution

import { executeSequential } from "@/lib/agents/patterns/sequential"

const result = await executeSequential({
  task: "Generate comprehensive market report",
  steps: [
    {
      agent: "research-agent",
      input: { topic: "vacation rental market Q4 2024" },
      outputKey: "research_data"
    },
    {
      agent: "analysis-agent", 
      input: (ctx) => ({ data: ctx.research_data }),
      outputKey: "analysis"
    },
    {
      agent: "writer-agent",
      input: (ctx) => ({ 
        research: ctx.research_data,
        analysis: ctx.analysis 
      }),
      outputKey: "final_report"
    }
  ],
  context: sharedContext
})

// Each step waits for the previous to complete
// result.final_report contains the finished output

When to Use

+ Tasks with clear dependencies
+ When order matters (research → analyze → write)
+ Debugging complex flows
+ Regulated processes requiring audit trails

Limitations

- Slowest pattern (no parallelization)
- Single point of failure per step
- Idle resources while waiting

Parallel Pattern

Multiple agents execute simultaneously on independent tasks. Results are aggregated at the end. Fastest pattern when tasks don't depend on each other.

                    ┌─────────────┐
                    │   START     │
                    └──────┬──────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │  Agent A    │  │  Agent B    │  │  Agent C    │
   │  (Pricing)  │  │  (Avail)    │  │  (Comms)    │
   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
          │                │                │
          └────────────────┼────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  AGGREGATE  │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │    END      │
                    └─────────────┘

Parallel Execution

import { executeParallel } from "@/lib/agents/patterns/parallel"

const result = await executeParallel({
  task: "Prepare booking response",
  branches: [
    {
      agent: "availability-agent",
      input: { propertyId, dates },
      outputKey: "availability"
    },
    {
      agent: "pricing-agent",
      input: { propertyId, dates, guestCount },
      outputKey: "pricing"
    },
    {
      agent: "communication-agent", 
      input: { guestProfile, propertyDetails },
      outputKey: "draft_response"
    }
  ],
  aggregation: {
    strategy: "merge",  // or "select_best", "vote"
    handler: (results) => ({
      available: results.availability.isAvailable,
      price: results.pricing.finalPrice,
      response: results.draft_response.text
    })
  },
  timeout: 30000,  // Overall timeout
  failFast: false  // Continue even if one branch fails
})

// All three agents run simultaneously
// ~3x faster than sequential for this use case

Aggregation Strategies

merge

Combine all results into one object

select_best

Pick highest-confidence result

vote

Majority consensus (for redundancy)

Hierarchical Pattern

A coordinator agent manages specialist agents, delegating subtasks and synthesizing results. Best for complex decisions requiring oversight.

                    ┌─────────────────┐
                    │   COORDINATOR   │
                    │   (Overseer)    │
                    └────────┬────────┘
                             │
            ┌────────────────┼────────────────┐
            │                │                │
            ▼                ▼                ▼
     ┌────────────┐   ┌────────────┐   ┌────────────┐
     │ Specialist │   │ Specialist │   │ Specialist │
     │     A      │   │     B      │   │     C      │
     └─────┬──────┘   └─────┬──────┘   └─────┬──────┘
           │                │                │
           │         ┌──────┴──────┐         │
           │         ▼             ▼         │
           │   ┌──────────┐ ┌──────────┐     │
           │   │ Sub-spec │ │ Sub-spec │     │
           │   │   B1     │ │   B2     │     │
           │   └────┬─────┘ └────┬─────┘     │
           │        │            │           │
           └────────┴─────┬──────┴───────────┘
                          │
                          ▼
                   ┌─────────────┐
                   │  SYNTHESIS  │
                   └─────────────┘

Hierarchical Execution

import { executeHierarchical } from "@/lib/agents/patterns/hierarchical"

const result = await executeHierarchical({
  task: "Optimize portfolio pricing across all properties",
  coordinator: {
    agent: "portfolio-coordinator",
    responsibilities: [
      "Analyze overall market conditions",
      "Identify properties needing price adjustments",
      "Delegate to specialists",
      "Synthesize recommendations",
      "Ensure consistency across portfolio"
    ]
  },
  specialists: [
    {
      agent: "market-analyst",
      scope: "Market research and competitor analysis",
      canDelegate: false
    },
    {
      agent: "pricing-optimizer",
      scope: "Individual property pricing",
      canDelegate: true,  // Can create sub-specialists
      subSpecialists: [
        { agent: "seasonal-pricer", scope: "Seasonal adjustments" },
        { agent: "event-pricer", scope: "Event-based pricing" }
      ]
    },
    {
      agent: "revenue-forecaster",
      scope: "Revenue projection and validation",
      canDelegate: false
    }
  ],
  synthesisRules: {
    requireConsensus: ["major_price_changes"],
    escalateConflicts: true,
    maxIterations: 3
  }
})

Pro tip: Use hierarchical patterns for tasks requiring judgment calls. The coordinator can resolve conflicts between specialists and ensure holistic decision-making.

Mesh Pattern

Agents communicate peer-to-peer without a central coordinator. Each agent can request help from any other. Most flexible but hardest to debug.

     ┌─────────────┐           ┌─────────────┐
     │   Agent A   │◄─────────►│   Agent B   │
     │  (Pricing)  │           │  (Comms)    │
     └──────┬──────┘           └──────┬──────┘
            │                         │
            │    ┌─────────────┐      │
            │    │   Agent D   │      │
            └───►│  (Support)  │◄─────┘
                 └──────┬──────┘
                        │
     ┌─────────────┐    │    ┌─────────────┐
     │   Agent C   │◄───┴───►│   Agent E   │
     │  (Analysis) │         │  (Research) │
     └─────────────┘         └─────────────┘
     
     All agents can communicate directly with any other agent

Mesh Execution

import { executeMesh } from "@/lib/agents/patterns/mesh"

const result = await executeMesh({
  task: "Handle complex guest situation",
  initialAgent: "support-agent",
  agents: {
    "support-agent": {
      canRequestFrom: ["pricing-agent", "availability-agent", "comms-agent"],
      maxRequests: 5
    },
    "pricing-agent": {
      canRequestFrom: ["market-agent", "support-agent"],
      maxRequests: 3
    },
    "availability-agent": {
      canRequestFrom: ["calendar-agent", "support-agent"],
      maxRequests: 3
    },
    "comms-agent": {
      canRequestFrom: ["support-agent", "translation-agent"],
      maxRequests: 3
    }
  },
  messageBus: {
    maxDepth: 5,           // Max request chain length
    timeout: 60000,        // Overall timeout
    deduplication: true,   // Prevent circular requests
    logging: "verbose"     // For debugging
  },
  terminationCondition: (state) => 
    state.resolutionConfidence > 0.9 || 
    state.iterations > 10
})

Use With Caution

Mesh patterns are powerful but can lead to runaway execution if not properly bounded. Always set max depth, timeouts, and deduplication.

Choosing the Right Pattern

Use Sequential when:

- Each step depends on the previous step's output
- You need a clear audit trail
- Debugging is more important than speed

Use Parallel when:

- Tasks are independent of each other
- Speed is critical
- Results can be easily merged

Use Hierarchical when:

- Complex decisions require oversight
- Specialists may have conflicting recommendations
- You need synthesis and judgment

Use Mesh when:

- Requirements are dynamic and unpredictable
- Agents need to collaborate ad-hoc
- Maximum flexibility is required

Best Practices

Start with Sequential

Build and test with sequential first, then optimize with parallel

Combine patterns

Use parallel within hierarchical for complex, fast workflows

Always set timeouts

Prevent runaway execution with bounded timeouts at every level

Log everything

Comprehensive logging is essential for debugging multi-agent flows

Test failure modes

What happens when an agent fails? Test and handle gracefully

Agent Registry HITL Overview

Pattern

Best For

Complexity

Speed

Sequential

Step-by-step workflows

Low

Slow

Parallel

Independent tasks

Medium

Fast

Hierarchical

Complex decisions

Medium

Mesh

Dynamic collaboration

High

Fast

┌─────────────┐ │ START │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ Agent A │ → Research market data │ (Research) │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ Agent B │ → Analyze findings │ (Analysis) │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ Agent C │ → Generate recommendations │ (Writer) │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ END │ └─────────────┘

import { executeSequential } from "@/lib/agents/patterns/sequential" const result = await executeSequential({ task: "Generate comprehensive market report", steps: [ { agent: "research-agent", input: { topic: "vacation rental market Q4 2024" }, outputKey: "research_data" }, { agent: "analysis-agent", input: (ctx) => ({ data: ctx.research_data }), outputKey: "analysis" }, { agent: "writer-agent", input: (ctx) => ({ research: ctx.research_data, analysis: ctx.analysis }), outputKey: "final_report" } ], context: sharedContext }) // Each step waits for the previous to complete // result.final_report contains the finished output

┌─────────────┐ │ START │ └──────┬──────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Agent A │ │ Agent B │ │ Agent C │ │ (Pricing) │ │ (Avail) │ │ (Comms) │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └────────────────┼────────────────┘ │ ▼ ┌─────────────┐ │ AGGREGATE │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ END │ └─────────────┘

import { executeParallel } from "@/lib/agents/patterns/parallel" const result = await executeParallel({ task: "Prepare booking response", branches: [ { agent: "availability-agent", input: { propertyId, dates }, outputKey: "availability" }, { agent: "pricing-agent", input: { propertyId, dates, guestCount }, outputKey: "pricing" }, { agent: "communication-agent", input: { guestProfile, propertyDetails }, outputKey: "draft_response" } ], aggregation: { strategy: "merge", // or "select_best", "vote" handler: (results) => ({ available: results.availability.isAvailable, price: results.pricing.finalPrice, response: results.draft_response.text }) }, timeout: 30000, // Overall timeout failFast: false // Continue even if one branch fails }) // All three agents run simultaneously // ~3x faster than sequential for this use case

┌─────────────────┐ │ COORDINATOR │ │ (Overseer) │ └────────┬────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Specialist │ │ Specialist │ │ Specialist │ │ A │ │ B │ │ C │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ │ ┌──────┴──────┐ │ │ ▼ ▼ │ │ ┌──────────┐ ┌──────────┐ │ │ │ Sub-spec │ │ Sub-spec │ │ │ │ B1 │ │ B2 │ │ │ └────┬─────┘ └────┬─────┘ │ │ │ │ │ └────────┴─────┬──────┴───────────┘ │ ▼ ┌─────────────┐ │ SYNTHESIS │ └─────────────┘

import { executeHierarchical } from "@/lib/agents/patterns/hierarchical" const result = await executeHierarchical({ task: "Optimize portfolio pricing across all properties", coordinator: { agent: "portfolio-coordinator", responsibilities: [ "Analyze overall market conditions", "Identify properties needing price adjustments", "Delegate to specialists", "Synthesize recommendations", "Ensure consistency across portfolio" ] }, specialists: [ { agent: "market-analyst", scope: "Market research and competitor analysis", canDelegate: false }, { agent: "pricing-optimizer", scope: "Individual property pricing", canDelegate: true, // Can create sub-specialists subSpecialists: [ { agent: "seasonal-pricer", scope: "Seasonal adjustments" }, { agent: "event-pricer", scope: "Event-based pricing" } ] }, { agent: "revenue-forecaster", scope: "Revenue projection and validation", canDelegate: false } ], synthesisRules: { requireConsensus: ["major_price_changes"], escalateConflicts: true, maxIterations: 3 } })

┌─────────────┐ ┌─────────────┐ │ Agent A │◄─────────►│ Agent B │ │ (Pricing) │ │ (Comms) │ └──────┬──────┘ └──────┬──────┘ │ │ │ ┌─────────────┐ │ │ │ Agent D │ │ └───►│ (Support) │◄─────┘ └──────┬──────┘ │ ┌─────────────┐ │ ┌─────────────┐ │ Agent C │◄───┴───►│ Agent E │ │ (Analysis) │ │ (Research) │ └─────────────┘ └─────────────┘ All agents can communicate directly with any other agent

import { executeMesh } from "@/lib/agents/patterns/mesh" const result = await executeMesh({ task: "Handle complex guest situation", initialAgent: "support-agent", agents: { "support-agent": { canRequestFrom: ["pricing-agent", "availability-agent", "comms-agent"], maxRequests: 5 }, "pricing-agent": { canRequestFrom: ["market-agent", "support-agent"], maxRequests: 3 }, "availability-agent": { canRequestFrom: ["calendar-agent", "support-agent"], maxRequests: 3 }, "comms-agent": { canRequestFrom: ["support-agent", "translation-agent"], maxRequests: 3 } }, messageBus: { maxDepth: 5, // Max request chain length timeout: 60000, // Overall timeout deduplication: true, // Prevent circular requests logging: "verbose" // For debugging }, terminationCondition: (state) => state.resolutionConfidence > 0.9 || state.iterations > 10 })

Choosing the Right Pattern

Use Sequential when:

- Each step depends on the previous step's output
- You need a clear audit trail
- Debugging is more important than speed

Use Parallel when:

- Tasks are independent of each other
- Speed is critical
- Results can be easily merged

Use Hierarchical when:

- Complex decisions require oversight
- Specialists may have conflicting recommendations
- You need synthesis and judgment

Use Mesh when:

- Requirements are dynamic and unpredictable
- Agents need to collaborate ad-hoc
- Maximum flexibility is required

Best Practices

Start with Sequential

Build and test with sequential first, then optimize with parallel

Combine patterns

Use parallel within hierarchical for complex, fast workflows

Always set timeouts

Prevent runaway execution with bounded timeouts at every level

Log everything

Comprehensive logging is essential for debugging multi-agent flows

Test failure modes

What happens when an agent fails? Test and handle gracefully