Headless

Headless API reference

The full surface of a headless agent. For how to put it together, see Headless mode.

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"`)

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

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

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

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