Start with one agent that classifies a bug report. Your application supplies a model and
history Layer; the definition owns the input, output, and execution limits. This example
runs in memory. Choose a durable host when accepted work must survive restart.
}>,"Classify the bug report and explain the severity in one sentence.",Toolkit.Toolkit<{}>,undefined>(id:"triage",options:Agent.DefinitionOptions<Schema.String,Schema.Struct<{
}>,"Classify the bug report and explain the severity in one sentence.",Toolkit.Toolkit<...>,undefined,undefined,undefined>&{
...;
}):Agent.Definition<...>&{
...;
}(+3overloads)
Validate an agent ID and return a shallowly frozen, model-agnostic definition.
make("triage",{
DefinitionOptions<String,Struct<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,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,Struct<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.output: Schema.Struct<{
Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use
optionalKey
or
optional
to
mark fields as optional, and
mutableKey
to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields'
decoded types. The Encoded form mirrors the field schemas' encoded types.
Declared fields may be inherited and are copied to own properties in the
output. The __proto__ field is accepted only when it is an own property.
Parsing does not guarantee that output keys retain their input order.
@see ― Literal for a schema that represents a single literal.
@stability ― stable
@category ― constructors
@since ― 4.0.0
Literals(["low","medium","high","critical"]),
explanation:Schema.String
explanation:
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,Struct<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.instructions: "Classify the bug report and explain the severity in one sentence."
instructions:"Classify the bug report and explain the severity in one sentence.",
DefinitionOptions<String,Struct<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.toolkit: Toolkit.Toolkit<{}>
toolkit:
importToolkit
Toolkit.
constempty: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,
DefinitionOptions<String,Struct<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.policy?:Partial<Readonly<Omit<{
readonlyrunStatus:"appended"|"off";
readonlymaxTurns:number;
readonlymaxToolCalls:number;
readonlymaxDuration:Duration;
readonlytoolConcurrency:number;
readonlyrepeatedFailureLimit:number;
readonlyonExhaustion:"final-answer"|"fail";
readonlycompletionReserveTokens:number;
readonlytoolResultBounds:ToolResultBounds;
readonlycompaction:CompactionPolicy;
readonlytokenBudget?:number|undefined;
readonlycostBudgetMicrousd?:number|undefined;
readonlycontextTokenLimit?:number|undefined;
readonlyrestartOnJoinedInput?:boolean|undefined;
readonlymodelRetries?:number|undefined;
},"runStatus"| ... 7more... |"compaction">&{
...;
}>>|undefined
policy:{
maxTurns?:number|null|undefined
Maximum model turns, or null to leave turn count unbounded.
maxTurns:2,
maxToolCalls?:number|null|undefined
Maximum declared and programmatic Tool Calls, or null to leave count unbounded.
maxToolCalls:1,
maxDuration?:Input|undefined
Finite, positive wall-clock duration accepted in any Effect Duration input form.
Runs a side effect with the result of an effect without changing the original
value.
When to use
Use when you need to run an effectful observation, such as logging or
tracking, while passing the original success value to the next step.
Details
tap works similarly to flatMap, but it ignores the result of the function
passed to it. The value from the previous effect remains available for the
next part of the chain. Note that if the side effect fails, the entire chain
will fail too.
Provides dependencies to an effect using layers or a context. A layer already
built by an enclosing provide or runtime is reused. Sibling provide calls
build their own copies. Use options.local to build a fresh layer subtree.
Provides dependencies to an effect using layers or a context. A layer already
built by an enclosing provide or runtime is reused. Sibling provide calls
build their own copies. Use options.local to build a fresh layer subtree.
Provides dependencies to an effect using layers or a context. A layer already
built by an enclosing provide or runtime is reused. Sibling provide calls
build their own copies. Use options.local to build a fresh layer subtree.
awaitEffect.runPromise(provided)// => "Result for: SELECT * FROM users"
@stability ― stable
@category ― providing services
@since ― 2.0.0
provide(
importFetchHttpClient
FetchHttpClient.
constlayer:Layer<HttpClient,never,never>
Layer that provides an HttpClient implementation backed by the configured
Fetch function.
When to use
Use when an Effect program should execute HttpClient requests through the
platform fetch implementation, especially in browser, edge, or Node.js
runtimes with globalThis.fetch.
Details
The layer uses the current Fetch reference and optional RequestInit
service for each request. Request-specific method, headers, body, and abort
signal are supplied by the client and override matching RequestInit fields.
Gotchas
Fetch behavior comes from the runtime's implementation, so CORS, cookies,
redirects, abort handling, and streaming support can vary by platform.
fetch follows redirects itself by default, so HttpClient.followRedirects
has no effect unless RequestInit sets redirect: "manual". Trace
propagation is on by default, and a browser preflight fails unless the
target allows b3 and traceparent. Stream request bodies are sent as Web
streams with duplex: "half" when the runtime supports it; see
StreamBodyFallback for the unsupported case. Any content-length header is
removed before calling fetch. Chrome passes the support check but rejects
streaming uploads over HTTP/1.1, which surfaces as a TransportError, and
browsers only deliver the response after the entire request body has been sent.
@see ― Fetch for supplying the fetch implementation used by this layer
@see ― RequestInit for default RequestInit options applied before request-specific fields
@see ― StreamBodyFallback for opting into buffering on unsupported runtimes
@see ― HttpClient.TracerPropagationEnabled for leaving b3 and traceparent off a browser request
Provides dependencies to an effect using layers or a context. A layer already
built by an enclosing provide or runtime is reused. Sibling provide calls
build their own copies. Use options.local to build a fresh layer subtree.
Run agents and attached subagents with in-memory conversation history.
Provide once around the parent program and all child handler Layers so siblings
share history and one reservation ledger. Reuse a Thread ID to continue a conversation.
Each parent Run releases its reservation pool after its attached children finish cleanup.
Conversations have no per-Thread history quota; individual messages and total host memory are bounded.
Use scoped for disposable request workflows within this shared store.
Each independent Layer build owns fresh state; state is released when its Scope closes.
Process loss loses history and active execution; this Layer provides no crash recovery.
Models, tool handlers, and provider clients remain application-supplied. Default
IDs need no Layer; enclosing ID and context-preparation overrides are preserved.
For storage-backed history, provide PersistentHistory.layer and a shared
SubagentReservationsMemoryLive instead. Durable hosts own their own assembly.
Helps you run a main effect with built-in error handling, logging, and signal management.
When to use
Use to run a Bun application's main Effect with structured error handling,
log management, interrupt support, or advanced teardown capabilities.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
An optional object that can include:
disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
Share the same InMemory.layer across Runs and pass the returned threadId for follow-up
input. Providing a fresh Layer around each call creates a separate store. History lasts
until its owner Scope closes; active execution has no process-loss recovery.