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_versionsand, when there is more,next_page_token
Request
| Field | Type | What it is |
|---|---|---|
parent | string | The agent to list in. Required. |
page_size | int32 | 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 version_number. |
Response
| Field | Type | What it is |
|---|---|---|
agent_versions | AgentVersion[] | The page. |
next_page_token | string | The token of the next page; empty on the last page. |
AgentVersion
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/agents/{agent}/agent_versions/{agent_version}. |
uid | string | agv_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
version_number | int64 | The version number within the agent, from 1, with no gaps. Output only. |
spec | AgentSpec | The definition, frozen. Output only. |
agent_generation | int64 | The Agent generation that minted it. Output only. |
create_time | timestamp | When it was minted. Output only. |
ResourceMeta
| Field | Type | What it is |
|---|---|---|
generation | int64 | Increases by one on every change to spec. Output only. |
etag | string | Strong 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_time | timestamp | When the Resource was created. Output only. |
update_time | timestamp | When the Resource last changed. Output only. |
delete_time | timestamp | Set while the Resource is being deleted. Output only. |
labels | map<string, string> | Caller-writable, indexed labels (AIP-122 label rules). |
annotations | map<string, string> | Caller-writable, unindexed annotations. |
display_name | string | Caller-writable human-readable name. |
creator | string | The principal that created the Resource. Output only. |
AgentSpec
| Field | Type | What it is |
|---|---|---|
instructions | string | The system instructions, at most 256 KiB. |
tools | Tool[] | The tools the agent may call, at most 128, each name once. |
mcp_servers | McpServer[] | The MCP servers whose tools the agent may call, at most 32. |
skills | Skill[] | Skills: instruction packs the agent loads when relevant, at most 64. |
memory_stores | string[] | The memory stores the agent recalls from and writes to, as MemoryStore names; at most 8. |
tool_policy | ToolPolicy | The policy every tool call passes before it runs. |
budget | AgentBudget | Spend and time limits per turn and per session. |
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. |
environment | EnvironmentSpec | Default 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. |
models | AgentModels | Exact owner and cheap-tool model ids. Neither is silently substituted. Required. |
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. |
Tool
| Field | Type | What it is |
|---|---|---|
name | string | The name the model calls, unique within the agent. Required. |
description | string | What the tool does, shown to the model; at most 4096 characters. |
input_schema | struct | The JSON Schema of the tool's input. Built-in tools carry their own. |
builtin | BuiltinTool | A platform tool: shell, files, browser, computer, web_fetch, web_search, remember, recall, knowledge_search or skill_load. One of the kind group. |
http | HttpTool | An HTTP API described by OpenAPI. One of the kind group. |
app_function | FunctionTool | The 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. |
client | ClientTool | Run by the client: the app executes it and returns the result as an event (:submitToolResult). One of the kind group. |
runtime_only | bool | Called only by the runtime, as a run's completion or renewal tool: never offered to the model, which cannot call it. |
McpServer
| Field | Type | What it is |
|---|---|---|
label | string | The label its tools are prefixed with, unique within the agent. Required. |
uri | string | The server's Streamable HTTP endpoint. Required. |
allowed_tools | string[] | Only these of its tools; empty allows every tool it lists. |
credential | CredentialBinding | The credential the gateway presents to the server. |
Skill
| Field | Type | What it is |
|---|---|---|
name | string | The skill's name, unique within the agent. Required. |
description | string | When to use it, shown to the model; at most 1024 characters. Required. |
instructions | string | The instructions it loads, at most 256 KiB. Required. |
ToolPolicy
| Field | Type | What it is |
|---|---|---|
default_decision | PolicyDecision | The decision for a call no rule matches; default allow. One of allow, deny, ask. |
rules | ToolPolicyRule[] | Rules in order; the first match decides. At most 256. |
approval_timeout | duration | How long a call waits for a person's answer before it is denied, 1m to 7d; default 24h. |
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. |
AgentBudget
| Field | Type | What it is |
|---|---|---|
max_steps_per_turn | int32 | Model and tool steps per turn, 1 to 1000; default 100. |
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. |
max_session_spend_micros | int64 | Spend per session in micro-USD, models and tools together; 0 is the project's spend limit only. |
EnvironmentSpec
| Field | Type | What it is |
|---|---|---|
shape | string | A Sylphx Sandboxes shape; empty gives sessions no environment. |
idle_standby | duration | Put the environment in standby after this long idle, 1m to 24h; default 10m. |
template | string | The Sandboxes image: template:<name> or an artifact image by digest, passed unchanged to the lease's image field. |
repo | RepositorySpec | The repository to prepare inside the fresh lease, if any. |
egress | LeaseNetwork | The lease's outbound policy, using the Sandboxes network contract. |
budget | LeaseBudget | The lease's CPU and cost ceiling, separate from model and tool spend. |
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. |
AgentModels
| Field | Type | What it is |
|---|---|---|
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. |
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. |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.INVALID_FIELD— A field failed validation.PAGE_TOKEN_MISMATCH— A page token was reused with different parameters.
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"