Delegation

Delegation#

An agent can hand off part of a request to another agent instead of (or alongside) calling tools directly. List the other agent’s name in delegates when you Managing agents it:

SELECT aidb.create_agent(
    name         => sql_specialist,
    instructions => You answer questions about the orders and customers tables precisely.,
    model        => my_gpt,
    tools        => ARRAY[run_sql_query]
);

SELECT aidb.create_agent(
    name         => help_desk,
    instructions => You help users with general questions, delegating data questions to the SQL specialist.,
    model        => my_gpt,
    delegates    => ARRAY[sql_specialist]
);

SELECT * FROM aidb.agent_converse(help_desk, How many orders came in last week?);

Presenting delegates to the model#

Each configured delegate becomes an ordinary function-call tool, named after the delegate agent, with two arguments: prompt (required — the request to hand off) and conversation_id (optional — see Continuing a delegate conversation below). The delegate’s own instructions become that tool’s description, so the delegating model sees them as “what this delegate is for” — write an agent’s instructions with that dual purpose in mind if you expect it to be delegated to.

A delegate name must not collide with one of the agent’s own tools , and it’s validated to be a currently-registered agent at create_agent /update_agent time, the same as tools is.

Continuing a delegate conversation#

Calling a delegate returns an object with answer and conversation_id . The model can pass that conversation_id back on a later delegate call in the same or a future agent_converse run to continue that specific delegate conversation — with its own prior history — instead of starting fresh each time. Omitting it (the common case) starts a new conversation with the delegate on every call.

Propagating behavior across a handoff#

  • Read-only mode propagates. If the delegating run is Read-only mode , the delegate’s own sub-call is forced read-only too — a read-only agent can’t use delegation to reach a write through another agent. A read-only delegate call always returns conversation_id: null and can’t be continued.

  • Debug mode propagates. If the top-level call passed debug => true , the delegate’s own actions are emitted as NOTICE messages too.

  • Role doesn’t propagate. A delegate runs under its own configured role (or the current user, if it has none) — not the delegating agent’s role.

  • Budgets don’t propagate. Each delegate call gets its own fresh token/iteration budget and timeout, from its own configuration — a parent’s budget doesn’t constrain how much a delegate can do.

Delegation depth#

Delegation chains are capped at 10 levels deep (a chain of agents, each delegating to the next). This exists mainly to fail fast on a cycle — one agent delegating back to itself, or two agents delegating back and forth — rather than recursing until Postgres’s stack depth check aborts the backend. Hitting the limit stops the task immediately with an error; it isn’t retried the way an ordinary tool failure might be.

Contents