🤝 OpenClaw Multi-Agent Orchestrator

Coordinate teams of specialized OpenClaw agents - Route tasks, aggregate results, and manage complex multi-agent workflows.

🎯 Why Multi-Agent?

Single agents hit limits. Teams of specialized agents can:

• Parallelize - Multiple tasks simultaneously
• Specialize - Each agent has expertise
• Scale - Add agents as needed
• Resilience - Fallbacks if one fails

🚀 Quick Start

Install

npm install openclaw-multi-agent-orchestrator

Basic Example

import { Orchestrator, Agent } from 'openclaw-multi-agent-orchestrator';

// Create orchestrator
const orchestrator = new Orchestrator();

// Define specialized agents
const researcher = new Agent({
  id: 'researcher',
  role: 'research',
  capabilities: ['web_search', 'web_fetch', 'summarize'],
});

const writer = new Agent({
  id: 'writer',
  role: 'content',
  capabilities: ['generate', 'format', 'optimize'],
});

const publisher = new Agent({
  id: 'publisher',
  role: 'distribution',
  capabilities: ['post', 'schedule', 'notify'],
});

// Register agents
orchestrator.register(researcher);
orchestrator.register(writer);
orchestrator.register(publisher);

// Define workflow
const workflow = orchestrator.createWorkflow('content-pipeline', {
  steps: [
    { agent: 'researcher', task: 'research', output: 'facts' },
    { agent: 'writer', task: 'write', input: 'facts', output: 'article' },
    { agent: 'publisher', task: 'publish', input: 'article' },
  ],
});

// Execute
const result = await workflow.execute({
  topic: 'AI safety trends 2024',
  format: 'blog-post',
});

console.log(result);

📖 Core Concepts

Orchestrator

Central coordinator that manages agents and workflows:

const orchestrator = new Orchestrator({
  maxConcurrent: 5,        // Max parallel agents
  timeout: 30000,          // Task timeout (ms)
  retries: 3,              // Retry failed tasks
  fallbackStrategy: 'best-effort',
});

Agent

Specialized worker with specific capabilities:

const agent = new Agent({
  id: 'data-analyst',
  role: 'analysis',
  capabilities: ['analyze', 'visualize', 'report'],
  
  // Custom handler
  async handler(task, context) {
    // Perform task
    const result = await analyzeData(task.input);
    return result;
  },
});

Workflow

Directed graph of tasks across agents:

const workflow = orchestrator.createWorkflow('analysis-pipeline', {
  steps: [
    { 
      agent: 'fetcher', 
      task: 'fetch-data',
      parallel: true,  // Can run in parallel
    },
    { 
      agent: 'analyzer', 
      task: 'analyze',
      dependsOn: ['fetch-data'],
    },
    {
      agent: 'reporter',
      task: 'report',
      dependsOn: ['analyze'],
      condition: (context) => context.analysis.confidence > 0.8,
    },
  ],
});

🎨 Coordination Patterns

1. Pipeline (Sequential)

Each agent processes in order:

orchestrator.pipeline([
  { agent: 'A', task: 'step1' },
  { agent: 'B', task: 'step2' },
  { agent: 'C', task: 'step3' },
]);

2. Fan-Out / Fan-In (Parallel + Aggregate)

Multiple agents work in parallel, results aggregated:

orchestrator.fanOut({
  tasks: [
    { agent: 'scraper-1', task: 'scrape', input: { url: 'site1.com' } },
    { agent: 'scraper-2', task: 'scrape', input: { url: 'site2.com' } },
    { agent: 'scraper-3', task: 'scrape', input: { url: 'site3.com' } },
  ],
  aggregator: (results) => {
    return results.flatMap(r => r.data);
  },
});

3. Round-Robin (Load Balancing)

Distribute tasks evenly across agents:

orchestrator.roundRobin('worker', [
  { task: 'process', input: item1 },
  { task: 'process', input: item2 },
  { task: 'process', input: item3 },
]);

4. Auction (Best Fit)

Agents bid on tasks based on capabilities:

orchestrator.auction({
  task: 'translate',
  requirements: { language: 'japanese', domain: 'technical' },
  
  // Agents submit bids
  bidders: ['translator-1', 'translator-2', 'translator-3'],
  
  // Select winner
  selector: (bids) => bids.sort((a, b) => b.score - a.score)[0],
});

5. Hierarchical (Manager + Workers)

Manager agent delegates to workers:

const manager = new Agent({
  id: 'manager',
  role: 'coordination',
  
  async handler(task, context) {
    // Decompose task
    const subtasks = this.decompose(task);
    
    // Delegate to workers
    const results = await Promise.all(
      subtasks.map(st => orchestrator.delegate('worker', st))
    );
    
    // Synthesize results
    return this.synthesize(results);
  },
});

🔧 Advanced Features

State Management

Share state across agents:

orchestrator.setState('session', {
  userId: 'user123',
  preferences: { theme: 'dark' },
});

// Agents can access shared state
const state = orchestrator.getState('session');

Event System

React to agent lifecycle events:

orchestrator.on('task:start', ({ agent, task }) => {
  console.log(`${agent} starting ${task}`);
});

orchestrator.on('task:complete', ({ agent, task, result, duration }) => {
  console.log(`${agent} completed ${task} in ${duration}ms`);
});

orchestrator.on('task:error', ({ agent, task, error }) => {
  console.error(`${agent} failed ${task}:`, error);
});

Retry & Fallback

Automatic retries with fallback strategies:

orchestrator.createWorkflow('resilient', {
  steps: [
    {
      agent: 'primary',
      task: 'process',
      retry: {
        attempts: 3,
        backoff: 'exponential',
      },
      fallback: {
        agent: 'secondary',
        condition: (error) => error.type === 'timeout',
      },
    },
  ],
});

Task Queue

Queue tasks when agents are busy:

orchestrator.queue.add({
  agent: 'worker',
  task: 'process',
  input: data,
  priority: 5,  // Higher = sooner
});

// Process queue
await orchestrator.queue.process();

🎓 Real-World Examples

Example 1: Customer Support Team

const supportOrchestrator = new Orchestrator();

const classifier = new Agent({
  id: 'classifier',
  role: 'triage',
  handler: async (task) => {
    const category = await classifyTicket(task.ticket);
    return { category, priority: category === 'urgent' ? 10 : 5 };
  },
});

const technical = new Agent({ id: 'tech-support', role: 'technical' });
const billing = new Agent({ id: 'billing-support', role: 'billing' });
const general = new Agent({ id: 'general-support', role: 'general' });

supportOrchestrator.register(classifier);
supportOrchestrator.register(technical);
supportOrchestrator.register(billing);
supportOrchestrator.register(general);

// Route based on classification
supportOrchestrator.route({
  classifier: 'classifier',
  routes: {
    technical: 'tech-support',
    billing: 'billing-support',
    general: 'general-support',
  },
});

Example 2: Content Generation Pipeline

const contentPipeline = orchestrator.createWorkflow('content-gen', {
  steps: [
    { agent: 'researcher', task: 'research', output: 'research' },
    { agent: 'outliner', task: 'outline', input: 'research', output: 'outline' },
    {
      parallel: true,
      tasks: [
        { agent: 'writer-1', task: 'write-section-1', input: 'outline' },
        { agent: 'writer-2', task: 'write-section-2', input: 'outline' },
        { agent: 'writer-3', task: 'write-section-3', input: 'outline' },
      ],
      output: 'sections',
    },
    { agent: 'editor', task: 'merge-and-edit', input: 'sections', output: 'draft' },
    { agent: 'reviewer', task: 'review', input: 'draft', output: 'final' },
    { agent: 'publisher', task: 'publish', input: 'final' },
  ],
});

const article = await contentPipeline.execute({
  topic: 'Future of AI agents',
  targetLength: 2000,
  audience: 'technical',
});

Example 3: Research Assistant Team

const research = await orchestrator.fanOut({
  tasks: [
    { agent: 'arxiv-searcher', task: 'search-papers', input: { query: topic } },
    { agent: 'github-searcher', task: 'search-repos', input: { query: topic } },
    { agent: 'news-searcher', task: 'search-news', input: { query: topic } },
  ],
  aggregator: async (results) => {
    // Synthesize findings
    const synthesizer = orchestrator.getAgent('synthesizer');
    return await synthesizer.execute('synthesize', { sources: results });
  },
});

📦 API Reference

Orchestrator

• register(agent) - Register an agent
• createWorkflow(name, config) - Define a workflow
• execute(workflow, input) - Run a workflow
• delegate(agent, task) - Delegate task to agent
• broadcast(task) - Send task to all agents
• setState/getState - Manage shared state

Agent

• execute(task, context) - Execute a task
• canHandle(task) - Check if agent can handle task
• bid(task) - Bid on a task (auction pattern)

Workflow

• execute(input) - Run the workflow
• pause/resume - Control execution
• getState - Get current workflow state

🛠️ Development

# Build
npm run build

# Run examples
npm run example

# Tests
npm test

🤝 Contributing

Contributions welcome! Ideas:

• [ ] More coordination patterns
• [ ] Visual workflow designer integration
• [ ] Metrics and monitoring dashboard
• [ ] Agent marketplace connector
• [ ] Distributed execution (across servers)

📄 License

MIT © Alex - Built for scalable OpenClaw deployments

🔗 Links

• OpenClaw Documentation
• Multi-Agent Systems Paper
• Discord Community

One agent is good. A team is unstoppable. 🤝