org.llm4s.agent.delegation

A TypedAgent compiled onto a runtime by TypedAgent.bind: what the task tools run, and what run runs with no parent - from a graph node, or a test.

What a parent does when a child run fails (design 4.44): a provider error, a tool's Fatal, or a refusal - the child was blocked, reached its step limit, or its typed answer failed its schema.

One interrupt a suspended child waits on (design 4.46): the child's own interrupt id and its request, each as the child's own AgentStatus.Suspended gives it. Delegated is one of the child's own delegated interrupts - a grandchild's - under the child's composite id (<child interrupt>~<grandchild interrupt>).

The child run a delegated task ran as (design 4.44): its thread, the run that produced the outcome, the subagent's id, the parent's tool call that started it, and its depth - 1 for a child of a top-level thread. A child run with no parent (BoundAgent.run) has depth 0 and no toolCallId.

The answers to a DelegatedQuestion (design 4.46), keyed by the child's interrupt ids - composite ones for the child's own delegated interrupts - each encoded as the child expects it.

The question a task tool asks when its child suspends (design 4.46): the child run, and every interrupt it waits on. Its answer is a DelegatedAnswers. Application code does not answer it directly: the parent's AgentStatus.Suspended.delegated lists each pending child interrupt under a composite id, which the answer helpers (approve, reject, edit, reply, proceed) and Agent.resume take unchanged.

A suspended child's interrupt, as its parent's AgentStatus.Suspended.delegated lists it under a composite id (design 4.46): the child run that waits, and its request, never itself Delegated - a grandchild's interrupt names the grandchild here.

The bounds on an agent's delegated tasks (design 4.44), each enforced on its own:

• maxConcurrentChildren: child runs one parent run has live at once. A task call over it waits for a slot; it is not refused.
• maxTasksPerTurn: task calls one parent turn may make, counted in the order of the turn's assistant messages, across handoffs (every agent of the family's calls in the turn count), so a call is refused (a tool error) exactly when the calls before it, its own included, are over the bound, whichever order the calls run in and however often they are replayed.
• maxDepth: how deep delegation nests; 1, the default, lets the agent delegate and its children not.
• maxReportBytes: the most any task tool message may be, in UTF-8: a child's report, as the JSON the parent model reads (a larger one is a tool error), and every tool error, its reason cut to fit, so the parent's checkpoint never holds more. At least DelegationConfig.MinReportBytes, so a cut error still fits.
• childRetention: settled child threads each parent thread keeps. A run's RunConfig.childRetention bounds it too: the smaller of the two applies.

Every bound must be positive, and maxReportBytes at least MinReportBytes: AgentBuilder.build() refuses one that is not.

How a delegated task ended (design 4.44): only typed data crosses from the child to the parent, never the child's messages.

Why a child gave no report (design 4.44). Each case is rebuilt from one RunOutcome on replay.

The input of a subagent defined with TypedAgent.text: a self-contained description of the task, which becomes the child's first user message as it is. Every such subagent is offered through the one task tool (design 4.44).

A subagent's definition (design 4.44): an agent that takes a typed input I and gives back a typed report O, run on a thread of its own, with a fresh conversation, its own tools and middleware only, and nothing of its parent's (rule 15). A parent offers it with AgentBuilder.withSubagents, which compiles it with bind at the parent's build(); BoundAgent.run runs one with no parent.

Only typed data crosses (rule 17): the parent sends I, rendered as the child's first user message - by default a TaskRequest's description as it is, any other input as its canonical JSON under one line naming the subagent (withInputText replaces that) - and gets back O, decoded from the child's answer. For a TypedAgent.text subagent the answer itself is the report; otherwise the child answers in O's schema (AgentBuilder.withOutput).

A definition holds clients and functions, not data: it is immutable, and every with* returns a new one. Its id ([a-zA-Z0-9_-]{1,52}) and description (not blank) are checked when it is bound.