sylphx agents
Every sylphx agents command: its argument, its flags and a run line.
The agents commands of Sylphx Agents, as the CLI spells them: the same
calls as the agents API page, typed for the
shell. Install, sign in and the grammar are on the CLI index.
capture-credential
Captures an existing grant for one session and purpose; never issues a key.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents capture-credential orgs/acme/projects/shop/envs/productionPOST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents:capture-credential · scope agents:sessions · effect write · Request, response and examples
Flags
| Flag | Type | What it does |
|---|---|---|
--session | string | The prospective or existing session to bind this handle to. Required. |
--turn | int | The turn allowed to use the execution credential. Required. |
--credential | string | The existing caller-owned credential, stored encrypted and never logged. Required. The value is never returned. |
--expires-at | timestamp | The issuer-provided expiry of the captured credential. Required. |
--allowed-tools | string | Pinned tool names allowed to inject this credential. Required. Repeat the flag for each value. |
--purpose | string | execution, completion, or runtime; runtime handles never enter the guest. Required. |
rotate-credential
Rotates the captured value under the same handle with generation fencing.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents rotate-credential orgs/acme/projects/shop/envs/productionPOST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents:rotate-credential · scope agents:sessions · effect write · Request, response and examples
Flags
| Flag | Type | What it does |
|---|---|---|
--handle | string | The opaque handle whose captured credential is being replaced. Required. The value is never returned. |
--generation | int | The current handle generation; stale rotations are refused. Required. |
--credential | string | The replacement issuer-provided credential, stored encrypted. Required. The value is never returned. |
--expires-at | timestamp | The issuer-provided expiry of the replacement credential. Required. |
revoke-credential
Revokes one captured handle. Repeating the revocation is harmless.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents revoke-credential orgs/acme/projects/shop/envs/productionPOST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents:revoke-credential · scope agents:sessions · effect write · Request, response and examples
Flags
| Flag | Type | What it does |
|---|---|---|
--handle | string | The opaque handle to revoke; repeated revocation is harmless. Required. The value is never returned. |
get
Gets an agent.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents get orgs/acme/projects/shop/envs/production/agents/agentGET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent · scope agents:read · effect read · Request, response and examples
list
Lists agents.
PARENT — optional: the CLI fills it from the linked project or the
key's scope when it is left out.
CLI
sylphx agents list orgs/acme/projects/shop/envs/productionGET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents · scope agents:read · 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 over labels and filterable fields. |
--order-by | string | AIP-132 ordering over filterable fields. |
create
Creates an agent and its version 1.
ID — The id segment of the new Resource's name; the server assigns one when omitted.
CLI
sylphx agents create --parent orgs/acme/projects/shop/envs/production --spec.models.primary … --spec.models.light …POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents · scope agents:write · 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. |
--spec.instructions | string | The system instructions, at most 256 KiB. |
--spec.tools | json | The tools the agent may call, at most 128, each name once. Repeat the flag for each value. |
--spec.mcp-servers | json | The MCP servers whose tools the agent may call, at most 32. Repeat the flag for each value. |
--spec.skills | json | Skills: instruction packs the agent loads when relevant, at most 64. Repeat the flag for each value. |
--spec.memory-stores | string | The memory stores the agent recalls from and writes to, as MemoryStore names; at most 8. Repeat the flag for each value. |
--spec.tool-policy.default-decision | enum | The decision for a call no rule matches; default allow. One of allow, deny, ask. |
--spec.tool-policy.rules | json | Rules in order; the first match decides. At most 256. Repeat the flag for each value. |
--spec.tool-policy.approval-timeout | duration | How long a call waits for a person's answer before it is denied, 1m to 7d; default 24h. |
--spec.tool-policy.egress-allow-hosts | string | Hosts every network call of the agent's tools may reach, beyond the tools' own endpoints; *.example.com matches subdomains. Private and internal addresses are refused whatever this says. Repeat the flag for each value. |
--spec.budget.max-steps-per-turn | int | Model and tool steps per turn, 1 to 1000; default 100. |
--spec.budget.turn-timeout | duration | Absolute maximum turn lifetime, 10s to 24h; default 4h from the original turn start, including retries. Observed model and tool progress renews the turn and sandbox inactivity leases only up to this maximum. |
--spec.budget.max-session-spend-micros | int | Spend per session in micro-USD, models and tools together; 0 is the project's spend limit only. |
--spec.end-user-access | bool | Whether end-user session access is intended for this agent. Reserved until the backend enforces end-user ownership; all contract methods currently require a secret key. |
--spec.environment.shape | string | A Sylphx Sandboxes shape; empty gives sessions no environment. |
--spec.environment.idle-standby | duration | Put the environment in standby after this long idle, 1m to 24h; default 10m. |
--spec.environment.template | string | The Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field. |
--spec.environment.repo.uri | string | The repository URI. Access uses the session's bound credential handles. |
--spec.environment.repo.revision | string | The commit or ref to check out; empty uses the repository's default branch. |
--spec.environment.egress.egress | enum | Default ALLOW. One of allow, deny, allowlist. |
--spec.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. |
--spec.environment.egress.allowed-cidrs | string | Public CIDRs reachable when egress is ALLOWLIST. Repeat the flag for each value. |
--spec.environment.budget.max-cpu-seconds | int | End CPU_BUDGET after this many vCPU-seconds of guest CPU time. |
--spec.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. |
--spec.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. |
--spec.models.primary | string | The exact Sylphx AI catalog id (ai_models) of the owner model, pinned for the life of a session; the runtime never remaps it. Required. |
--spec.models.light | string | The exact catalog id of the cheap model used only for owner-briefed subcall.* tools and in-loop compaction; never an owner. Required. |
--spec.read-only | bool | Read-only: the version holds no write grant, so it may verify another agent's work but never own it. Create and update refuse memory stores, MCP servers, app_function and client tools, the memory, browser and computer built-ins, and an HTTP tool whose pinned operation is not GET or HEAD unless it is runtime_only. The shell and files built-ins, and a claude_code or codex harness (which bring their own), need environment.egress that denies by default: DENY, or ALLOWLIST of the configured Sylphx API and inference gateways and the version's GET or HEAD tool hosts, with no CIDRs. Session create, :send and :run check the version and the session's effective environment again, and refuse any model-facing credential that is not a captured Access key holding only <service>:read and ai:inference scopes; a renewal's credential_updates value for a model-facing binding is held to the same rule. A run's completion.result_fields never map into the completion tool's path or query parameters. An OwnerPool never qualifies the version. |
--dry-run | bool | Validate and print the result without writing (validate_only). |
update
Updates an agent. A change to spec mints the next AgentVersion; sessions already started keep the version they pinned.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents update orgs/acme/projects/shop/envs/production/agents/agent --spec.models.primary … --spec.models.light …PATCH https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent · scope agents:write · effect write · Request, response and examples
Flags
| Flag | Type | What it does |
|---|---|---|
--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. |
--spec.instructions | string | The system instructions, at most 256 KiB. |
--spec.tools | json | The tools the agent may call, at most 128, each name once. Repeat the flag for each value. |
--spec.mcp-servers | json | The MCP servers whose tools the agent may call, at most 32. Repeat the flag for each value. |
--spec.skills | json | Skills: instruction packs the agent loads when relevant, at most 64. Repeat the flag for each value. |
--spec.memory-stores | string | The memory stores the agent recalls from and writes to, as MemoryStore names; at most 8. Repeat the flag for each value. |
--spec.tool-policy.default-decision | enum | The decision for a call no rule matches; default allow. One of allow, deny, ask. |
--spec.tool-policy.rules | json | Rules in order; the first match decides. At most 256. Repeat the flag for each value. |
--spec.tool-policy.approval-timeout | duration | How long a call waits for a person's answer before it is denied, 1m to 7d; default 24h. |
--spec.tool-policy.egress-allow-hosts | string | Hosts every network call of the agent's tools may reach, beyond the tools' own endpoints; *.example.com matches subdomains. Private and internal addresses are refused whatever this says. Repeat the flag for each value. |
--spec.budget.max-steps-per-turn | int | Model and tool steps per turn, 1 to 1000; default 100. |
--spec.budget.turn-timeout | duration | Absolute maximum turn lifetime, 10s to 24h; default 4h from the original turn start, including retries. Observed model and tool progress renews the turn and sandbox inactivity leases only up to this maximum. |
--spec.budget.max-session-spend-micros | int | Spend per session in micro-USD, models and tools together; 0 is the project's spend limit only. |
--spec.end-user-access | bool | Whether end-user session access is intended for this agent. Reserved until the backend enforces end-user ownership; all contract methods currently require a secret key. |
--spec.environment.shape | string | A Sylphx Sandboxes shape; empty gives sessions no environment. |
--spec.environment.idle-standby | duration | Put the environment in standby after this long idle, 1m to 24h; default 10m. |
--spec.environment.template | string | The Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field. |
--spec.environment.repo.uri | string | The repository URI. Access uses the session's bound credential handles. |
--spec.environment.repo.revision | string | The commit or ref to check out; empty uses the repository's default branch. |
--spec.environment.egress.egress | enum | Default ALLOW. One of allow, deny, allowlist. |
--spec.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. |
--spec.environment.egress.allowed-cidrs | string | Public CIDRs reachable when egress is ALLOWLIST. Repeat the flag for each value. |
--spec.environment.budget.max-cpu-seconds | int | End CPU_BUDGET after this many vCPU-seconds of guest CPU time. |
--spec.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. |
--spec.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. |
--spec.models.primary | string | The exact Sylphx AI catalog id (ai_models) of the owner model, pinned for the life of a session; the runtime never remaps it. Required. |
--spec.models.light | string | The exact catalog id of the cheap model used only for owner-briefed subcall.* tools and in-loop compaction; never an owner. Required. |
--spec.read-only | bool | Read-only: the version holds no write grant, so it may verify another agent's work but never own it. Create and update refuse memory stores, MCP servers, app_function and client tools, the memory, browser and computer built-ins, and an HTTP tool whose pinned operation is not GET or HEAD unless it is runtime_only. The shell and files built-ins, and a claude_code or codex harness (which bring their own), need environment.egress that denies by default: DENY, or ALLOWLIST of the configured Sylphx API and inference gateways and the version's GET or HEAD tool hosts, with no CIDRs. Session create, :send and :run check the version and the session's effective environment again, and refuse any model-facing credential that is not a captured Access key holding only <service>:read and ai:inference scopes; a renewal's credential_updates value for a model-facing binding is held to the same rule. A run's completion.result_fields never map into the completion tool's path or query parameters. An OwnerPool never qualifies the version. |
--allow-missing | bool | Create the agent when it does not exist (declarative upsert). |
--dry-run | bool | Validate and print the result without writing (validate_only). |
delete
Deletes an agent and its versions. An agent with sessions is refused with INVALID_STATE unless force is set, which deletes them too.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents delete orgs/acme/projects/shop/envs/production/agents/agent --yesDELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent · scope agents:write · 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 agent does not exist. |
--dry-run | bool | Validate and print the result without writing (validate_only). |
--force | bool | Also delete the agent's sessions; without it, an agent with sessions is refused with INVALID_STATE. |
--yes | bool | Do not ask before this destructive call. |
run
Atomically admits a pinned task session, initial event and pending turn.
NAME — the resource's name; a bare id is enough below the linked
project.
CLI
sylphx agents run orgs/acme/projects/shop/envs/production/agents/agentPOST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent:run · scope agents:sessions · effect write · Request, response and examples
Flags
| Flag | Type | What it does |
|---|---|---|
--agent-version | string | The immutable agent version pinned for this task attempt. Required. |
--agent-session-id | string | The stable session identifier; reusing it for another attempt is refused. Required. |
--message | json | The initial task message appended atomically with session acceptance. Required. |
--environment | json | Optional overrides of the environment in the pinned AgentVersion's frozen spec, never the Agent's current head. Omitted or empty with no mask keeps that default unchanged. Only selected fields are overlaid; see environment_mask. The effective environment must have a supported shape, finite positive TTL and valid repository, network and budget before admission. |
--credentials | key=value | Captured credential bindings by alias; credentials never enter context. Repeat the flag for each value. |
--profiles | json | Granted profile mounts for the fresh session lease. Repeat the flag for each value. |
--completion | json | The pinned tool call used by the runtime to deliver the terminal result. Required. |
--workspace-knowledge | json | Opaque, claim-pinned workspace knowledge, including its rendered instruction. |
--task-ref | string | Caller-owned opaque reference, not interpreted by Agents. |
--renewal | json | Optional pinned grant-renewal call, owned by the runtime after acceptance. |
--runtime-credential-handle | string | Same-session handle to a caller-owned scoped Access credential. Runtime only, never installed in the guest or sent to the model. Required. The value is never returned. |
--environment-mask | json | Fields of environment to overlay, relative to EnvironmentSpec, using proto snake_case paths such as ttl, repo.uri, repo.revision, egress.allowed_domains and budget.max_cost_micros. The wire value is a comma-separated string; SDK property naming does not change these paths. Omitted or empty infers populated serialized leaf fields recursively, preserving unselected siblings from the pinned version. Proto defaults (including empty lists) need an explicit mask to reset a selected field. Selected lists replace, rather than append to, the inherited list. The sole path "*" replaces the whole environment, resetting unpopulated fields. Unknown, invalid and output-only paths are rejected, as is a nonempty mask without environment. Effective validation also applies to explicit resets and whole-environment replacement. |
--item-key | string | The caller's stable identity of the work item, not interpreted otherwise. Every session and attempt with the same item key works on one repository branch derived from it, so a new attempt continues the pushed work. Omitted, the session is the item. |
--owner-pool | string | The OwnerPool this run owns work for. Admission refuses with INVALID_STATE unless agent_version is a QUALIFIED member at that moment; later turns of the session are not re-checked. |
--verifies | string | The maker sessions this run verifies, 1 to 16; empty for an ordinary run. Admission refuses with PERMISSION_DENIED unless agent_version is read-only and its Agent differs from every maker session's Agent. The verifier session never receives a maker transcript. Set at most one of owner_pool and verifies. Repeat the flag for each value. |
--organization-layer | json | The organization layer the caller binds at assignment, read from its own versioned store. The session pins it; see AgentSession.organization_layer. |