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;
    model?: ModelStrings,
    maxTokens?: number | MaxTokens;
}, 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.
​
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,
  },
): 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.
​
Returns
Promise<T>
Returns a promise that resolves to the result of specified or inferred return type T.

​
Agent.total_usage

A method to obtain the token usage of an agent for accross all invocations. 
total_usage(): Usage
​
Returns
Usage
The token usage accross all invocations of the agent.

​
Agent.last_usage

A method to obtain the token usage of an agent for the last invocation. 
last_usage(): Usage
​
Returns
Usage
The token usage of the last invocation of the agent.

​
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