Skip to content

Add capabilities

Subagents

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.

subagent-basics.ts
import {
import Agent
Agent
,
import Subagent
Subagent
} from "@yielded/agent";
import {
import Schema
Schema
} from "effect";
import {
import Toolkit
Toolkit
} from "effect/ai";
export const
const Summarize: Subagent.SubagentDelegation<"summarize", Schema.String, Schema.String, string, {}, Schema.String, Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>, Schema.Never, never, never, "error"> & {
readonly target: Agent.Definition<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "summarizer";
};
}
Summarize
=
import Subagent
Subagent
.
make<"summarize", Schema.String, Schema.String, string, {}, Schema.String, Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>, Schema.Never, never, never, Agent.Definition<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "summarizer";
}>(name: "summarize", options: Omit<Subagent.SubagentDefineOptions<Schema.String, Schema.String, ... 7 more ..., "error">, "parameters" | ... 3 more ... | "projectResult"> & {
...;
} & {
...;
}): Subagent.SubagentDelegation<...> & {
...;
} (+1 overload)
export make

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.",
target: Agent.Definition<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, Agent.RunDispositionDeclaration<string, Schema.Top> | undefined, unknown, Schema.Top | undefined> & Agent.Definition<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "summarizer";
}

The model-agnostic child Agent Definition this delegation targets (SUB-002).

target
:
import Agent
Agent
.
function make<"summarizer", Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined>(id: "summarizer", options: Agent.DefinitionOptions<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly inputPrompt?: undefined;
readonly runDisposition?: undefined;
}): Agent.Definition<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "summarizer";
} (+3 overloads)

Validate an agent ID and return a shallowly frozen, model-agnostic definition.

make
("summarizer", {
DefinitionOptions<String, String, string, Toolkit<{}>, undefined, undefined, undefined>.input: Schema.String
input
:
import Schema
Schema
.
const String: 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, string, Toolkit<{}>, undefined, undefined, undefined>.output: Schema.String
output
:
import Schema
Schema
.
const String: 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, string, Toolkit<{}>, undefined, undefined, undefined>.instructions: string
instructions
: "Summarize the case. Include the issue and next action.",
DefinitionOptions<String, String, string, Toolkit<{}>, undefined, undefined, undefined>.toolkit: Toolkit.Toolkit<{}>
toolkit
:
import Toolkit
Toolkit
.
const empty: Toolkit.Toolkit<{}>

An empty toolkit with no tools.

When to use

Use when you need an empty starting point for building toolkits or a default toolkit value that can be extended with merge.

@stability ― unstable

@category ― constructors

@since ― 4.0.0

empty
,
}),
});
export const
const Support: Agent.Definition<Schema.String, Schema.String, "Use summarize to prepare a concise case summary, then answer the user.", Toolkit.Toolkit<{
readonly summarize: Tool<"summarize", {
readonly parameters: Schema.String;
readonly success: Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>;
readonly failure: Subagent.SubagentToolFailure<Schema.Never>;
readonly failureMode: "error";
}, AgentSpawner | RunEventSink | SubagentDurability>;
}>, undefined, undefined, undefined> & {
...;
}
Support
=
import Agent
Agent
.
function make<"support", Schema.String, Schema.String, "Use summarize to prepare a concise case summary, then answer the user.", Toolkit.Toolkit<{
readonly summarize: Tool<"summarize", {
readonly parameters: Schema.String;
readonly success: Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>;
readonly failure: Subagent.SubagentToolFailure<Schema.Never>;
readonly failureMode: "error";
}, AgentSpawner | RunEventSink | SubagentDurability>;
}>, undefined>(id: "support", options: Agent.DefinitionOptions<...> & {
...;
}): Agent.Definition<...> & {
...;
} (+3 overloads)

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<{ readonly summarize: Tool<"summarize", { readonly parameters: String; readonly success: Struct<...>; readonly failure: SubagentToolFailure<...>; readonly failureMode: "error"; }, AgentSpawner | ... 1 more ... | SubagentDurability>; }>, undefined, undefined, undefined>.input: Schema.String
input
:
import Schema
Schema
.
const String: 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<{ readonly summarize: Tool<"summarize", { readonly parameters: String; readonly success: Struct<...>; readonly failure: SubagentToolFailure<...>; readonly failureMode: "error"; }, AgentSpawner | ... 1 more ... | SubagentDurability>; }>, undefined, undefined, undefined>.output: Schema.String
output
:
import Schema
Schema
.
const String: 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<{ readonly summarize: Tool<"summarize", { readonly parameters: String; readonly success: Struct<...>; readonly failure: SubagentToolFailure<...>; readonly failureMode: "error"; }, AgentSpawner | ... 1 more ... | 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<{ readonly summarize: Tool<"summarize", { readonly parameters: String; readonly success: Struct<...>; readonly failure: SubagentToolFailure<...>; readonly failureMode: "error"; }, AgentSpawner | ... 1 more ... | SubagentDurability>; }>, undefined, undefined, undefined>.toolkit: Toolkit.Toolkit<{
readonly summarize: Tool<"summarize", {
readonly parameters: Schema.String;
readonly success: Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>;
readonly failure: Subagent.SubagentToolFailure<Schema.Never>;
readonly failureMode: "error";
}, AgentSpawner | RunEventSink | SubagentDurability>;
}>
toolkit
:
import Toolkit
Toolkit
.
const make: <[Tool<"summarize", {
readonly parameters: Schema.String;
readonly success: Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>;
readonly failure: Subagent.SubagentToolFailure<Schema.Never>;
readonly failureMode: "error";
}, AgentSpawner | RunEventSink | SubagentDurability>]>(tools_0: Tool<"summarize", {
readonly parameters: Schema.String;
readonly success: Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>;
readonly failure: Subagent.SubagentToolFailure<Schema.Never>;
readonly failureMode: "error";
}, AgentSpawner | ... 1 more ... | SubagentDurability>) => Toolkit.Toolkit<...>

Creates a new toolkit from the specified tools.

Details

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.

Example (Creating a toolkit)

import { Effect, Schema } from "effect"
import { Tool, Toolkit } from "effect/ai"
const GetCurrentTime = Tool.make("GetCurrentTime", {
description: "Get the current timestamp",
success: Schema.Number
})
const GetWeather = Tool.make("get_weather", {
description: "Get weather information",
parameters: Schema.Struct({ location: Schema.String }),
success: Schema.Struct({
temperature: Schema.Number,
condition: Schema.String
})
})
const toolkit = Toolkit.make(GetCurrentTime, GetWeather)
const ready = toolkit.pipe(Effect.provide(toolkit.toLayer({
GetCurrentTime: () => Effect.succeed(0),
get_weather: () => Effect.succeed({ temperature: 20, condition: "clear" })
})))
Object.keys((await Effect.runPromise(ready)).tools) // => ["GetCurrentTime", "get_weather"]

@stability ― unstable

@category ― constructors

@since ― 4.0.0

make
(
const Summarize: Subagent.SubagentDelegation<"summarize", Schema.String, Schema.String, string, {}, Schema.String, Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>, Schema.Never, never, never, "error"> & {
readonly target: Agent.Definition<Schema.String, Schema.String, string, Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "summarizer";
};
}
Summarize
.
SubagentDelegation<"summarize", String, String, string, {}, String, Struct<{ readonly output: String; readonly budgetExhausted: Boolean; }>, Never, never, never, "error">.tool: Tool<"summarize", {
readonly parameters: Schema.String;
readonly success: Schema.Struct<{
readonly output: Schema.String;
readonly budgetExhausted: Schema.Boolean;
}>;
readonly failure: Subagent.SubagentToolFailure<Schema.Never>;
readonly failureMode: "error";
}, AgentSpawner | RunEventSink | SubagentDurability>

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.

Lifetime Parent behavior Choose it when
In-memory attached Waits for the child in the same process Restarting after process loss is acceptable
Durable attached Suspends until the child’s canonical outcome 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.
  • Yielded Agent: Waiting parent Run
  • Yielded Agent: Attached child
  • Yielded Agent: Parent Thread
  • Yielded Agent: Background worker
  • Attached child to Waiting parent Run: tool result
  • Background worker to Parent Thread: message

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.

Run the in-memory example, or use the durable host assembly with the Node host.

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.