Skip to main content
Agents are stateful, long‑lived LLM workers you spawn and call repeatedly; they keep conversational history across invocations. The spawn function creates a new agent instance.

​
spawn

async function spawn({
    premise?: string,
    system?: string,
    model?: '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',
    maxTokens?: number,
    listener?: (iid: string, chunk: Chunk) => void,
}, scope?: object): Promise<Agent>
Parameters
​
premise
string
required
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
required
An system prompt for the agent. This is for providing completely custom behaviour.
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
Defaults to openai:gpt-4.1.
​
maxTokens
number
The maximum number of tokens that the agent can generate during one round of inference.Defaults to 2048.
​
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

The Agent class represents a stateful agent that maintains conversation history.

​
Methods

​
call

Invoke the agent with a task. 
async call<T>(
  prompt: string,
  scope?: object,
  config?: {
    listener?: (iid: string, chunk: Chunk) => void,
  },
): Promise<T>;
Parameters
​
prompt
string
required
The agent’s task (or objective) for this invocation of the agent.
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.

​
close

Manually close the 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