Sign in
Agents

Create an agent session

Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See running sessions.

post/agents/sessions

Request body

metadataobject nullable

Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map.

agent_idstring

The ID of a saved reusable agent. Omit agent to use its configuration unchanged.

vault_idsstring[] nullable

The IDs of vaults made available to the session.

streamboolean

Whether to stream session events as server-sent events. Defaults to false.

Response

The created session or its event stream.

metadataobject required

Custom string key-value pairs attached to the session.

idstring required

The ID of the session.

object'agent.session' required

The object type. Always agent.session.

created_atinteger required

The Unix timestamp, in seconds, when the session was created.

last_active_atinteger required

The Unix timestamp, in seconds, when the session was last active.

status'idle' | 'in_progress' | 'requires_action' | 'failed' required

The current status of a session.

errorstring nullable required

The error that caused the session to fail, if any.

vault_idsstring[] required

The IDs of vaults made available to the session.

Changes