> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symbolica.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

### `spawn`

A function to spawn an agent.

```typescript wrap theme={null}
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**

<ParamField body="premise" type="string">
  An initial premise for the agent. This will be attached to the system prompt of this agent.

  <Warning>
    This argument cannot be provided along with the `system` argument.
  </Warning>
</ParamField>

<ParamField body="scope" type="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.
</ParamField>

<ParamField body="system" type="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`](/references/ts/templating#template).

  <Warning>
    This argument cannot be provided along with the `premise` argument.
  </Warning>
</ParamField>

<ParamField body="model" type="string">
  The model which backs your agent.
  Any OpenRouter model slug.

  <Note>
    The default model is `openai/gpt-4.1`.
  </Note>
</ParamField>

<ParamField body="maxTokens" type="number | MaxTokens">
  Either

  * the maximum number of output tokens generated over all rounds of inference in a single invocation, or
  * an instance of `MaxTokens` for more fine-grained control.

  See [`MaxTokens`](/references/ts/usage#maxtokens) for information on default values.
</ParamField>

<ParamField body="listener" type="(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.
</ParamField>

<ParamField body="listenerIncludeUsage" type="boolean">
  Whether to include usage-reporting chunks (`chunk.type === 'usage'`) in the listener stream. Defaults to `false`.
</ParamField>

<ParamField body="reasoningEffort" type="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.
</ParamField>

<ParamField body="cacheTTL" type="'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.
</ParamField>

<ResponseField name="Returns" type="Promise<Agent>">
  A promise that resolves to an `Agent` instance.
</ResponseField>

### `Agent.call`

A method to invoke an agent.

```typescript wrap theme={null}
async call<T>(
  userPrompt: string | Template,
  scope?: object,
  config?: {
    listener?: (iid: string, chunk: Chunk) => void,
    listenerIncludeUsage?: boolean,
  },
): Promise<T>;
```

**Parameters**

<ParamField body="userPrompt" type="string" required>
  The agent's task (or objective) for this invocation of the agent.
  Either

  * a `string`, or
  * or an instance of [`Template`](/references/ts/templating#template).

  <Info>
    If the `system` argument is provided when spawning the agent, `prompt` will be provided as a raw user prompt.
  </Info>
</ParamField>

<ParamField body="scope" type="object">
  Optional. Any additional resources added to the agent's scope for this invocation.
</ParamField>

<ParamField body="config" type="object">
  Optional configuration for this invocation.
</ParamField>

<ParamField body="config.listener" type="(iid: string, chunk: Chunk) => void">
  Optional. Override the agent's streaming listener for this specific call.
</ParamField>

<ParamField body="config.listenerIncludeUsage" type="boolean">
  Optional. Whether to include usage-reporting chunks in the listener stream for this call. Defaults to `false`.
</ParamField>

<ResponseField name="Returns" type="Promise<T>">
  Returns a promise that resolves to the result of specified or inferred return type `T`.
</ResponseField>

### `Agent.totalUsage`

A method to obtain the token usage of an agent across all invocations.

```typescript theme={null}
totalUsage(): Usage
```

<ResponseField name="Returns" type="Usage">
  The token usage across all invocations of the agent. Includes `cachedTokens` and `reasoningTokens` breakdowns.
</ResponseField>

### `Agent.lastUsage`

A method to obtain the token usage of an agent for the last invocation.

```typescript theme={null}
lastUsage(): Usage
```

<ResponseField name="Returns" type="Usage">
  The token usage of the last invocation of the agent. Throws if no invocation has been made yet.
</ResponseField>

### `Agent.close`

A method to manually close an agent and clean up resources.

```typescript wrap theme={null}
async close(): Promise<void>
```

The agent also implements `AsyncDisposable` for use with `await using` syntax:

```typescript wrap theme={null}
await using agent = await spawn("Helper agent");
// Agent is automatically cleaned up when out of scope
```