Skip to main content
POST
agent.sessions.create({ cwd?, systemPrompt?, metadata? })

Authorizations

Authorization
string
header
required

An API key, or a session token on its own session

Path Parameters

id
string
required

The agent's ID

Pattern: ^agt_[0-7][0-9a-hjkmnp-tv-z]{25}$

Body

application/json
cwd
string
systemPrompt
string
metadata
object

The customer's own string keys and values; never case-converted.

Response

Created

The session's projection of its events; status is computed when served.

id
string
required
Pattern: ^ses_[0-7][0-9a-hjkmnp-tv-z]{25}$
agentId
string
required
Pattern: ^agt_[0-7][0-9a-hjkmnp-tv-z]{25}$
cwd
string
required
systemPrompt
string | null
required

Composed at creation from the agent's system prompt and the one given; fixed for the session's life.

status
enum<string>
required
Available options:
idle,
running,
retrying,
failed,
blocked
lastSeq
integer
required

A position in an agent's event log.

Required range: 0 <= x <= 9007199254740991
lastUserSeq
integer
required

A position in an agent's event log.

Required range: 0 <= x <= 9007199254740991
processedSeq
integer
required

A position in an agent's event log.

Required range: 0 <= x <= 9007199254740991
heldSeq
integer
required

A position in an agent's event log.

Required range: 0 <= x <= 9007199254740991
lastError
object | null
required
retryAt
string<date-time> | null
required

RFC 3339 in UTC with milliseconds.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
lastEventAt
string<date-time> | null
required

The createdAt of the event at lastSeq; null if none.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
observedGeneration
integer
required

The agent generation the session's harness runs in full; 0 before the first.

Required range: x >= 0
metadata
object
required

The customer's own string keys and values; never case-converted.

createdAt
string<date-time>
required

RFC 3339 in UTC with milliseconds.

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$