Reference

Agent sessions

An AgentSession is a durable conversation with one pinned AgentVersion.

Checked 2026-09-28

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

Not available yet. Sylphx Agents is declared in the registry but no backend serves it: every call answers 501 with the problem code UNIMPLEMENTED.

#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.
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 environment for this session; when omitted, use the pinned Agent version's default. An explicit value replaces that default.
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.

#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	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	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.

#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 · not available yet · 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 · not available yet · 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 · not available yet · 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 · not available yet · 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 · not available yet · 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 · not available yet · 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 · not available yet · 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 · not available yet · 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 · not available yet · Request, response and examples