---
title: "Delegation"
description: "Let an agent hand a task to another agent, on another machine, under the same job."
canonical_url: "https://docs.oz0.ai/agents/delegation"
---
# Delegation

> Let an agent hand a task to another agent, on another machine, under the same job.

For: people running and reviewing agents.

Give an agent `oz.delegate` and a `delegation.allow` list so it can assign a task to one of those agents and wait for the answer. The child is a separate job on any node that has the agent. A lead agent on a laptop can therefore delegate to a test runner on a GPU machine.

```yaml [agents/lead.yaml]
name: lead
runtime: pydantic-ai
model:
  primary: anthropic/claude-sonnet-5-5
instructions: prompts/lead.md
tools: [oz.delegate]
delegation:
  allow: [helper, test-runner]   # agents oz.delegate may start
  max_depth: 1                   # how deep a chain of delegations may go
  max_children: 3                # delegations per job
```

The model sees `oz.delegate` as a tool with the agent, from the allowed list, the task and, optionally, `data`: an object of values the helper works on (text the lead read, records), passed beside the task rather than written into it.

The helper's model gets them after its task in a `<delegated_data>` block that says whether they may hold outside text (its `trust`), as data, never as instructions. The block names no level or compartment: the helper's model provider never sees the lead's labels, which the helper's job carries instead. Write the agents' `description` well; it is what tells the lead which helper fits.

A child starts with its parent's [labels](https://docs.oz0.ai/govern/taint-and-labels): when the lead had read untrusted input, the helper is untrusted from its start, so text from outside cannot launder itself through a sub-agent's instructions. The helper's result joins its labels back into the lead, and so does its failure: what a job says as it fails can repeat what it read, so a helper that fails hands the lead what it held, along with the failure's kind. To read something without tainting the lead, use [`oz.quarantine`](https://docs.oz0.ai/govern/taint-and-labels/quarantine#the-quarantine-child).

## The platform enforces the rules

The allowed agents are an enum in the tool's schema, and the workflow checks the allow list, `max_depth` and `max_children` again before it starts a child, because a model can ignore a schema. When a limit is reached, the model is told so and answers without delegating.

## The tree

A child's job ID is `<parent>/<agent>-<8 hex>`, so the tree is in the IDs. `job get` on the parent shows every branch and what it cost:

```text
JOB                                       AGENT   NODES              MODELS                       CALLS  INPUT  CACHED  OUTPUT  COST
job-bb270cf1-b194-4bf1-a0e3-267e061e416a  lead    node-91378eb09343  anthropic/claude-sonnet-5-5  2      465    0       45      $0.0014
└ helper-30aa1892                         helper  node-d77d102ec079  anthropic/claude-haiku-4-5   2      307    0       44      $0.0005
```

Cancelling the parent cancels its children, and a [budget](https://docs.oz0.ai/build/parts/contracts-and-limits/budgets#budgets) set on the parent covers the whole tree.

## Authority only narrows

Each child runs on its parent's authority, recorded in its [authority envelope](https://docs.oz0.ai/concepts/run-receipts/authority#the-authority-envelope): the edge appends the child's block when it sees the child start, with the same person or team the tree runs for, the scopes both the parent holds and the child's plugin reaches, and the parent's budget, depth and expiry as ceilings. A runtime may ask for less for a child and never more; a child start that asks for more is refused and the job fails with the reason. A child's [autonomy level](https://docs.oz0.ai/concepts/run-receipts/authority#the-authority-envelope) is never above its parent's.

The lead's model reads the agents it may delegate to by their description and a stable ID, `id <plugin>/<agent>`, never by the model or the provider they run on.

## Constraints that reach every child

A job started with constraints (`oz0 run ... --constraint "..."`, or `constraints` in the runtime API's StartJob) passes them to every child word for word: the runtime copies them into the child's start and shows its model the list before its task, never a summary. Each job shows their digest (`constraints_digest` in `oz0 job get --json`), and an [eval case](https://docs.oz0.ai/improve/evals/cases#constraints) can check that they reach a given depth.

## What a delegation hands over

Each delegation's step in the parent's trace says how much it handed the child and how much the parent had: the task and `data`, at about four bytes a token as the gateway estimates a request, and the input tokens, cached ones included, of the parent's last model call before it asked for the child (before in the job's history, whatever the host's clock said).

A task and data too large for the history are kept in External Storage; the edge reads each such input back once to measure it and remembers its size, and one trace reads at most a few back, so a delegation's size can show as unknown for a moment while a job with many large hand-overs runs.

The job's **Steps** tab shows both on the child's step (*about 12,400 tokens of task and data, 91% of the 13,600 tokens this job's last model call read before it*), with a note that the child may belong in the parent when the share is above 60%, and `GetJobTrace` returns them as `handed_tokens` and `context_tokens`.

They are sizes, never content. A reviewer, a best-of candidate, an [`oz.quarantine`](https://docs.oz0.ai/govern/taint-and-labels/quarantine#the-quarantine-child) child and a flow tool's flow are handed what they are handed by design, and are not measured.

A child that needs most of its parent's context to do its part is a sign the split came too early: the parent hands over what it knows, the child reads it again, and the two pay for the same context twice. Per parent and child agent, the edge reads the job summaries every hour and opens a **`delegation_context` finding** when, over the last 14 days and at least 20 delegations of the pair, the median share of the parent's context handed to the child is above 60%:

```text
lead hands helper most of its context: a median of 91% of it per delegation (upper quartile 97%) over 34 delegations in 14 days. A child that needs most of its parent's context may belong in the parent; see "When to split an agent" in the docs.
```

The finding shows on the parent agent's page and in `oz0 eval findings --kind delegation_context` (its subject is `<parent>/<child>`). It resolves itself once the median has stayed at 60% or below for 14 days, so that a pair near the line does not open and resolve by turns, and at once when the pair delegates nothing in the window (the two were merged back into one agent, say). A finding a person resolves (`oz0 eval resolve ID --reason ...`) is not raised again for 14 days.

It only reports: it changes nothing, names agents and never a person, and carries no cost or savings figure. Left out of the counts: delegations in which a data subject's job takes part (the child, its parent or the tree's root), replays, evals, comparisons, shadow runs and flows' steps. [When to split an agent](https://docs.oz0.ai/build/parts/when-to-split-an-agent#a-split-made-too-early) says what to do about it: merge the two, or move what both need into a skill.

Two more findings of the same kind read the shape of the delegations rather than their size, each from the same job summaries, every hour, over the last 14 days:

- `delegate_every_job`: a parent delegates to the same child in at least 90% of its jobs, over at least 20 of its jobs that closed in the window. A part that runs every time is not a choice the parent makes; it may belong in the parent, as a skill and the child's tools. Its subject is `<parent>/<child>`.
- `delegate_chain`: a parent hands one child's answer to the next child as its task, in at least 60% of its delegations to the second child, over at least 20 of them. A fixed order of children is a flow written by hand, and each hand-over costs the parent a model turn. Its subject is `<parent>/<first>/<second>`.

```text
lead hands researcher's answer to writer: 31 of its 33 delegations to writer in 14 days carried it (94%). A fixed order of delegates may be a flow, or one agent; see "When to split an agent" in the docs, and compare the parent with the child folded in: oz0 compare start lead --variant inline-delegate=writer --budget <dollars>.
```

A delegation carries an answer when most of that answer's text, compared as sequences of words, case and punctuation aside, is in the child's task and data; it is compared with the answers of the delegations that completed last before it was asked for. The parent's summary keeps only which child job's answer it carried, never the text.

Both resolve, are kept from opening again after a person resolves them, only report and leave out the same jobs as `delegation_context`. Each points at [When to split an agent](https://docs.oz0.ai/build/parts/when-to-split-an-agent#signs-a-split-may-not-pay) and at the [comparison that folds the child into the parent](https://docs.oz0.ai/improve/comparisons-of-a-changed-agent#fold-a-delegate-into-its-parent), which says on the parent's own cases whether the split pays.

## Delegation from Ask

The built-in [Ask](https://docs.oz0.ai/agents/conversations/handoffs-and-ask#ask-one-chat-that-finds-the-right-agent) agent delegates too, with no `delegation.allow` list: it may delegate to any agent the person who started the chat may start now.

The edge checks that twice, before Ask asks and again when the child starts, against the person's role at that moment, and refuses everything else (`ask.refused` in the audit log).

A child of an Ask turn is a child job like any other: `<ask job>/<agent>-<8 hex>`, on the agent's own nodes, charged to the person, at most three per turn and one level deep, and as private as the chat it belongs to.

The limit holds however many delegations the model asks for at once: Ask starts three and tells the model the rest were not made, and the edge counts the turn's children again and stops a turn that starts a fourth. A hand-over's turn is charged to the team the person started the Ask turn with.

<note>

Agents of one tree can also ask each other questions while they run, and share notes on a board: see [Colleagues and the board](https://docs.oz0.ai/agents/colleagues). A model that asks for several delegations in one response gets them side by side, and [best-of-N](https://docs.oz0.ai/improve/outcome-checks/selection#best-of-n) runs several candidates of a child in parallel and keeps one. Planned: agents as tools (`agent:<name>`), and a share of the parent's budget for each child.

</note>


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
