On this page
Agent sessions
An AgentSession is a durable conversation with one pinned AgentVersion.
An AgentSession is a durable conversation with one pinned AgentVersion. Its conversation is its SessionEvent log. Each turn runs as one Sylphx Workflows Run, and each model call and tool call is a step keyed by (session, turn, step), assigned by the runtime and never taken from the model's tool-call id. An idle session holds no Run and no compute.
Service Sylphx Agents · Resource type agents.sylphx.com/AgentSession · Name pattern orgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session} · Shape record
Fields
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session}. |
uid | string | ases_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
agent | string | The Agent the session talks to. Required. |
agent_version | string | The AgentVersion the session pinned; the Agent's current version when unset at create. |
end_user | string | The Sylphx Auth end user the session belongs to, set from the caller's end-user session; empty for a session a secret key started. An end user reads and changes only their own sessions. Output only. |
title | string | A short title; set by the caller or summarised by the runtime. |
state | SessionState | The session's state. Output only. One of idle, running, awaiting_approval, awaiting_client, failed, archived. |
turn_count | int64 | The number of turns started, from 0. Output only. |
last_event_sequence | int64 | The sequence of the newest event, from 0. Output only. |
create_time | timestamp | When the session was created. Output only. |
update_time | timestamp | When the last event was appended. Output only. |
usage | SessionUsage | What the session has used so far. Output only. |
environment_lease | string | The Sylphx Sandboxes lease attached to the session, while it has one. Output only. |
environment | EnvironmentSpec | The immutable effective environment for this session. RunAgent resolves it from the pinned AgentVersion's frozen default and selected request overrides. For CreateAgentSession, omission inherits the pinned default; an explicit environment replaces it. |
credentials | map<string, CredentialBinding> | Session-scoped credential bindings, keyed by the tool or MCP credential name. Values are references or opaque handles, never secret values. |
profiles | ProfileMount[] | Granted platform Profiles to mount when the session starts, each by resource name and mode. The runtime never puts profile values in events. |
verifies | string[] | The maker sessions this session verifies, as its :run named them; empty for any other session. Output only. |
archive_time | timestamp | When the session was archived; unset while it is not archived. Output only. |
organization_context | struct | The pinned organization layer: its sha256 digest, instructions and skill names and descriptions. Skill bodies are never returned. Output only. |
organization_layer | OrganizationLayer | The organization layer the caller binds at assignment, read from its own versioned store. Admission pins it for the session's life: its instructions and skill index are injected at every activation, and a skill body is read from the pin only when the agent loads it. Never returned; organization_context shows the pin. |
Methods
Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.
| Method | Call | What it does |
|---|---|---|
POST | invoke_tool | Guest execution capability authentication, not an Access management key. Preserve any JSON tool result, including scalars and arrays. |
GET | tool_catalog | The immutable pinned HTTP-tool catalog exposed to the guest's MCP bridge. |
POST | create | Starts a session of an agent, pinned to its current version unless agent_version names another. Requires a secret key until end-user ownership is implemented. The session starts idle; :send starts its first turn. |
GET | get | Gets a session. |
GET | list | Lists sessions, newest first. With a publishable key, only the caller's end user's sessions. |
DELETE | delete | Deletes a session and its events. A session whose turn is running is refused with INVALID_STATE unless force is set, which interrupts it first. |
POST | archive | Archives a session: the session and its event log stay readable, but no new turn may start and the session's captured credential handles are revoked. An idle or failed session archives at once; a running turn is refused with INVALID_STATE (interrupt it first). Repeating the call with the same Idempotency-Key returns the same session. |
POST | queue_execution | Explicitly reserves existing captured authority for one future turn, without executing it. |
POST | resume | Consumes all ready owners atomically with fresh exact-next-turn authority. |
POST | send | Sends a user message. On an idle or failed session it starts a new turn; while a turn runs it is refused with INVALID_STATE (use :steer). The same Idempotency-Key returns the same event. |
POST | steer | Sends a message into the running turn; the agent reads it at its next step. On an idle session it is the same as :send. |
POST | interrupt | Stops the running turn at its current step. Calls already made keep their results; the session becomes idle. A no-op on an idle session. |
POST | decide_approval | Answers a tool call waiting for approval; the turn continues. |
POST | submit_tool_result | Returns the result of a client tool call; the turn continues. |
invoke_tool
Guest execution capability authentication, not an Access management key. Preserve any JSON tool result, including scalars and arrays.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:invoke-tool · scope agents:sessions · effect write · Request, response and examples
tool_catalog
The immutable pinned HTTP-tool catalog exposed to the guest's MCP bridge.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:tool-catalog · scope agents:sessions · effect read · Request, response and examples
create
Starts a session of an agent, pinned to its current version unless agent_version names another. Requires a secret key until end-user ownership is implemented. The session starts idle; :send starts its first turn.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions · scope agents:sessions · effect write · Request, response and examples
get
Gets a session.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session · scope agents:sessions · effect read · Request, response and examples
list
Lists sessions, newest first. With a publishable key, only the caller's end user's sessions.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions · scope agents:sessions · effect read · paginated · Request, response and examples
delete
Deletes a session and its events. A session whose turn is running is refused with INVALID_STATE unless force is set, which interrupts it first.
DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session · scope agents:sessions · effect destructive · Request, response and examples
archive
Archives a session: the session and its event log stay readable, but no new turn may start and the session's captured credential handles are revoked. An idle or failed session archives at once; a running turn is refused with INVALID_STATE (interrupt it first). Repeating the call with the same Idempotency-Key returns the same session.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:archive · scope agents:sessions · effect write · Request, response and examples
queue_execution
Explicitly reserves existing captured authority for one future turn, without executing it.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:queueExecution · scope agents:sessions · effect write · Request, response and examples
resume
Consumes all ready owners atomically with fresh exact-next-turn authority.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:resume · scope agents:sessions · effect write · Request, response and examples
send
Sends a user message. On an idle or failed session it starts a new turn; while a turn runs it is refused with INVALID_STATE (use :steer). The same Idempotency-Key returns the same event.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:send · scope agents:sessions · effect write · Request, response and examples
steer
Sends a message into the running turn; the agent reads it at its next step. On an idle session it is the same as :send.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:steer · scope agents:sessions · effect write · Request, response and examples
interrupt
Stops the running turn at its current step. Calls already made keep their results; the session becomes idle. A no-op on an idle session.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:interrupt · scope agents:sessions · effect write · Request, response and examples
decide_approval
Answers a tool call waiting for approval; the turn continues.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:decideApproval · scope agents:sessions · effect write · Request, response and examples
submit_tool_result
Returns the result of a client tool call; the turn continues.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:submitToolResult · scope agents:sessions · effect write · Request, response and examples