Skip to content
Console
On this page

sylphx agents agent_sessions

Every sylphx agents agent_sessions command: its argument, its flags and a run line.

The agent_sessions commands of Sylphx Agents, as the CLI spells them: the same calls as the agent_sessions API page, typed for the shell. Install, sign in and the grammar are on the CLI index.

invoke-tool

Guest execution capability authentication, not an Access management key. Preserve any JSON tool result, including scalars and arrays.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions invoke-tool orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--turnintThe live turn whose execution capability authorizes the call. Required.
--toolstringThe tool name in the session's pinned agent version. Required.
--argumentsjsonThe tool input, validated against its pinned input schema. Required.
--op-idstringThe stable operation identifier, reused for idempotent tool-call retries. Required.

tool-catalog

The immutable pinned HTTP-tool catalog exposed to the guest's MCP bridge.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions tool-catalog orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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.

ID — The id segment of the new Resource's name; the server assigns one when omitted.

CLI

Shell
sylphx agents agent-sessions create --parent orgs/acme/projects/shop/envs/production --agent …

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions · scope agents:sessions · effect write · Request, response and examples

Flags

FlagTypeWhat it does
--parentstringThe parent to create in; defaults to the linked project or the key's scope.
--meta.labelskey=valueCaller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value.
--meta.annotationskey=valueCaller-writable, unindexed annotations. Repeat the flag for each value.
--meta.display-namestringCaller-writable human-readable name.
--agentstringThe Agent the session talks to. Required.
--agent-versionstringThe AgentVersion the session pinned; the Agent's current version when unset at create.
--titlestringA short title; set by the caller or summarised by the runtime.
--environment.shapestringA Sylphx Sandboxes shape; empty gives sessions no environment.
--environment.idle-standbydurationPut the environment in standby after this long idle, 1m to 24h; default 10m.
--environment.templatestringThe Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field.
--environment.repo.uristringThe repository URI. Access uses the session's bound credential handles.
--environment.repo.revisionstringThe commit or ref to check out; empty uses the repository's default branch.
--environment.egress.egressenumDefault ALLOW. One of allow, deny, allowlist.
--environment.egress.allowed-domainsstringHosts reachable when egress is ALLOWLIST: exact names or one leading *. wildcard label, for example api.openai.com, *.github.com. Repeat the flag for each value.
--environment.egress.allowed-cidrsstringPublic CIDRs reachable when egress is ALLOWLIST. Repeat the flag for each value.
--environment.budget.max-cpu-secondsintEnd CPU_BUDGET after this many vCPU-seconds of guest CPU time.
--environment.budget.max-cost-microsintEnd COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.
--environment.ttldurationThe lease's maximum wall time, passed to Sandboxes as ttl. The lease is released when the session ends even if this bound has not been reached.
--credentialskey=valueSession-scoped credential bindings, keyed by the tool or MCP credential name. Values are references or opaque handles, never secret values. Repeat the flag for each value.
--profilesjsonGranted platform Profiles to mount when the session starts, each by resource name and mode. The runtime never puts profile values in events. Repeat the flag for each value.
--organization-layer.instructionsstringAlways loaded organization instructions, at most 256 KiB.
--organization-layer.skillsjsonUp to 256 skills with unique names; the layer is at most 1 MiB in total. Repeat the flag for each value.
--dry-runboolValidate and print the result without writing (validate_only).

get

Gets a session.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions get orgs/acme/projects/shop/envs/production/agent_sessions/agent-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.

PARENT — optional: the CLI fills it from the linked project or the key's scope when it is left out.

CLI

Shell
sylphx agents agent-sessions list orgs/acme/projects/shop/envs/production

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions · scope agents:sessions · effect read · Request, response and examples

Flags

FlagTypeWhat it does
--page-sizeintAt most this many; default 50, clamped to 1000.
--page-tokenstringnext_page_token of the previous page.
--filterstringAIP-160 filter, limited to agent, end_user and state.

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.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions delete orgs/acme/projects/shop/envs/production/agent_sessions/agent-session --yes

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

Flags

FlagTypeWhat it does
--etagstringDelete only if the current etag matches.
--allow-missingboolSucceed when the session does not exist.
--dry-runboolValidate and print the result without writing (validate_only).
--forceboolInterrupt a running turn and delete; without it, a running session is refused with INVALID_STATE.
--yesboolDo not ask before this destructive call.

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.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions archive orgs/acme/projects/shop/envs/production/agent_sessions/agent-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.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions queue-execution orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--executionjsonExisting handles captured by this caller for this exact future turn. Required.
--goalstringExact current Goal, or empty only when the Session has no Goal.
--expected-goal-versionintRequired for a Goal; its observed contract version when granting authority.
--operation-idstringPermanent caller mutation identity, at most 128 bytes. Required.
--expected-generationintZero on first creation; replacing authority requires its exact generation.
--automaticboolExplicitly authorize automatic ready-wait resume with these exact captures. Default false only reserves them. Requires captured agents:sessions as well as runtime permissions; owner holds and ordinary admission still apply.

resume

Consumes all ready owners atomically with fresh exact-next-turn authority.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions resume orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--operation-idstringPermanent caller mutation identity, at most 128 bytes. Required.
--waitsstringExact ready owners, 1 to 16; must include all outstanding Session waits. Required. Repeat the flag for each value.
--executionjsonFresh handles captured for this exact next turn; no Task is required. Required.
--queued-execution-generationintNonzero for automatic continuation: require this exact queued authority generation, caller, Goal terms and execution. Zero is explicit fresh caller admission. A delayed automatic callback never selects a replacement.

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.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions send orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--messagejsonThe message, 1 to 64 parts. Required.
--executionjsonCaptured authority for a new hosted turn. Required when starting a turn with the hosted runtime; an active-turn steer must omit it. Admission checks the exact turn and pins these inputs atomically with the message.

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.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions steer orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--messagejsonThe message, 1 to 64 parts. Required.
--executionjsonCaptured authority for a new hosted turn. Required when starting a turn with the hosted runtime; an active-turn steer must omit it. Admission checks the exact turn and pins these inputs atomically with the message.

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.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions interrupt orgs/acme/projects/shop/envs/production/agent_sessions/agent-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

Flags

FlagTypeWhat it does
--reasonstringWhy, recorded on the status event; at most 500 characters.

decide-approval

Answers a tool call waiting for approval; the turn continues.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions decide-approval orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--call-idstringThe waiting ToolCall's id. Required.
--decisionenumThe answer. Required. One of approve, reject.
--rememberboolAlso allow later calls of the same tool in this session without asking ("always allow"); only with APPROVE.
--reasonstringWhy, at most 500 characters; the agent reads it with a rejection.

submit-tool-result

Returns the result of a client tool call; the turn continues.

NAME — the resource's name; a bare id is enough below the linked project.

CLI

Shell
sylphx agents agent-sessions submit-tool-result orgs/acme/projects/shop/envs/production/agent_sessions/agent-session

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

Flags

FlagTypeWhat it does
--call-idstringThe waiting client ToolCall's id. Required.
--outputjsonThe result, at most 1 MiB of JSON. Required.
--errorboolWhether the call failed; output then holds the error.