Skip to content
Console
On this page

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

Shell
sylphx agents capture-credential orgs/acme/projects/shop/envs/production

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

Flags

FlagTypeWhat it does
--sessionstringThe prospective or existing session to bind this handle to. Required.
--turnintThe turn allowed to use the execution credential. Required.
--credentialstringThe existing caller-owned credential, stored encrypted and never logged. Required. The value is never returned.
--expires-attimestampThe issuer-provided expiry of the captured credential. Required.
--allowed-toolsstringPinned tool names allowed to inject this credential. Required. Repeat the flag for each value.
--purposestringexecution, 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

Shell
sylphx agents rotate-credential orgs/acme/projects/shop/envs/production

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

Flags

FlagTypeWhat it does
--handlestringThe opaque handle whose captured credential is being replaced. Required. The value is never returned.
--generationintThe current handle generation; stale rotations are refused. Required.
--credentialstringThe replacement issuer-provided credential, stored encrypted. Required. The value is never returned.
--expires-attimestampThe 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

Shell
sylphx agents revoke-credential orgs/acme/projects/shop/envs/production

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

Flags

FlagTypeWhat it does
--handlestringThe 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

Shell
sylphx agents get orgs/acme/projects/shop/envs/production/agents/agent

GET 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

Shell
sylphx agents list orgs/acme/projects/shop/envs/production

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents · scope agents:read · 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 over labels and filterable fields.
--order-bystringAIP-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

Shell
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

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.
--spec.instructionsstringThe system instructions, at most 256 KiB.
--spec.toolsjsonThe tools the agent may call, at most 128, each name once. Repeat the flag for each value.
--spec.mcp-serversjsonThe MCP servers whose tools the agent may call, at most 32. Repeat the flag for each value.
--spec.skillsjsonSkills: instruction packs the agent loads when relevant, at most 64. Repeat the flag for each value.
--spec.memory-storesstringThe 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-decisionenumThe decision for a call no rule matches; default allow. One of allow, deny, ask.
--spec.tool-policy.rulesjsonRules in order; the first match decides. At most 256. Repeat the flag for each value.
--spec.tool-policy.approval-timeoutdurationHow long a call waits for a person's answer before it is denied, 1m to 7d; default 24h.
--spec.tool-policy.egress-allow-hostsstringHosts 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-turnintModel and tool steps per turn, 1 to 1000; default 100.
--spec.budget.turn-timeoutdurationAbsolute 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-microsintSpend per session in micro-USD, models and tools together; 0 is the project's spend limit only.
--spec.end-user-accessboolWhether 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.shapestringA Sylphx Sandboxes shape; empty gives sessions no environment.
--spec.environment.idle-standbydurationPut the environment in standby after this long idle, 1m to 24h; default 10m.
--spec.environment.templatestringThe Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field.
--spec.environment.repo.uristringThe repository URI. Access uses the session's bound credential handles.
--spec.environment.repo.revisionstringThe commit or ref to check out; empty uses the repository's default branch.
--spec.environment.egress.egressenumDefault ALLOW. One of allow, deny, allowlist.
--spec.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.
--spec.environment.egress.allowed-cidrsstringPublic CIDRs reachable when egress is ALLOWLIST. Repeat the flag for each value.
--spec.environment.budget.max-cpu-secondsintEnd CPU_BUDGET after this many vCPU-seconds of guest CPU time.
--spec.environment.budget.max-cost-microsintEnd COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.
--spec.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.
--spec.models.primarystringThe 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.lightstringThe exact catalog id of the cheap model used only for owner-briefed subcall.* tools and in-loop compaction; never an owner. Required.
--spec.read-onlyboolRead-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-runboolValidate 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

Shell
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

FlagTypeWhat it does
--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.
--spec.instructionsstringThe system instructions, at most 256 KiB.
--spec.toolsjsonThe tools the agent may call, at most 128, each name once. Repeat the flag for each value.
--spec.mcp-serversjsonThe MCP servers whose tools the agent may call, at most 32. Repeat the flag for each value.
--spec.skillsjsonSkills: instruction packs the agent loads when relevant, at most 64. Repeat the flag for each value.
--spec.memory-storesstringThe 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-decisionenumThe decision for a call no rule matches; default allow. One of allow, deny, ask.
--spec.tool-policy.rulesjsonRules in order; the first match decides. At most 256. Repeat the flag for each value.
--spec.tool-policy.approval-timeoutdurationHow long a call waits for a person's answer before it is denied, 1m to 7d; default 24h.
--spec.tool-policy.egress-allow-hostsstringHosts 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-turnintModel and tool steps per turn, 1 to 1000; default 100.
--spec.budget.turn-timeoutdurationAbsolute 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-microsintSpend per session in micro-USD, models and tools together; 0 is the project's spend limit only.
--spec.end-user-accessboolWhether 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.shapestringA Sylphx Sandboxes shape; empty gives sessions no environment.
--spec.environment.idle-standbydurationPut the environment in standby after this long idle, 1m to 24h; default 10m.
--spec.environment.templatestringThe Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field.
--spec.environment.repo.uristringThe repository URI. Access uses the session's bound credential handles.
--spec.environment.repo.revisionstringThe commit or ref to check out; empty uses the repository's default branch.
--spec.environment.egress.egressenumDefault ALLOW. One of allow, deny, allowlist.
--spec.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.
--spec.environment.egress.allowed-cidrsstringPublic CIDRs reachable when egress is ALLOWLIST. Repeat the flag for each value.
--spec.environment.budget.max-cpu-secondsintEnd CPU_BUDGET after this many vCPU-seconds of guest CPU time.
--spec.environment.budget.max-cost-microsintEnd COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.
--spec.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.
--spec.models.primarystringThe 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.lightstringThe exact catalog id of the cheap model used only for owner-briefed subcall.* tools and in-loop compaction; never an owner. Required.
--spec.read-onlyboolRead-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-missingboolCreate the agent when it does not exist (declarative upsert).
--dry-runboolValidate 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

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

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

Flags

FlagTypeWhat it does
--etagstringDelete only if the current etag matches.
--allow-missingboolSucceed when the agent does not exist.
--dry-runboolValidate and print the result without writing (validate_only).
--forceboolAlso delete the agent's sessions; without it, an agent with sessions is refused with INVALID_STATE.
--yesboolDo 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

Shell
sylphx agents run orgs/acme/projects/shop/envs/production/agents/agent

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

Flags

FlagTypeWhat it does
--agent-versionstringThe immutable agent version pinned for this task attempt. Required.
--agent-session-idstringThe stable session identifier; reusing it for another attempt is refused. Required.
--messagejsonThe initial task message appended atomically with session acceptance. Required.
--environmentjsonOptional 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.
--credentialskey=valueCaptured credential bindings by alias; credentials never enter context. Repeat the flag for each value.
--profilesjsonGranted profile mounts for the fresh session lease. Repeat the flag for each value.
--completionjsonThe pinned tool call used by the runtime to deliver the terminal result. Required.
--workspace-knowledgejsonOpaque, claim-pinned workspace knowledge, including its rendered instruction.
--task-refstringCaller-owned opaque reference, not interpreted by Agents.
--renewaljsonOptional pinned grant-renewal call, owned by the runtime after acceptance.
--runtime-credential-handlestringSame-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-maskjsonFields 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-keystringThe 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-poolstringThe 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.
--verifiesstringThe 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-layerjsonThe organization layer the caller binds at assignment, read from its own versioned store. The session pins it; see AgentSession.organization_layer.