delegate_to_agent

delegate_to_agent is a built-in tool that lets one agent hand off a conversation to another agent. This enables multi-agent workflows where a general-purpose assistant can route specialised questions to domain-specific agents.

How it works

When the LLM calls delegate_to_agent:

The orchestrator pauses the current agent’s session.
The target agent is activated with the conversation context.
The target agent responds to the user.
Depending on configuration, control may return to the original agent afterward or stay with the target.

From the user’s perspective, the handoff is seamless — the conversation continues naturally.

Tool signature

name: delegate_to_agent
parameters:
  - name: agent
    type: string
    required: true
    description: The name of the target agent (as defined in its agent.yaml).
  - name: message
    type: string
    required: true
    description: Context message passed to the target agent explaining why the handoff is happening.
  - name: new_session
    type: boolean
    required: false
    default: false
    description: If true, start a fresh session. If false, continue the existing conversation context.
  - name: return_after
    type: boolean
    required: false
    default: true
    description: If true, control returns to the delegating agent after the target finishes.

Example usage in agent.md

A personal assistant agent might delegate to specialists:

## Delegation rules
- If the user asks about weather, delegate to `weather-agent`.
- If the user asks about calendar or scheduling, delegate to `calendar-agent`.
- For everything else, handle it yourself.

When delegating, use `delegate_to_agent` with a clear `message` explaining the user's request.

Example tool call

{
  "tool": "delegate_to_agent",
  "parameters": {
    "agent": "weather-agent",
    "message": "The user is asking about the weather forecast for Berlin this weekend.",
    "new_session": false,
    "return_after": true
  }
}

Delegation patterns

A central assistant delegates to specialists and always gets control back:

return_after: true
new_session: false

Best for: personal assistants that handle triage.

The delegating agent permanently transfers the conversation:

return_after: false
new_session: true

Best for: onboarding flows, escalation to a human-backed agent.

The target agent continues in the same session, sees the full history:

return_after: true
new_session: false

Best for: domain experts that need conversational context.

The `message` parameter

The message field is critical. It’s injected into the target agent’s context as a system-level handoff note. Write it as if you’re briefing a colleague:

Good: “The user wants to know the weather in Berlin this weekend. They prefer Celsius.”
Bad: “weather berlin”

A clear message helps the target agent respond accurately without asking the user to repeat themselves.

Limits

Limit	Value
Max delegation depth	3 (A → B → C → D, but no further)
Max delegations per session	10