Skip to content
Console
On this page

List agent versions

Lists an agent's versions, newest first.

Lists an agent's versions, newest first.

  • Path GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent/agent_versions
  • Scope agents:read
  • Effect read — nothing is written.
  • Collection agent_versions
  • Query page_size, page_token, filter
  • Pagination the answer carries agent_versions and, when there is more, next_page_token

Request

FieldTypeWhat it is
parentstringThe agent to list in. Required.
page_sizeint32At most this many; default 50, clamped to 1000.
page_tokenstringnext_page_token of the previous page.
filterstringAIP-160 filter, limited to version_number.

Response

FieldTypeWhat it is
agent_versionsAgentVersion[]The page.
next_page_tokenstringThe token of the next page; empty on the last page.

AgentVersion

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/agents/{agent}/agent_versions/{agent_version}.
uidstringagv_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
version_numberint64The version number within the agent, from 1, with no gaps. Output only.
specAgentSpecThe definition, frozen. Output only.
agent_generationint64The Agent generation that minted it. Output only.
create_timetimestampWhen it was minted. Output only.

ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

AgentSpec

FieldTypeWhat it is
instructionsstringThe system instructions, at most 256 KiB.
toolsTool[]The tools the agent may call, at most 128, each name once.
mcp_serversMcpServer[]The MCP servers whose tools the agent may call, at most 32.
skillsSkill[]Skills: instruction packs the agent loads when relevant, at most 64.
memory_storesstring[]The memory stores the agent recalls from and writes to, as MemoryStore names; at most 8.
tool_policyToolPolicyThe policy every tool call passes before it runs.
budgetAgentBudgetSpend and time limits per turn and per session.
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.
environmentEnvironmentSpecDefault session environment (shell, files, browser, computer use), frozen in each AgentVersion. RunAgent overlays only its selected environment fields on that pinned default and requires a valid fresh finite lease.
modelsAgentModelsExact owner and cheap-tool model ids. Neither is silently substituted. Required.
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.

Tool

FieldTypeWhat it is
namestringThe name the model calls, unique within the agent. Required.
descriptionstringWhat the tool does, shown to the model; at most 4096 characters.
input_schemastructThe JSON Schema of the tool's input. Built-in tools carry their own.
builtinBuiltinToolA platform tool: shell, files, browser, computer, web_fetch, web_search, remember, recall, knowledge_search or skill_load. One of the kind group.
httpHttpToolAn HTTP API described by OpenAPI. One of the kind group.
app_functionFunctionToolThe app's own server code: the gateway calls it with a short-lived signed token bound to the session, turn and step. One of the kind group.
clientClientToolRun by the client: the app executes it and returns the result as an event (:submitToolResult). One of the kind group.
runtime_onlyboolCalled only by the runtime, as a run's completion or renewal tool: never offered to the model, which cannot call it.

McpServer

FieldTypeWhat it is
labelstringThe label its tools are prefixed with, unique within the agent. Required.
uristringThe server's Streamable HTTP endpoint. Required.
allowed_toolsstring[]Only these of its tools; empty allows every tool it lists.
credentialCredentialBindingThe credential the gateway presents to the server.

Skill

FieldTypeWhat it is
namestringThe skill's name, unique within the agent. Required.
descriptionstringWhen to use it, shown to the model; at most 1024 characters. Required.
instructionsstringThe instructions it loads, at most 256 KiB. Required.

ToolPolicy

FieldTypeWhat it is
default_decisionPolicyDecisionThe decision for a call no rule matches; default allow. One of allow, deny, ask.
rulesToolPolicyRule[]Rules in order; the first match decides. At most 256.
approval_timeoutdurationHow long a call waits for a person's answer before it is denied, 1m to 7d; default 24h.
egress_allow_hostsstring[]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.

AgentBudget

FieldTypeWhat it is
max_steps_per_turnint32Model and tool steps per turn, 1 to 1000; default 100.
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.
max_session_spend_microsint64Spend per session in micro-USD, models and tools together; 0 is the project's spend limit only.

EnvironmentSpec

FieldTypeWhat it is
shapestringA Sylphx Sandboxes shape; empty gives sessions no environment.
idle_standbydurationPut the environment in standby after this long idle, 1m to 24h; default 10m.
templatestringThe Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field.
repoRepositorySpecThe repository to prepare inside the fresh lease, if any.
egressLeaseNetworkThe lease's outbound policy, using the Sandboxes network contract.
budgetLeaseBudgetThe lease's CPU and cost ceiling, separate from model and tool spend.
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.

AgentModels

FieldTypeWhat it is
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.
lightstringThe exact catalog id of the cheap model used only for owner-briefed subcall.* tools and in-loop compaction; never an owner. Required.

Errors

Every error arrives in the body Errors describes.

Examples

curl "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent/agent_versions" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"