A subagent gives a specialist its own instructions, model, tools, and conversation. The parent
passes a task and receives a bounded result; the child’s intermediate history stays out of the
parent’s context. Use delegation when that separation helps the task, such as researching several
travel options before a coordinator chooses an itinerary.
Expose one child Agent as an attached Effect AI Tool. The nonempty application
name is preserved as both Tool name and delegation identity; no prefix is required.
Parameters and result projections default to the child's input and result envelope.
Throws when the name is empty. Nested Tool visibility follows the effective inherited grant.
make("summarize",{
description?:string|undefined
Model-visible description of the delegated capability.
description:"Summarize a support case in three sentences.",
Validate an agent ID and return a shallowly frozen, model-agnostic definition.
make("support",{
DefinitionOptions<String,String,"Use summarize to prepare a concise case summary, then answer the user.",Toolkit<{ readonlysummarize:Tool<"summarize", { readonly parameters:String; readonlysuccess: Struct<...>; readonlyfailure: SubagentToolFailure<...>; readonlyfailureMode: "error"; },AgentSpawner|...1more...|SubagentDurability>; }>,undefined,undefined,undefined>.input: Schema.String
input:
importSchema
Schema.
constString:Schema.String
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof"string".
@stability ― stable
@category ― models
@since ― 4.0.0
@stability ― stable
@category ― schemas
@since ― 4.0.0
String,
DefinitionOptions<String,String,"Use summarize to prepare a concise case summary, then answer the user.",Toolkit<{ readonlysummarize:Tool<"summarize", { readonly parameters:String; readonlysuccess: Struct<...>; readonlyfailure: SubagentToolFailure<...>; readonlyfailureMode: "error"; },AgentSpawner|...1more...|SubagentDurability>; }>,undefined,undefined,undefined>.output: Schema.String
output:
importSchema
Schema.
constString:Schema.String
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof"string".
@stability ― stable
@category ― models
@since ― 4.0.0
@stability ― stable
@category ― schemas
@since ― 4.0.0
String,
DefinitionOptions<String,String,"Use summarize to prepare a concise case summary, then answer the user.",Toolkit<{ readonlysummarize:Tool<"summarize", { readonly parameters:String; readonlysuccess: Struct<...>; readonlyfailure: SubagentToolFailure<...>; readonlyfailureMode: "error"; },AgentSpawner|...1more...|SubagentDurability>; }>,undefined,undefined,undefined>.instructions: "Use summarize to prepare a concise case summary, then answer the user."
instructions:"Use summarize to prepare a concise case summary, then answer the user.",
DefinitionOptions<String,String,"Use summarize to prepare a concise case summary, then answer the user.",Toolkit<{ readonlysummarize:Tool<"summarize", { readonly parameters:String; readonlysuccess: Struct<...>; readonlyfailure: SubagentToolFailure<...>; readonlyfailureMode: "error"; },AgentSpawner|...1more...|SubagentDurability>; }>,undefined,undefined,undefined>.toolkit: Toolkit.Toolkit<{
This is the primary constructor for creating toolkits. It accepts multiple
tools and organizes them into a toolkit that can be provided to AI language
models.
The real Effect AI Tool to include in the parent Toolkit (SUB-001).
tool),
});
Summarize.tool is an ordinary model-facing tool on the parent. Provide its handlers with
Subagent.layer(Summarize) and supply the child’s model and services through Layers. The default
result is { output, budgetExhausted }, so the parent can recognize a partial answer.
The answer is required and progress must survive restart
Durable background
Continues while the worker runs
The user should keep chatting during longer work
Two delegation lifetimes. An attached child returns a tool result to its waiting parent. A background worker delivers a message to a continuing parent Thread.
Both attached forms use the same declaration. In-memory execution shares the parent’s Scope;
durable execution registers both Definitions with the host. A durable parent releases its
execution slot while waiting and recovers the same child after restart. Parent abort propagates
to attached children. Sibling calls may run concurrently, but the parent model receives the
complete batch before continuing.
Create a delegation with Subagent.make, then use Subagent.startTool(delegation) and
Subagent.followUpTool(delegation). Each returns a native tool and its handler layer.
Install only the management operations the parent needs. A start returns a worker identity and
retained delivery status; inspect that delivery until it has a receipt rather than starting the
task again.
Follow-ups address the same child Thread. Background workers outlive completion or abort of the
launching Run. The host must authorize starting, sending, inspecting, and controlling them;
a worker reference grants none of those permissions.
Add reporting: [Subagent.reporting(delegation)] to the parent registration so completed Runs
send framework messages to it. Declare updates on the child for structured intermediate findings.
Reporting and destination processing can fail independently of the child outcome. Reports are
untrusted model context, not instructions.
The background example
includes declarations, access policy, and host wiring.
A worker normally accepts later tasks. For a single retained assignment, opt into
runDisposition.workerLifecycle: "assignment" and use Worker.AssignmentDisposition to select
waiting or completed from typed output. Completion seals the worker only after its latest
accepted input is applied. Stopping a worker prevents future input; cancelling one receipt has
a narrower scope.
Parent tools are never inherited automatically. Grants, depth, and reserved budgets constrain
children, and approval to start one does not authorize its actions. An uncertain external tool
still needs reconciliation after a crash. See the subagent reference
for defaults, failure handling, and nested work, or messaging for communication
between independent Threads.