Supervisor Pattern

The supervisor pattern enables you to build multi-agent systems where a central supervisor agent coordinates and delegates tasks to specialized worker agents. This is ideal for complex workflows requiring task decomposition and intelligent routing.

What is a Supervisor?

A supervisor agent acts as an intelligent orchestrator that:

Routes user requests to the most appropriate specialist agent
Manages handoffs between multiple agents
Evaluates worker outputs and decides next steps
Coordinates multi-step workflows across different domains

Use architecture: "supervisor" to enable supervisor-based multi-agent coordination. The supervisor dynamically routes tasks without requiring explicit edges.

When to Use Supervisors

Best For

Multi-domain systems (e.g., research + analysis + writing)
Complex workflows requiring task delegation
Systems with specialized agent teams
Dynamic routing based on request type

Capabilities

✅ Streaming support
✅ Tool calling (for handoffs)
✅ Memory support
✅ Dynamic agent routing
✅ Agent handoffs
✅ Workflow coordination

Supervisor Configuration

Basic Structure

name: "System Name"
architecture: "supervisor"  # Enable supervisor pattern

agents:
  - name: "supervisor"
    agent_type: "supervisor"
    supervised_agents: ["agent1", "agent2", "agent3"]
    return_to_supervisor: true
    max_handoffs: 10
    prompt_config:
      system_prompt: |
        Your coordination instructions...
  
  - name: "agent1"
    agent_type: "react_agent"
    # worker agent config...
  
  - name: "agent2"
    agent_type: "llm_agent"
    # worker agent config...

entry_point: "supervisor"

Supervisor architecture must not define explicit edges. Routing is handled dynamically by the supervisor via handoff tools. Adding edges will cause a validation error.

Supervisor Parameters

array

required

List of agent names that this supervisor coordinates. These must match agent names defined in the agents list. The supervisor must have at least one supervised agent.

supervised_agents: ["research_agent", "analysis_agent", "writer_agent"]

boolean

default:"true"

Controls coordination flow:

true (default): Iterative coordination — worker returns to supervisor for evaluation and next steps
false: One-way delegation — worker responds directly to the user (routes to END)

integer

default:"10"

Maximum number of agent handoffs to prevent infinite coordination loops.

string

System prompt defining the supervisor’s coordination strategy. Should clearly describe each worker’s role and delegation instructions. This is configured via the standard prompt_config block (there is no separate supervisor_prompt field).

prompt_config:
  system_prompt: |
    You coordinate a team of specialists...

Coordination Patterns

One-Way Delegation

Set return_to_supervisor: false for simple routing:

User → Supervisor → Worker Agent → User

The supervisor analyzes the request, routes to the appropriate worker, and the worker responds directly to the user. Use when:

Tasks are simple and don’t require multi-step coordination
Each agent can complete its work independently
You want minimal overhead

Iterative Coordination

Set return_to_supervisor: true for multi-step workflows:

User → Supervisor → Worker 1 → Supervisor → Worker 2 → Supervisor → User

The supervisor evaluates each worker’s output and orchestrates the next step. Use when:

Tasks require multiple agents working in sequence
Supervisor needs to evaluate intermediate results
Complex workflows with conditional routing

Complete Example

Here’s a research team supervisor coordinating three specialized agents:

name: "Research Team Supervisor"
description: "Supervisor coordinates research, analysis, and synthesis specialists"
architecture: "supervisor"
save_messages: true
persistent_state: true

agents:
  # Supervisor Agent
  - name: "research_supervisor"
    agent_type: "supervisor"
    description: "Intelligent supervisor coordinating research team specialists"
    supervised_agents: ["research_agent", "analysis_agent", "synthesis_agent"]
    return_to_supervisor: true
    max_handoffs: 10
    
    streaming_config:
      enable_streaming: true
      show_output_to_user: true

    prompt_config:
      system_prompt: |
        You are a research team supervisor coordinating specialized agents.

        Your team consists of:
        - research_agent: Expert at web search and information gathering
        - analysis_agent: Specialist in data analysis and pattern recognition
        - synthesis_agent: Expert at summarizing findings

        For ANY user request, immediately delegate to the appropriate agent.
        Always provide clear reasoning when transferring.

  # Research Agent
  - name: "research_agent"
    agent_type: "react_agent"
    description: "Specialized in research and information gathering"
    
    tools:
      - "tavily_search"
      - "tavily_extract"
    
    tool_calling:
      enabled: true
      max_iterations: 5
    
    streaming_config:
      show_output_to_user: true
      show_reasoning: true
    
    system_prompt: |
      You are a Research Specialist in a multi-agent team.
      
      Your expertise includes:
      - Web search and information gathering
      - Fact-checking and source verification
      - Identifying reliable sources
      
      Always provide detailed, well-sourced research results.

  # Analysis Agent
  - name: "analysis_agent"
    agent_type: "react_agent"
    description: "Specialized in data analysis and pattern recognition"
    
    tools:
      - "calculator"
    
    tool_calling:
      enabled: true
      max_iterations: 3
    
    streaming_config:
      show_output_to_user: true
    
    system_prompt: |
      You are an Analysis Specialist in a multi-agent team.
      
      Your expertise includes:
      - Data analysis and statistical processing
      - Pattern recognition and trend identification
      - Insight generation from complex information
      
      Focus on extracting meaningful insights.

  # Synthesis Agent
  - name: "synthesis_agent"
    agent_type: "llm_agent"
    description: "Specialized in synthesizing information"
    
    streaming_config:
      show_output_to_user: true
    
    system_prompt: |
      You are a Synthesis Specialist in a multi-agent team.
      
      Your expertise includes:
      - Combining research and analysis into coherent narratives
      - Creating well-structured, comprehensive reports
      - Ensuring completeness and coherence
      
      Create comprehensive, well-organized final responses.

entry_point: "research_supervisor"

Best Practices

Clear role definitions: In prompt_config.system_prompt, clearly describe each worker agent’s expertise and when to use them

Mix agent types: Combine ReAct agents (for tool use) with LLM agents (for synthesis) under a supervisor for powerful multi-domain systems

Immediate delegation: Instruct the supervisor to delegate immediately without attempting to answer directly

Set appropriate max_handoffs limits to prevent infinite coordination loops

Use return_to_supervisor: true when the supervisor needs to evaluate intermediate results and orchestrate multi-step workflows. Set to false for simpler one-way delegation.

Supervisor vs Workflow Architecture

Feature	Supervisor	Workflow
Routing	Dynamic (supervisor decides)	Static (predefined edges)
Edges Required	❌ No	✅ Yes
Complexity	Lower config, smarter routing	More config, explicit control
Best For	Task delegation, dynamic routing	Sequential flows, conditional logic
Coordination	Supervisor manages handoffs	Edges define transitions

Use supervisors when you need intelligent task delegation and don’t want to define all possible paths

Use workflows when you need explicit control over agent transitions and conditional routing

Common Use Cases

Content Creation Team

Setup: Supervisor + research agent + writer agent + editor agentThe supervisor routes tasks: research gathers info, writer creates content, editor polishes.

Customer Support System

Setup: Supervisor + technical support + billing support + general supportThe supervisor classifies requests and routes to the appropriate specialist.

Data Analysis Pipeline

Setup: Supervisor + data collector + analyzer + visualizerThe supervisor coordinates: collector gathers data, analyzer processes it, visualizer creates reports.

Multi-Domain Expert System

Setup: Supervisor + multiple domain-specific ReAct agentsEach agent is an expert in a specific domain (legal, medical, technical). Supervisor routes based on domain.

Next Steps

Agent Types

Learn about different agent types to use as workers

Workflow Patterns

Compare with workflow-based multi-agent patterns

YAML Configuration

Complete YAML reference for all parameters

Tool Configuration

Configure tools for ReAct worker agents

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Artaios Agents Studio

Platform

Integration

What is a Supervisor?

When to Use Supervisors

Best For

Capabilities

Supervisor Configuration

Basic Structure

Supervisor Parameters

Coordination Patterns

One-Way Delegation

Iterative Coordination

Complete Example

Best Practices

Supervisor vs Workflow Architecture

Common Use Cases

Next Steps

Agent Types

Workflow Patterns

YAML Configuration

Tool Configuration

​What is a Supervisor?

​When to Use Supervisors

Best For

Capabilities

​Supervisor Configuration

​Basic Structure

​Supervisor Parameters

​Coordination Patterns

​One-Way Delegation

​Iterative Coordination

​Complete Example

​Best Practices

​Supervisor vs Workflow Architecture

​Common Use Cases

​Next Steps

Agent Types

Workflow Patterns

YAML Configuration

Tool Configuration

What is a Supervisor?

When to Use Supervisors

Supervisor Configuration

Basic Structure

Supervisor Parameters

Coordination Patterns

One-Way Delegation

Iterative Coordination

Complete Example

Best Practices

Supervisor vs Workflow Architecture

Common Use Cases

Next Steps