Skip to content
Console
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

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/agent_sessions/{agent_session}.
uidstringases_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
agentstringThe Agent the session talks to. Required.
agent_versionstringThe AgentVersion the session pinned; the Agent's current version when unset at create.
end_userstringThe 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.
titlestringA short title; set by the caller or summarised by the runtime.
stateSessionStateThe session's state. Output only. One of idle, running, awaiting_approval, awaiting_client, failed, archived.
turn_countint64The number of turns started, from 0. Output only.
last_event_sequenceint64The sequence of the newest event, from 0. Output only.
create_timetimestampWhen the session was created. Output only.
update_timetimestampWhen the last event was appended. Output only.
usageSessionUsageWhat the session has used so far. Output only.
environment_leasestringThe Sylphx Sandboxes lease attached to the session, while it has one. Output only.
environmentEnvironmentSpecThe 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.
credentialsmap<string, CredentialBinding>Session-scoped credential bindings, keyed by the tool or MCP credential name. Values are references or opaque handles, never secret values.
profilesProfileMount[]Granted platform Profiles to mount when the session starts, each by resource name and mode. The runtime never puts profile values in events.
verifiesstring[]The maker sessions this session verifies, as its :run named them; empty for any other session. Output only.
archive_timetimestampWhen the session was archived; unset while it is not archived. Output only.
organization_contextstructThe pinned organization layer: its sha256 digest, instructions and skill names and descriptions. Skill bodies are never returned. Output only.
organization_layerOrganizationLayerThe 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.

MethodCallWhat it does
POSTinvoke_toolGuest execution capability authentication, not an Access management key. Preserve any JSON tool result, including scalars and arrays.
GETtool_catalogThe immutable pinned HTTP-tool catalog exposed to the guest's MCP bridge.
POSTcreateStarts 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.
GETgetGets a session.
GETlistLists sessions, newest first. With a publishable key, only the caller's end user's sessions.
DELETEdeleteDeletes a session and its events. A session whose turn is running is refused with INVALID_STATE unless force is set, which interrupts it first.
POSTarchiveArchives 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.
POSTqueue_executionExplicitly reserves existing captured authority for one future turn, without executing it.
POSTresumeConsumes all ready owners atomically with fresh exact-next-turn authority.
POSTsendSends 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.
POSTsteerSends a message into the running turn; the agent reads it at its next step. On an idle session it is the same as :send.
POSTinterruptStops the running turn at its current step. Calls already made keep their results; the session becomes idle. A no-op on an idle session.
POSTdecide_approvalAnswers a tool call waiting for approval; the turn continues.
POSTsubmit_tool_resultReturns 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