Start

Platform

Agents

App store purchases

Auth

Builds

Credits

Database

Flags

Generated Assets

Hosting

Jobs and cron

Knowledge

Localization

Monitoring

Network

Notifications

Organizations

Queues

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

create
get
list
delete
send
steer
interrupt
decide-approval
submit-tool-result

Reference

sylphx agents agent_sessions

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

Checked 2026-09-28

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.

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

#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

Flag	Type	What it does
`--parent`	`string`	The parent to create in; defaults to the linked project or the key's scope.
`--meta.labels`	`key=value`	Caller-writable, indexed labels (AIP-122 label rules). Repeat the flag for each value.
`--meta.annotations`	`key=value`	Caller-writable, unindexed annotations. Repeat the flag for each value.
`--meta.display-name`	`string`	Caller-writable human-readable name.
`--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.
`--title`	`string`	A short title; set by the caller or summarised by the runtime.
`--environment.shape`	`string`	A Sylphx Sandboxes shape; empty gives sessions no environment.
`--environment.idle-standby`	`duration`	Put the environment in standby after this long idle, 1m to 24h; default 10m.
`--environment.template`	`string`	The Sandboxes image: `template:<name>` or an artifact image by digest, passed unchanged to the lease's `image` field.
`--environment.repo.uri`	`string`	The repository URI. Access uses the session's bound credential handles.
`--environment.repo.revision`	`string`	The commit or ref to check out; empty uses the repository's default branch.
`--environment.egress.egress`	`enum`	Default ALLOW. One of `allow`, `deny`, `allowlist`.
`--environment.egress.allowed-domains`	`string`	Hosts 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-cidrs`	`string`	Public CIDRs reachable when `egress` is ALLOWLIST. Repeat the flag for each value.
`--environment.budget.max-cpu-seconds`	`int`	End CPU_BUDGET after this many vCPU-seconds of guest CPU time.
`--environment.budget.max-cost-micros`	`int`	End COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.
`--environment.ttl`	`duration`	The 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.
`--credentials`	`key=value`	Session-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.
`--profiles`	`json`	Granted 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.
`--dry-run`	`bool`	Validate 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

Flag	Type	What it does
`--page-size`	`int`	At most this many; default 50, clamped to 1000.
`--page-token`	`string`	`next_page_token` of the previous page.
`--filter`	`string`	AIP-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

Flag	Type	What it does
`--etag`	`string`	Delete only if the current etag matches.
`--allow-missing`	`bool`	Succeed when the session does not exist.
`--dry-run`	`bool`	Validate and print the result without writing (validate_only).
`--force`	`bool`	Interrupt a running turn and delete; without it, a running session is refused with `INVALID_STATE`.
`--yes`	`bool`	Do not ask before this destructive call.

#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

Flag	Type	What it does
`--message`	`json`	The message, 1 to 64 parts. Required.

#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

Flag	Type	What it does
`--message`	`json`	The message, 1 to 64 parts. Required.

#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

Flag	Type	What it does
`--reason`	`string`	Why, 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

Flag	Type	What it does
`--call-id`	`string`	The waiting ToolCall's `id`. Required.
`--decision`	`enum`	The answer. Required. One of `approve`, `reject`.
`--remember`	`bool`	Also allow later calls of the same tool in this session without asking ("always allow"); only with APPROVE.
`--reason`	`string`	Why, 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

Flag	Type	What it does
`--call-id`	`string`	The waiting client ToolCall's `id`. Required.
`--output`	`json`	The result, at most 1 MiB of JSON. Required.
`--error`	`bool`	Whether the call failed; `output` then holds the error.

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links