Multi-agent orchestration patterns, delegation chains, AgentRegistry tracking, and depth limits.

Orchestration

Orchestration is about how multiple agents work together to accomplish complex tasks. Supyagent supports hierarchical delegation chains where agents route, plan, and execute work through a tree of specialists.

The Planner-Coder Pattern

The most common orchestration pattern is a three-agent hierarchy:

User
  └─ Assistant (router)
       ├─ Planner (analysis + orchestration)
       │    └─ Coder (implementation)
       └─ Coder (direct, for simple tasks)

How It Works

The user sends a request to the assistant.
The assistant evaluates the request:
- Simple questions: handles directly
- Code tasks: delegates to coder
- Complex projects: delegates to planner
The planner analyzes the problem, creates a plan, then delegates implementation steps to coder.
The coder implements each step, runs tests, and returns results.
Results flow back up the chain to the user.

Configuration

agents/assistant.yaml

name: assistant
description: General-purpose AI assistant that routes tasks to specialist agents
type: interactive

model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 0.7

system_prompt: |
  You are an intelligent assistant and task router.

  ## When to Delegate to Planner
  - Complex multi-step projects
  - Architectural decisions or system design
  - Tasks requiring research followed by implementation

  ## When to Delegate to Coder
  - Writing, editing, or debugging code
  - Running commands or scripts
  - File operations

delegates:
  - planner
  - coder

limits:
  max_tool_calls_per_turn: 20

agents/planner.yaml

name: planner
description: Deep introspective planner that analyzes, plans, and orchestrates complex tasks
type: interactive

model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 0.7

system_prompt: |
  You are a deep-thinking Planning Agent. Analyze problems, create structured
  plans, and delegate implementation to the coder agent.

  ## Your Process
  1. Analyze — Read existing code, understand the problem
  2. Plan — Create numbered implementation steps
  3. Delegate — Send coherent units of work to coder
  4. Synthesize — Verify results and combine into final response

delegates:
  - coder

limits:
  max_tool_calls_per_turn: 20
  max_total_tool_calls: 100

agents/coder.yaml

name: coder
description: Expert programmer that builds, edits, debugs, and tests code
type: interactive

model:
  provider: google/gemini-3-flash-preview
  temperature: 0.3

system_prompt: |
  You are an expert programmer. Search first, edit minimal, test after
  every change.

will_create_tools: true
delegates: []

limits:
  max_tool_calls_per_turn: 50

Execution Flow Example

A complex request flows through the chain:

User: "Build a REST API for managing tasks with CRUD endpoints"

assistant receives message
  → Determines this is a complex project → delegates to planner
    planner receives task + conversation summary
      → Phase 1: Reads existing project structure, checks dependencies
      → Phase 2: Creates a 5-step implementation plan
      → Phase 3: Delegates step 1 to coder ("Set up FastAPI project skeleton")
        coder receives task + context
          → Creates project files, installs dependencies
          → Returns results to planner
      → Verifies step 1, delegates step 2 ("Create Task model and database")
        coder receives task
          → Implements models, migrations
          → Returns results
      → Continues through all steps...
      → Phase 4: Synthesizes all results into a summary
    → Returns plan + results to assistant
  → Presents final result to user

Delegation Chains

Delegation can form chains of arbitrary depth (up to the configured maximum). Each agent in the chain can delegate further if it has delegates configured.

Chain Depth

assistant (depth 0)
  └─ planner (depth 1)
       └─ coder (depth 2)

The depth is tracked both in-process (via the AgentRegistry) and across processes (via the SUPYAGENT_DELEGATION_DEPTH environment variable).

Maximum Depth

The maximum delegation depth is 5 (defined by AgentRegistry.MAX_DEPTH). When an agent at depth 5 tries to delegate, it receives an error:

{
  "ok": false,
  "error": "Maximum delegation depth (5) reached. Cannot delegate further."
}

This prevents infinite delegation loops where agents keep delegating to each other.

Cross-Process Depth Tracking

In subprocess mode, depth is tracked across process boundaries:

The parent reads the current cross-process depth from SUPYAGENT_DELEGATION_DEPTH.
It adds the in-process depth from the registry.
It passes --depth {total + 1} to the child process.
The child inherits the depth and enforces the limit.

Agent Registry

The AgentRegistry tracks all active agent instances and their relationships. It persists to ~/.supyagent/registry.json.

Instance Tracking

Every agent that starts running registers itself:

# Registry entry
AgentInstance(
    name="planner",
    instance_id="a1b2c3d4",
    created_at="2025-01-15T10:30:00Z",
    parent_id="e5f6g7h8",    # The assistant that spawned it
    status="active",
    depth=1,
)

Instance Lifecycle

Status	Meaning
`active`	Agent is currently running
`completed`	Agent finished its task successfully
`failed`	Agent encountered an error

Registry Operations

The registry supports:

Registration -- register(agent, parent_id) -- Creates a new instance and returns its ID.
Lookup -- get_agent(instance_id) -- Get a live agent by instance ID (in-process only).
Hierarchy -- list_children(parent_id) -- List all agents spawned by a parent.
Depth query -- get_depth(instance_id) -- Get the delegation depth of an instance.
Cleanup -- cleanup_completed() -- Remove all completed/failed instances.
Pruning -- prune_stale(max_age_hours) -- Remove active instances older than a threshold (typically from crashed processes).

Registry Stats

registry.stats()
# {"total": 5, "active": 2, "completed": 2, "failed": 1}

Cleanup

supyagent cleanup

This prunes stale registry entries from crashed processes and removes completed/failed entries.

Task Routing Patterns

Direct Delegation

For simple routing, the parent delegates directly to the specialist:

User: "Fix the bug in auth.py line 42"
assistant → delegate_to_coder(task="Fix the bug in auth.py line 42")

Planning Then Execution

For complex tasks, route through the planner first:

User: "Refactor the database layer to use SQLAlchemy"
assistant → delegate_to_planner(task="Refactor the database layer to use SQLAlchemy")
  planner → [reads codebase, creates plan]
  planner → delegate_to_coder(task="Step 1: Install SQLAlchemy and create base model")
  planner → delegate_to_coder(task="Step 2: Convert User model to SQLAlchemy")
  planner → [synthesizes results]

Parallel Delegation

An agent can delegate multiple tasks in a single turn:

planner → delegate_to_coder(task="Write unit tests for User model")
planner → delegate_to_coder(task="Write unit tests for Auth service")

When the LLM makes multiple tool calls in one response, supyagent executes them in parallel (up to 5 concurrent workers).

Background Delegation

For tasks that don't need immediate results:

assistant → delegate_to_coder(task="Run the full test suite", background=true)
  → Returns immediately with process ID
assistant → "I've started the test suite in the background. I'll check the results when it's done."
  [later]
assistant → list_processes()
assistant → get_process_output(process_id="...")

Model Selection Across Agents

A key advantage of multi-agent orchestration is using different models for different tasks:

Agent	Recommended Model	Reasoning
Assistant (router)	`anthropic/claude-sonnet-4-5-20250929`	Needs strong reasoning for routing decisions
Planner	`anthropic/claude-sonnet-4-5-20250929`	Needs deep analysis and structured planning
Coder	`google/gemini-3-flash-preview`	Fast, cost-effective, large context for code

This lets you optimize cost and performance: use an expensive, high-quality model for decision-making and a fast, cheap model for execution.

Error Handling

When a delegation fails, the error flows back to the parent:

{
  "ok": false,
  "error": "Delegation to 'coder' failed: Agent 'coder' not found"
}

The parent agent sees this as a tool result and can decide how to proceed -- retry, try a different approach, or report the error to the user.

Common failure modes:

Error	Cause	Resolution
Agent not found	Delegate YAML doesn't exist	Create the missing agent config
Not in delegates list	Agent name not listed in `delegates`	Add the name to the config
Max depth reached	Too many nested delegations	Reduce chain depth or increase limit
Delegation timeout	Child took too long	Increase timeout or use background mode
Model auth failure	Child's model API key missing	Set the API key with `supyagent config set`

Delegation -- Setting up delegates and execution modes
Daemon Mode -- Event-driven agent processing
Examples -- Complete multi-agent setups
Models -- Provider setup for different agents

Orchestration

On this page