Orchestrator-Workers

The Orchestrator-Workers pattern is a design where a central orchestrator coordinates multiple specialized worker agents to accomplish complex tasks.

Basic Structure

states:
  - id: start
    type: initial
    next: orchestrator
  
  - id: orchestrator
    type: agent
    model: orchestrator
    prompt: |
      Coordinate the following task:
      {task}
      
      Available workers:
      - researcher
      - writer
      - reviewer      
    input:
      task: "${input.task}"
    next: distribute_tasks
  
  - id: distribute_tasks
    type: parallel
    branches:
      - id: research
        states:
          - id: start
            type: initial
            next: researcher
          - id: researcher
            type: agent
            model: researcher
            prompt: "Research: {task}"
            input:
              task: "${input.task}"
      - id: writing
        states:
          - id: start
            type: initial
            next: writer
          - id: writer
            type: agent
            model: writer
            prompt: "Write: {task}"
            input:
              task: "${input.task}"
      - id: review
        states:
          - id: start
            type: initial
            next: reviewer
          - id: reviewer
            type: agent
            model: reviewer
            prompt: "Review: {task}"
            input:
              task: "${input.task}"
    next: combine_results

Common Use Cases

1. Content Creation

states:
  - id: start
    type: initial
    next: content_orchestrator
  
  - id: content_orchestrator
    type: agent
    model: orchestrator
    prompt: |
      Create content for:
      {topic}
      
      Coordinate:
      - research
      - writing
      - editing
      - fact-checking      
    input:
      topic: "${input.topic}"
    next: content_creation
  
  - id: content_creation
    type: parallel
    branches:
      - id: research
        states:
          - id: start
            type: initial
            next: researcher
          - id: researcher
            type: agent
            model: researcher
            prompt: "Research topic: {topic}"
            input:
              topic: "${input.topic}"
      - id: writing
        states:
          - id: start
            type: initial
            next: writer
          - id: writer
            type: agent
            model: writer
            prompt: "Write about: {topic}"
            input:
              topic: "${input.topic}"
      - id: editing
        states:
          - id: start
            type: initial
            next: editor
          - id: editor
            type: agent
            model: editor
            prompt: "Edit content about: {topic}"
            input:
              topic: "${input.topic}"
      - id: fact_checking
        states:
          - id: start
            type: initial
            next: fact_checker
          - id: fact_checker
            type: agent
            model: fact_checker
            prompt: "Fact check: {topic}"
            input:
              topic: "${input.topic}"
    next: finalize_content

2. Code Review

states:
  - id: start
    type: initial
    next: review_orchestrator
  
  - id: review_orchestrator
    type: agent
    model: orchestrator
    prompt: |
      Review code:
      {code}
      
      Coordinate:
      - style_check
      - security_scan
      - performance_analysis
      - documentation_review      
    input:
      code: "${input.code}"
    next: code_review
  
  - id: code_review
    type: parallel
    branches:
      - id: style_check
        states:
          - id: start
            type: initial
            next: style_checker
          - id: style_checker
            type: agent
            model: style_checker
            prompt: "Check code style: {code}"
            input:
              code: "${input.code}"
      - id: security_scan
        states:
          - id: start
            type: initial
            next: security_scanner
          - id: security_scanner
            type: agent
            model: security_scanner
            prompt: "Scan for security issues: {code}"
            input:
              code: "${input.code}"
      - id: performance_analysis
        states:
          - id: start
            type: initial
            next: performance_analyzer
          - id: performance_analyzer
            type: agent
            model: performance_analyzer
            prompt: "Analyze performance: {code}"
            input:
              code: "${input.code}"
      - id: documentation_review
        states:
          - id: start
            type: initial
            next: documentation_reviewer
          - id: documentation_reviewer
            type: agent
            model: documentation_reviewer
            prompt: "Review documentation: {code}"
            input:
              code: "${input.code}"
    next: combine_reviews

3. Data Analysis

states:
  - id: start
    type: initial
    next: analysis_orchestrator
  
  - id: analysis_orchestrator
    type: agent
    model: orchestrator
    prompt: |
      Analyze data:
      {data}
      
      Coordinate:
      - data_cleaning
      - statistical_analysis
      - visualization
      - insights_generation      
    input:
      data: "${input.data}"
    next: data_analysis
  
  - id: data_analysis
    type: parallel
    branches:
      - id: data_cleaning
        states:
          - id: start
            type: initial
            next: data_cleaner
          - id: data_cleaner
            type: agent
            model: data_cleaner
            prompt: "Clean data: {data}"
            input:
              data: "${input.data}"
      - id: statistical_analysis
        states:
          - id: start
            type: initial
            next: statistician
          - id: statistician
            type: agent
            model: statistician
            prompt: "Analyze statistics: {data}"
            input:
              data: "${input.data}"
      - id: visualization
        states:
          - id: start
            type: initial
            next: visualizer
          - id: visualizer
            type: agent
            model: visualizer
            prompt: "Create visualizations: {data}"
            input:
              data: "${input.data}"
      - id: insights_generation
        states:
          - id: start
            type: initial
            next: insights_generator
          - id: insights_generator
            type: agent
            model: insights_generator
            prompt: "Generate insights: {data}"
            input:
              data: "${input.data}"
    next: combine_analysis

Advanced Patterns

1. Dynamic Worker Selection

states:
  - id: start
    type: initial
    next: select_workers
  
  - id: select_workers
    type: llm
    model: worker_selector
    prompt: |
      Select appropriate workers for:
      {task}
      
      Available workers:
      {workers}
      
      Return as JSON:
      {
        "selected_workers": ["worker1", "worker2"],
        "reason": "explanation"
      }      
    input:
      task: "${input.task}"
      workers: "${context.available_workers}"
    next: orchestrate_workers
  
  - id: orchestrate_workers
    type: parallel
    branches: "${output.selected_workers.map(worker => ({
      id: worker,
      states: [
        {
          id: 'start',
          type: 'initial',
          next: 'execute'
        },
        {
          id: 'execute',
          type: 'agent',
          model: worker,
          prompt: 'Execute task: {task}',
          input: {
            task: '${input.task}'
          }
        }
      ]
    }))}"
    next: combine_results

2. Worker Communication

states:
  - id: start
    type: initial
    next: orchestrate_with_communication
  
  - id: orchestrate_with_communication
    type: parallel
    branches:
      - id: worker1
        states:
          - id: start
            type: initial
            next: execute_task1
          - id: execute_task1
            type: agent
            model: worker1
            prompt: "Execute task 1: {task}"
            input:
              task: "${input.task}"
            next: share_results
          - id: share_results
            type: tool
            tool: share_results
            input:
              results: "${output}"
              target: "worker2"
      - id: worker2
        states:
          - id: start
            type: initial
            next: wait_for_input
          - id: wait_for_input
            type: tool
            tool: wait_for_results
            input:
              source: "worker1"
            next: execute_task2
          - id: execute_task2
            type: agent
            model: worker2
            prompt: "Execute task 2 with input: {input}"
            input:
              input: "${input}"
    next: combine_results

3. Error Recovery

states:
  - id: start
    type: initial
    next: orchestrate_with_recovery
  
  - id: orchestrate_with_recovery
    type: parallel
    branches:
      - id: worker1
        states:
          - id: start
            type: initial
            next: execute_task1
          - id: execute_task1
            type: agent
            model: worker1
            prompt: "Execute task 1: {task}"
            input:
              task: "${input.task}"
            error:
              next: handle_error1
          - id: handle_error1
            type: agent
            model: error_handler
            prompt: "Handle error: {error}"
            input:
              error: "${error}"
            next: retry_task1
          - id: retry_task1
            type: agent
            model: worker1
            prompt: "Retry task 1: {task}"
            input:
              task: "${input.task}"
      - id: worker2
        states:
          - id: start
            type: initial
            next: execute_task2
          - id: execute_task2
            type: agent
            model: worker2
            prompt: "Execute task 2: {task}"
            input:
              task: "${input.task}"
            error:
              next: handle_error2
          - id: handle_error2
            type: agent
            model: error_handler
            prompt: "Handle error: {error}"
            input:
              error: "${error}"
            next: retry_task2
          - id: retry_task2
            type: agent
            model: worker2
            prompt: "Retry task 2: {task}"
            input:
              task: "${input.task}"
    next: combine_results

Best Practices

Clear Responsibilities: Define clear roles for orchestrator and workers
Task Independence: Ensure workers can operate independently
Communication: Implement effective worker communication
Error Handling: Plan for worker failures and recovery
Resource Management: Monitor and optimize resource usage
Monitoring: Track worker performance and progress

Common Pitfalls

Orchestrator Overload: Making orchestrator too complex
Worker Dependencies: Creating tight coupling between workers
Communication Overhead: Excessive worker communication
Error Propagation: Not handling worker errors properly
Resource Contention: Workers competing for resources

Next Steps

Learn about Best Practices
Explore Error Handling
Read about Resource Management

Last updated on May 9, 2025

Parallelization Evaluator-Optimizer