Skip to content
Console
Menu

Alerts and status pages

App store purchases

Credits

Knowledge

KV

Notifications

Organizations

Storage

Workflows

API reference

Getting Started

Authentication

KV Store

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.

Not available yet. This command answers 501 with the problem code UNIMPLEMENTED.

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.