Delegation

Delegation lets one agent hand off tasks to another. When you list agents in the delegates field, supyagent automatically injects delegation tools into the parent agent's tool set.

Setting Up Delegates

Add agent names to the delegates list in your YAML config:

name: assistant
delegates:
  - planner
  - coder

Each name must match a YAML file in the agents/ directory (agents/planner.yaml, agents/coder.yaml).

Injected Tools

For each delegate, supyagent creates two types of tools:

Named Delegation Tools

A delegate_to_{name} tool is created for each delegate:

delegate_to_planner(task, context?, mode?, background?, timeout?)
delegate_to_coder(task, context?, mode?, background?, timeout?)

The tool description includes the delegate's description field from its config, so the LLM knows what each delegate specializes in.

Generic Spawn Tool

When delegates are configured, a spawn_agent tool is also injected:

spawn_agent(agent_type, task, background?)

The spawn_agent tool is functionally equivalent to the named delegation tools but uses a generic interface. The LLM can choose either approach.

Execution Modes

Subprocess Mode (Default)

delegation:
  default_mode: subprocess

In subprocess mode, the child agent runs as a separate OS process via supyagent exec:

Parent Agent
  └─ supyagent exec coder --task "..." --context "{...}" --depth 1 --output json
       └─ Child Agent (separate process)

Advantages:

• Isolation -- Child has its own memory space, no risk of corrupting parent state
• Backgrounding -- Can run in background and be checked later
• Timeout control -- ProcessSupervisor manages timeouts and auto-backgrounding
• Safety -- If child crashes, parent continues

Disadvantages:

• Overhead -- Process startup cost (tool discovery, model initialization)
• No shared state -- Cannot access parent's in-memory objects

In-Process Mode

delegation:
  default_mode: in_process

In in-process mode, the child agent is instantiated directly in the parent's Python process:

Parent Agent
  └─ Agent("coder") or ExecutionRunner("coder")
       └─ Child runs in same process

Advantages:

• Speed -- No process startup overhead
• Shared sandbox -- Child reuses parent's sandbox container if enabled

Disadvantages:

• Coupled -- If child fails badly, it could affect the parent
• No backgrounding -- Always runs synchronously
• Memory sharing -- Uses same memory space

Per-Call Mode Selection

The LLM can override the default mode on each delegation:

{
  "task": "Write unit tests for auth.py",
  "mode": "in_process"
}

Context Sharing

When an agent delegates, the DelegationManager builds a DelegationContext that gets passed to the child.

Conversation Summary

When delegation.share_summary: true (default), the parent's conversation is summarized and passed to the child. This gives the child agent awareness of what has been discussed without sending the full chat history.

delegation:
  share_summary: true

The summary is generated only when there are more than 4 non-system messages in the parent's history. For short conversations, no summary is needed.

Credential Sharing

When delegation.share_credentials: true (default), the parent's stored credentials are listed and made available to the child:

delegation:
  share_credentials: true

This means if the parent has stored a GITHUB_TOKEN, the child can use it without re-prompting the user.

Context Structure

The full delegation context sent to the child includes:

You are being delegated a task by the assistant agent.

## Conversation Summary
[Summary of parent's conversation so far]

## Available Credentials
[List of credential names available from parent]

---

Your task:
[The actual task string]

Delegation Configuration

delegation:
  share_credentials: true     # Share stored credentials with delegates
  share_summary: true          # Pass conversation summary for context
  default_mode: subprocess     # Default execution mode
  default_timeout: 300         # Default timeout in seconds

The supervisor also has delegation-specific settings:

supervisor:
  default_delegation_mode: subprocess
  delegation_timeout: 600      # Timeout for delegated agent tasks

Background Delegation

For long-running tasks, delegate in background mode:

{
  "task": "Run the full test suite and fix any failures",
  "background": true
}

The parent receives an immediate response with a process ID. It can then check on the task using the built-in process management tools:

• list_processes -- See all running and completed background tasks
• get_process_output -- Get the result of a completed delegation
• kill_process -- Terminate a stuck delegation

DelegationManager Internals

The DelegationManager class orchestrates the delegation flow:

1. Tool generation (get_delegation_tools) -- Creates OpenAI function-calling format tool definitions for each delegate agent. Tool descriptions include the delegate's description field.

2. Tool routing (is_delegation_tool, execute_delegation) -- Detects whether a tool call is a delegation request and routes it appropriately.

3. Context building (_build_context) -- Generates a DelegationContext with conversation summary, relevant facts, and shared credentials.

4. Subprocess delegation (_delegate_subprocess) -- Constructs a supyagent exec command with task, context JSON, delegation depth, and output format. Runs it through the ProcessSupervisor.

5. In-process delegation (_delegate_in_process) -- Instantiates a child Agent or ExecutionRunner directly. For execution-type agents, uses ExecutionRunner.run(). For interactive agents, uses Agent.send_message().

6. Depth checking -- Before delegating, checks the current delegation depth against AgentRegistry.MAX_DEPTH (5). If the limit is reached, returns an error instead of creating another child.

Sandbox Sharing

When sandbox mode is enabled, the parent's sandbox container is shared with child agents:

• Subprocess mode: The parent's container name and runtime are passed via environment variables (SUPYAGENT_SANDBOX_CONTAINER, SUPYAGENT_SANDBOX_RUNTIME).
• In-process mode: The parent's SandboxManager object is passed directly to the child constructor.

This ensures all agents in the delegation chain use the same container, preserving file state and installed packages.

Related

• Orchestration -- Patterns for multi-agent workflows
• Configuration -- Delegation configuration reference
• Examples -- Real-world multi-agent setups