Skip to content
Console
Menu

Alerts and status pages

App store purchases

Credits

Knowledge

KV

Notifications

Organizations

Storage

Workflows

API reference

Getting Started

Authentication

KV Store

Get an agent

Gets an agent.

Gets an agent.

  • Path GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents/agent
  • Scope agents:read
  • Effect read — nothing is written.
  • Collection agents

#Request

FieldTypeWhat it is
namestringThe name of the agent to get. Required.

#Response

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/agents/{agent}.
uidstringagt_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
specAgentSpecDesired state: the definition the next version takes. Required.
statusAgentStatusObserved state. 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.

#AgentStatus

FieldTypeWhat it is
observed_generationint64The generation this status was computed from. Output only.
conditionsCondition[]Ready, Reconciling, Stalled. Output only.
current_versionstringThe newest version, which new sessions pin unless they name another. Output only.
current_version_numberint64The number of the newest version, from 1. Output only.

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

#Condition

FieldTypeWhat it is
typestringThe condition type, for example Ready.
statusConditionStatusWhether the condition holds. One of true, false, unknown.
observed_generationint64The generation this observation was made against.
reasonstringA machine-readable UpperCamelCase reason.
messagestringA customer-safe human-readable message.
severitySeverityHow severe a FALSE condition is. One of info, warning, error.
transition_timetimestampWhen status last changed.

#BuiltinTool

FieldTypeWhat it is
idstringThe built-in tool's id. Required.
configstructTool-specific settings, at most 16 KiB of JSON.

#HttpTool

FieldTypeWhat it is
openapi_uristringAn HTTPS URL of an OpenAPI 3 document. One of the source group.
openapistructAn OpenAPI 3 document, at most 1 MiB of JSON. One of the source group.
operation_idstringThe operation the tool calls; empty exposes every operation as its own tool named <tool>_<operationId>.
credentialCredentialBindingThe credential the gateway injects at egress; the model never sees it.

#FunctionTool

FieldTypeWhat it is
uristringThe HTTPS endpoint the gateway calls, a Hosting route or a verified Network Domain of this project. Required.
timeoutdurationOne call's deadline, 1s to 15m; default 60s.

#ClientTool

FieldTypeWhat it is
timeoutdurationHow long the session waits for the result before the call fails, 1s to 24h; default 10m.

#CredentialBinding

FieldTypeWhat it is
secretstringA Kernel Secret of this environment, by name. One of the source group.
connectionstringA Kernel Connection (a third-party OAuth installation), by name. One of the source group.
end_user_providerstringThe end user's own grant in Sylphx Auth's agent token vault, by provider id; the session's end user must hold it. One of the source group.
placementstringHow the value is sent: bearer (default), header:<Name> or query:<name>.
handlestringAn opaque credential handle issued for this session, resolved only at egress. This is never a credential value. Never returned again. One of the source group.

#ToolPolicyRule

FieldTypeWhat it is
toolstringA tool name, <mcp label>__<tool> for an MCP tool; * matches any characters. Required.
decisionPolicyDecisionThe decision. Required. One of allow, deny, ask.
conditionstringA CEL condition over the call's input, the session's end_user and labels; the rule matches only when it is true. Empty always matches.

#RepositorySpec

FieldTypeWhat it is
uristringThe repository URI. Access uses the session's bound credential handles. Required.
revisionstringThe commit or ref to check out; empty uses the repository's default branch.

#LeaseNetwork

FieldTypeWhat it is
egressEgressPolicyDefault ALLOW. One of allow, deny, allowlist.
allowed_domainsstring[]Hosts reachable when egress is ALLOWLIST: exact names or one leading *. wildcard label, for example api.openai.com, *.github.com.
allowed_cidrsstring[]Public CIDRs reachable when egress is ALLOWLIST.
blocked_cidrsstring[]The ranges blocked under every policy. Output only.

#LeaseBudget

FieldTypeWhat it is
max_cpu_secondsint64End CPU_BUDGET after this many vCPU-seconds of guest CPU time.
max_cost_microsint64End COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar.

#Errors

Every error arrives in the body Errors describes.

#Examples

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