Supervisor & Orchestrator Patterns

The supervisor pattern places a coordinating agent at the top of the pipeline. The supervisor decomposes the task, assigns subtasks to specialized agents, monitors their progress, handles failures, and aggregates the final output. This is the most structured multi-agent pattern — it mirrors how a tech lead coordinates a development team.

The supervisor agent should use a reasoning model (o3 with high effort) because its job is strategic: decomposition, delegation, quality assessment, and conflict resolution. Worker agents can use faster, cheaper models because their tasks are well-scoped by the supervisor. This hierarchical model assignment optimizes the cost-quality tradeoff: expensive reasoning where it matters (coordination), economical execution where volume is high (implementation).

from agents import Agent, handoff, Runner

# Worker agents
implementer = Agent(
    name="implementer",
    model="codex-1",
    instructions="Implement the assigned task. Report completion \
      with a summary of changes and files modified.",
)

tester = Agent(
    name="tester",
    model="gpt-4.1",
    instructions="Write tests for the specified module. \
      Report coverage percentage and any edge cases found.",
)

# Supervisor agent
supervisor = Agent(
    name="supervisor",
    model="o3",
    instructions="""
    You coordinate a development pipeline:
    1. Analyze the task and decompose into subtasks
    2. Assign implementation tasks to the implementer
    3. Assign testing tasks to the tester
    4. Review all outputs for quality and consistency
    5. Produce a final summary with all changes
    
    If a worker fails, provide context-enriched retry.
    If quality is insufficient, request revisions.
    """,
    handoffs=[
        handoff(implementer, "Delegate implementation work"),
        handoff(tester, "Delegate testing work"),
    ],
)

1. Define the supervisor's authority Specify what the supervisor can and cannot do: can it retry workers? Can it reassign tasks? Can it abort the pipeline? Clear authority prevents ambiguous behavior.
2. Limit pipeline depth Keep the pipeline to 2-3 levels (supervisor + workers). Deeper hierarchies add latency and coordination overhead that rarely justifies the complexity.
3. Require structured output Workers should report back in a structured format (JSON or markdown template) so the supervisor can parse results programmatically rather than interpreting freeform text.