Subagents

Give a parent agent a specialist it can call:

import { Schema } from "effect";
import { Agent, Subagent } from "effect-agent";
import { Toolkit } from "effect/unstable/ai";

export const Summarize = Subagent.make("summarize", {
  description: "Summarize a support case in three sentences.",
  target: Agent.make("summarizer", {
    input: Schema.String,
    output: Schema.String,
    instructions: "Summarize the case. Include the issue and next action.",
    toolkit: Toolkit.empty,
  }),
});

export const Support = Agent.make("support", {
  input: Schema.String,
  output: Schema.String,
  instructions: "Use summarize to prepare a concise case summary, then answer the user.",
  toolkit: Toolkit.make(Summarize.tool),
});

The parent calls summarize like any other tool. The child gets that call's input, runs with its own instructions and conversation, and returns { output, budgetExhausted }. Its intermediate history stays out of the parent's context. Each agent can use its own model and toolkit.

This defines the agents. Choose how to run them below.

Choose an execution kind

Kind	Parent behavior	Use it when
Ephemeral attached	Waits for a tool result; child shares its Scope	Restarting the task after a process crash is acceptable
Durable attached	Suspends, then resumes with the child's result	The parent needs the answer and progress must survive restarts
Durable background	Continues; receives declared updates and a completion report	The user should keep chatting while work runs

Both attached forms use Summarize.tool. Durable execution comes from the host you run them on. For background work, expose start and follow-up tools instead:

const background = Subagent.background(Summarize.target, {
  start: true,
  followUp: true,
  reportToParent: true,
});

Give the parent background.toolkit and provide background.layer for its handlers. The background guide shows how findings become new input to the parent.

Lifecycle and limits

Attached children can run concurrently, but the parent's next model call waits for the batch to settle. A durable parent releases its execution slot while waiting and recovers the same child after a restart. Aborting the parent propagates cancellation to attached children.

Background workers keep running after the parent finishes or aborts. Follow-ups continue the same child thread. Durable hosts recover their accepted work and pending report delivery.

All three forms enforce permissions and budgets. Parent tools are not inherited. See the subagent reference for projections, nested delegation, and limits, or durability for recovery of uncertain external actions.

Looking for a section from the previous guide?

Child definitions, delegation tools, and model bindings now live in the ephemeral attached walkthrough.

Durable registration and recovery now live in the durable attached guide.

Starting workers, follow-ups, and replies now live in the background guide.

Advanced policies now live in the subagent reference.

Peer routes now live in Agent messaging.