---
# @generated by sylphx-gen 0.1.0 from contracts@3118f36f16f799965338811e17ed3a9f565a9f136b14c95e9c94a1e21d42ea3e. Do not edit.
title: "sylphx agents agent_sessions"
description: "The sylphx agents agent_sessions commands of Sylphx Agents: every verb, with its argument, its flags and a run line."
type: reference
product: agents
summary: "Every sylphx agents agent_sessions command: its argument, its flags and a run line."
updated: 2026-09-28
nav: false
---

The `agent_sessions` commands of Sylphx Agents, as the CLI spells them: the same
calls as [the `agent_sessions` API page](/docs/api/agent_sessions), typed for the
shell. [Install, sign in and the grammar](/docs/cli) 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**

```bash
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](/docs/api/agent_sessions/create)

**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**

```bash
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](/docs/api/agent_sessions/get)

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

```bash
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](/docs/api/agent_sessions/list)

**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**

```bash
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](/docs/api/agent_sessions/delete)

**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**

```bash
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](/docs/api/agent_sessions/send)

**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**

```bash
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](/docs/api/agent_sessions/steer)

**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**

```bash
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](/docs/api/agent_sessions/interrupt)

**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**

```bash
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](/docs/api/agent_sessions/decide_approval)

**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**

```bash
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](/docs/api/agent_sessions/submit_tool_result)

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