Agent Orchestration Patterns

Aixgo provides 12 production-proven orchestration patterns for building AI agent systems. Each pattern solves specific problems and is backed by real-world usage from industry-leading frameworks.

Pattern Overview

orchestration:
  pattern: supervisor
  agents: [billing, tech-support, sales]

orchestration:
  pattern: sequential
  agents: [extract, transform, validate, load]

orchestration:
  pattern: parallel
  agents: [competitive-analysis, market-sizing, tech-trends]

orchestration:
  pattern: router
  classifier: intent-classifier
  routes:
    simple: gpt-3.5-turbo
    complex: gpt-4-turbo

orchestration:
  pattern: swarm
  agents: [general, billing, technical]

orchestration:
  pattern: rag
  retriever: vector-store
  generator: answer-agent
  top_k: 5

orchestration:
  pattern: reflection
  generator: code-generator
  critic: code-reviewer
  max_iterations: 3

orchestration:
  pattern: hierarchical
  manager: project-manager
  teams:
    frontend: [ui-engineer, ux-engineer]
    backend: [api-engineer, db-engineer]

orchestration:
  pattern: ensemble
  models: [gpt-4, claude-3.5, gemini-1.5]
  voting: majority

Pattern Comparison

Cost Legend

• 1× = Single agent execution
• N× = N agents (sequential or parallel)
• 0.25-0.5× = Router savings (cheap models for most queries)
• 0.3× = RAG token reduction vs full KB
• 2-4×, 3-5×, 9× = Multiple iterations/agents

Latency Legend

• Low: < 1s overhead
• Medium: 1-5s overhead
• High: 5-15s overhead
• Very High: > 15s overhead

Pattern Selection Guide

Choose by Goal

💰 Reduce Costs → Router (25-50% savings) or RAG (70% token reduction)

⚡ Improve Speed → Parallel (3-4× speedup)

🎯 Improve Accuracy → Ensemble (25-50% error reduction) or Reflection (20-50% improvement)

🔄 Adaptive Routing → Swarm (dynamic handoffs) or Supervisor (centralized control)

📊 Complex Workflows → Hierarchical (multi-level) or Sequential (ordered steps)

📚 Knowledge-Intensive → RAG (retrieval-augmented)

Decision Tree

Need to reduce costs? → Router or RAG
Need high accuracy? → Ensemble or Reflection
Have independent sub-tasks? → Parallel
Need ordered steps? → Sequential
Need dynamic routing? → Swarm
Need multi-level management? → Hierarchical
Need knowledge base access? → RAG
General orchestration? → Supervisor (default)

Real-World Examples

Cost Optimization with Router

// Before: Always using GPT-4
// Cost: $0.03 per request
// After: Router to GPT-3.5 for 80% of queries
// Cost: $0.006 per request (80% savings)

router := orchestration.NewRouter(
    "cost-optimizer",
    runtime,
    "complexity-classifier",
    map[string]string{
        "simple":  "gpt-3.5-turbo-agent",
        "complex": "gpt-4-turbo-agent",
    },
)

Result: 25-50% cost reduction in production deployments.

Speed Improvement with Parallel

// Before: Sequential execution
// Time: 10s (sum of all agents)
// After: Parallel execution
// Time: 3s (max of all agents)

parallel := orchestration.NewParallel(
    "market-research",
    runtime,
    []string{"competitors", "market-size", "trends", "regulations"},
)

Result: 3-4× speedup for independent research tasks.

Accuracy Improvement with Ensemble

// Before: Single model (GPT-4)
// Error rate: 15%
// After: 3-model ensemble
// Error rate: 6% (60% reduction)

ensemble := orchestration.NewEnsemble(
    "medical-diagnosis",
    runtime,
    []string{"gpt4-diagnostic", "claude-diagnostic", "gemini-diagnostic"},
    orchestration.WithVotingStrategy(orchestration.VotingMajority),
)

Result: 25-50% error reduction for high-stakes decisions.

Implementation Roadmap

v2.0 (Q1-Q2 2025)

Phase 1 (Weeks 1-2): Foundation

• Agent interface redesign
• LocalRuntime implementation

Phase 2 (Weeks 2-3): Observability

• Automatic cost tracking
• Langfuse integration

Phase 3 (Weeks 3-5): Core Patterns

• ✅ Parallel
• ✅ Router
• ✅ Swarm
• ✅ RAG
• ✅ Reflection

Phase 4 (Weeks 5-7): Advanced Patterns

• ✅ Hierarchical
• ✅ Ensemble

Phase 5 (Weeks 7-9): Distributed Runtime

• gRPC-based deployment
• Local → Distributed migration

Phase 6 (Weeks 9-10): Documentation

• Pattern catalog
• Migration guide
• Examples for each pattern

Phase 7 (Weeks 10-11): Testing

• Unit, integration, E2E tests
• Race condition tests
• Benchmarks

Phase 8 (Week 12): Release

• v2.0.0-alpha
• Documentation
• Examples

v2.1+ (2025 H2)

Phase 5: Future Patterns

• 🔮 Debate
• 🔮 Plan-Execute (possibly Phase 2)

Phase 6: Modularity

• 🔮 Nested/Composite

Getting Started

Installation

go get github.com/aixgo-dev/aixgo@v2.0.0-alpha

Quick Example

package main

import (
    "context"
    "github.com/aixgo-dev/aixgo/internal/runtime"
    "github.com/aixgo-dev/aixgo/internal/orchestration"
)

func main() {
    // Create runtime
    rt := runtime.NewLocalRuntime()
    rt.Register("agent1", agent1)
    rt.Register("agent2", agent2)

    // Create orchestrator
    orchestrator := orchestration.NewParallel(
        "parallel-workflow",
        rt,
        []string{"agent1", "agent2"},
    )

    // Execute
    result, _ := orchestrator.Execute(context.Background(), input)
    println(result.Payload)
}

Learn More

• Quickstart Guide
• Pattern Catalog
• Architecture Overview
• Migration Guide
• Examples

Support

• GitHub Issues: github.com/aixgo-dev/aixgo/issues
• Documentation: aixgo.dev
• Discord: Join our community (coming soon)