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

Changed in 6 of the 163 revisions of this API.1213

Sep 27, 20264b75527da17b5See the full diff
- ●
  added the new flex_unavailable enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new flex_unavailable enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new flex_unavailable enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new flex_unavailable enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new flex_unavailable enum value to the ////////// response property for the response status
  response-property-enum-value-added
Sep 25, 202682d76d5c86cf61See the full diff
- ●
  added the new ultrafast enum value to the / response property for the response status (media type: application/json)
  response-property-enum-value-added
- ●
  added the new ultrafast enum value to the ////// response property for the response status (media type: text/event-stream)
  response-property-enum-value-added
- ●
  added the new ultrafast enum value to the ////// response property for the response status (media type: text/event-stream)
  response-property-enum-value-added
- ●
  added the new ultrafast enum value to the ////// response property for the response status (media type: text/event-stream)
  response-property-enum-value-added
- ●
  added the new ultrafast enum value to the ////// response property for the response status (media type: text/event-stream)
  response-property-enum-value-added
- ●
  added the new ultrafast enum value to the ////// response property for the response status (media type: text/event-stream)
  response-property-enum-value-added
- ○
  added the new ultrafast enum value to the request property /////
  request-property-enum-value-added
Sep 25, 2026e0550bdbb5455See the full diff
- ●
  added the new misalignment_policy_violation enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new misalignment_policy_violation enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new misalignment_policy_violation enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new misalignment_policy_violation enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new misalignment_policy_violation enum value to the ////////// response property for the response status
  response-property-enum-value-added
Sep 19, 2026d4e842399c2e11See the full diff
- ▲
  added to the response body oneOf list for the response status
  response-body-one-of-added
- ○
  added agent.session.environment.reset mapping keys to the response discriminator for the response status
  response-body-discriminator-mapping-added
Sep 11, 20268c3c08961f625See the full diff
- ●
  added the new credit_balance_exhausted enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new credit_balance_exhausted enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new credit_balance_exhausted enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new credit_balance_exhausted enum value to the ////////// response property for the response status
  response-property-enum-value-added
- ●
  added the new credit_balance_exhausted enum value to the ////////// response property for the response status
  response-property-enum-value-added
Sep 10, 2026f2dae1a9aced1See the full diff
- ○
  endpoint added
  endpoint-added

Full history