spawn
A function to spawn an agent.
string
An initial premise for the agent. This will be attached to the system prompt of this agent.
object
An optional default set of resources which the agent will have access to indefinitely.
Resources in scope may be arbitrary functions, methods, objects, iterators, types or any other value.
These resources may additionally be specified per invocation later on.
string | Template
An optional system prompt for the agent. This will be the system prompt of all invocations of this agent.
Either
- a
string, or - or an instance of
Template.
string
The model which backs your agent.
Any OpenRouter model slug.
The default model is
openai/gpt-4.1.number | MaxTokens
Either
- the maximum number of output tokens generated over all rounds of inference in a single invocation, or
- an instance of
MaxTokensfor more fine-grained control.
MaxTokens for information on default values.(iid: string, chunk: Chunk) => void
A callback for streaming any invocations of the agent’s responses.
Each streamed text chunk for each agent invocation, determined by a unique invocation ID, will route to this callback.
boolean
Whether to include usage-reporting chunks (
chunk.type === 'usage') in the listener stream. Defaults to false.ReasoningEffort
Constrains the thinking budget on reasoning models which support it (e.g. GPT 5.2, Sonnet 4.5, Gemini 3).
Higher values use more reasoning tokens but may produce better results.One of:
'none', 'minimal', 'low', 'medium', 'high', 'xhigh'.If omitted, uses the model’s default reasoning effort.'5m' | '1h'
Controls how long Anthropic prompt caching entries persist. Only used for Anthropic models; ignored for other providers.
'5m' is the default Anthropic cache duration. '1h' costs more but caches longer.Promise<Agent>
A promise that resolves to an
Agent instance.Agent.call
A method to invoke an agent.
string
required
The agent’s task (or objective) for this invocation of the agent.
Either
- a
string, or - or an instance of
Template.
If the
system argument is provided when spawning the agent, prompt will be provided as a raw user prompt.object
Optional. Any additional resources added to the agent’s scope for this invocation.
object
Optional configuration for this invocation.
(iid: string, chunk: Chunk) => void
Optional. Override the agent’s streaming listener for this specific call.
boolean
Optional. Whether to include usage-reporting chunks in the listener stream for this call. Defaults to
false.Promise<T>
Returns a promise that resolves to the result of specified or inferred return type
T.Agent.totalUsage
A method to obtain the token usage of an agent across all invocations.
Usage
The token usage across all invocations of the agent. Includes
cachedTokens and reasoningTokens breakdowns.Agent.lastUsage
A method to obtain the token usage of an agent for the last invocation.
Usage
The token usage of the last invocation of the agent. Throws if no invocation has been made yet.
Agent.close
A method to manually close an agent and clean up resources.
AsyncDisposable for use with await using syntax: