Skip to main content

​
spawn

A function to spawn an agent. 
async function spawn({
    premise?: string,
    system?: string | Template,
    listener?: (iid: string, chunk: Chunk) => void;
    listenerIncludeUsage?: boolean;
    model?: ModelStrings,
    maxTokens?: number | MaxTokens;
    reasoningEffort?: ReasoningEffort;
    cacheTTL?: '5m' | '1h';
}, scope?: object): Promise<Agent>
Parameters
​
premise
string
An initial premise for the agent. This will be attached to the system prompt of this agent.
This argument cannot be provided along with the system argument.
​
scope
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.
​
system
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.
This argument cannot be provided along with the premise argument.
​
model
string
The model which backs your agent.One of:
  • 'openai:gpt-3.5-turbo'
  • 'openai:gpt-4o'
  • 'openai:gpt-4.1'
  • 'openai:gpt-5'
  • 'anthropic:claude-sonnet-4'
  • 'anthropic:claude-opus-4.1'
  • 'anthropic:claude-sonnet-4.5'
  • 'anthropic:claude-opus-4.5'
or any OpenRouter model slug.
The default model is openai:gpt-4.1.
​
maxTokens
number | MaxTokens
Either
  • the maximum number of output tokens generated in a single round of inference in a single invocation, or
  • an instance of MaxTokens for more fine-grained control.
See MaxTokens for information on default values.
​
listener
(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.
​
listenerIncludeUsage
boolean
Whether to include usage-reporting chunks (chunk.type === 'usage') in the listener stream. Defaults to false.
​
reasoningEffort
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.
​
cacheTTL
'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.
​
Returns
Promise<Agent>
A promise that resolves to an Agent instance.

​
Agent.call

A method to invoke an agent. 
async call<T>(
  userPrompt: string | Template,
  scope?: object,
  config?: {
    listener?: (iid: string, chunk: Chunk) => void,
    listenerIncludeUsage?: boolean,
  },
): Promise<T>;
Parameters
​
userPrompt
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.
​
scope
object
Optional. Any additional resources added to the agent’s scope for this invocation.
​
config
object
Optional configuration for this invocation.
​
config.listener
(iid: string, chunk: Chunk) => void
Optional. Override the agent’s streaming listener for this specific call.
​
config.listenerIncludeUsage
boolean
Optional. Whether to include usage-reporting chunks in the listener stream for this call. Defaults to false.
​
Returns
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. 
totalUsage(): Usage
​
Returns
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. 
lastUsage(): Usage
​
Returns
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. 
async close(): Promise<void>
The agent also implements AsyncDisposable for use with await using syntax: 
await using agent = await spawn("Helper agent");
// Agent is automatically cleaned up when out of scope