# Headless API reference

Every signature a headless agent exposes, from settings and sendMessage to the streamOptions callbacks, the render event, and the agent methods.

The full surface of a headless agent. For how to put it together, see [Headless mode](/reference/headless-agent/).

## Settings

| Key | Type | Default | Description |
| :-- | :-- | :-- | :-- |
| `apiName` | `string` | - | The agent's API name from Agent Studio |
| `mode` | `"HEADLESS"` | - | Selects headless mode |
| `aiActions` | `Record<string, Action>` | `{}` | Client-side action handlers |
| `token` | `string` | - | JWT for authenticated agents |
| `onTokenExpired` | `() => Promise<string>` | - | Returns a fresh JWT when `token` expires. If it fails, the call rejects with `HTTP_ERROR` (401); requests never go out without the token |
| `languageOverride` | `string` | - | ISO 639-1 language code |
| `configuration.remoteActionsSettings` | `object` | From Agent Studio | Overrides which remote actions file loads |
| `configuration.screenSharingSettings` | `{ active, shareMode }` | From Agent Studio | Overrides screen sharing (`shareMode`: `"image"`, `"html"` or `"both"`) |

## `sendMessage(text, options)`

| Option | Type | Description |
| :-- | :-- | :-- |
| `conversationId` | `string` | Continue this conversation; omit to start a new one |
| `files` | `Array<File \| string>` | Images to attach (PNG, JPEG, GIF), or ids from `uploadFiles` |
| `signal` | `AbortSignal` | Stops this message |
| `streamOptions` | `object` | Callbacks, see below |

Resolves with:

| Field | Type | Description |
| :-- | :-- | :-- |
| `conversationId` | `string` | The conversation |
| `messageId` | `string` | The agent message, for feedback |
| `text` | `string` | The full agent message (markdown) |
| `steps` | `{ callId, label?, content }[]` | Tool and task agent progress |
| `actions` | `ActionResult[]` | Every client-side action run while answering |
| `suggestions` | `{ id, text, clickType, prompt? }[]` | Follow-ups. `SEND_PROMPT`: send it. `TYPE_PROMPT`: put it in your input. `CALLBACK`: app-defined |
| `assets` | `object[]` | Related content (videos, articles) |
| `quota` | `{ allowed, action, code }` | Usage limit decision; `BLOCK` means not answered |

## `streamOptions`

All optional.

| Callback | Receives | When |
| :-- | :-- | :-- |
| `onStart` | `{ conversationId, messageId, isNewConversation, abort }` | The agent started answering (once per message) |
| `onMessage` | `{ conversationId, messageId, textDelta, fullText, turn, turnText }` | Text arrived |
| `onStep` | `{ callId, label?, content, turn, conversationId, messageId }` | Tool or task agent progress |
| `onActionStart` | `{ conversationId, messageId, callId, actionKey, params, confirmationRequired, confirmationMessage? }` | The agent asked to run an action |
| `onConfirmationRequired` | Same as `onActionStart` | The action needs confirmation; return `boolean` or `Promise<boolean>` |
| `onRender` | Render event, see below | A UI component should be shown; return its element |
| `onActionComplete` | Action request plus `{ success, result }` | The action finished, failed, or was declined |
| `onTitle` | `{ conversationId, title }` | A new conversation got its AI-generated title |
| `onComplete` | The resolved response | The agent finished |
| `onError` | `Error` | The message failed or was stopped |

## Render event

| Field | Type | Description |
| :-- | :-- | :-- |
| `actionKey`, `callId`, `params` | | The action the agent called |
| `conversationId`, `messageId` | `string` | Where to show the component |
| `data` | `any` | What the action's `execute` returned (passed to its `render()`) |
| `awaitUserInput` | `boolean` | `true`: the agent waits for the user to submit or cancel |
| `submit(value, finished?)` | `Promise<Response \| undefined>` | The user submitted |
| `cancel()` | `Promise<Response \| undefined>` | The user dismissed the component |

## Agent methods

| Method | Description |
| :-- | :-- |
| `ready()` | Resolves when remote config and remote actions are loaded |
| `sendMessage(text, options)` | Sends a message and streams the answer |
| `resumePendingMessage({ streamOptions, signal })` | Continues a message interrupted by a full page load |
| `getPendingConversationId()` | The conversation of the pending message, or `null` |
| `abort()` | Stops every in-flight message |
| `conversations.list / get / rename / pin / unpin / delete` | Conversation history |
| `conversations.showComponent(container, component)` | Shows a saved component from history, read-only |
| `sendFeedback({ conversationId, messageId, rating, reason })` | Rates an agent message |
| `uploadFiles(files)` | Uploads images and returns their ids |
| `transcribe(audio, { signal })` | Turns recorded audio into text |
| `startShareScreen({ exclude })`, `stopShareScreen()` | Share the page with every message |
| `addActionHandlers(actions)`, `removeActionHandlers(keys)` | Manage actions |
| `getAvailableActions()` | All registered actions |
| `runAction(key, params)` | Runs a registered action directly |
| `setNavigationHandler(handler, timeoutMs)` | How the agent navigates your app |
| `setAgentContext(context)`, `removeAgentContext(name)` | Extra knowledge for the agent |
| `setNavigationContext(context)` | Where the user is in your app |
| `shareState(key, state, handleState, schema)`, `clearState(key)` | Live UI state |
| `runTask(params)` | Runs a task agent |
| `remove()` | Stops in-flight messages and unregisters the agent |