Menu
Platform
AI
Alerts and status pages
App store purchases
Credits
Generated Assets
Knowledge
KV
Localization
Notifications
Organizations
Payments
Queues
Realtime
Sandboxes
Storage
Workflows
API reference
- Overview
- Access API keys
- Agent sessions API
- Agent versions API
- Agents API
- AI models API
- Artifact references API
- Artifacts API
- Assets API
- Auth configs API
- Bank receipts API
- Bank transfer accounts API
- Buckets API
- Builds API
- Catalogs API
- Chat profiles API
- Chat reports API
- Chat sticker packs API
- Checkout policies API
- Checkout sessions API
- Config changes API
- Config flags API
- Config segments API
- Connection providers API
- Connections API
- Connectors API
- Credit grants API
- Customer organizations API
- Customer subscriptions API
- Databases API
- Documents API
- Email domains API
- End users API
- Entities API
- Entitlement grants API
- Entries API
- Environments API
- Episodes API
- Error events API
- Error groups API
- Events API
- Exchange rates API
- Generations API
- Glossaries API
- Goals API
- Identities API
- Inbound emails API
- Inbound endpoints API
- Inbound messages API
- Inbound sms API
- Invitations API
- Job runs API
- Jobs API
- Knowledge schemas API
- KV API
- KV namespaces API
- Lease events API
- Leases API
- Licence keys API
- Licence tokens API
- Mail domains API
- Mail routes API
- Mailbox connect links API
- Mailbox OAUTH apps API
- Mailboxes API
- Memberships API
- Memories API
- Memory stores API
- Merchant accounts API
- Message topics API
- Messages API
- OAUTH clients API
- Objects API
- Organization roles API
- Orgs API
- Owner pools API
- Phone numbers API
- Portal sessions API
- Preferences API
- Price catalogs API
- Processor events API
- Projects API
- Queued executions API
- Queues API
- Realtime channels API
- Realtime members API
- Realtime messages API
- Recipients API
- Relations API
- Releases API
- Revenue API
- Revenue facts API
- Revenue sources API
- Runs API
- Sandbox shapes API
- Schedules API
- Scrubbing policies API
- Search API
- Search indexes API
- Secret versions API
- Secrets API
- Service enablements API
- Service observations API
- Services API
- Serving routes API
- Session events API
- Sessions API
- Signing key versions
- Signing keys
- Sms numbers API
- Source maps API
- Spaces API
- Store connections API
- Store purchases API
- Subscriptions API
- Suppressions API
- Tax threshold statuses API
- Templates API
- Test clocks API
- Token exchanges API
- Transfers API
- Trust policies API
- Trusted issuers API
- Uptime checks API
- Uptime manifests API
- Uptime sources API
- Usage events API
- Usage invoices API
- Usage meter prices API
- Usage meters API
- Usage reservations API
- Usage settings API
- Usage tiers API
- Volumes API
- Waits API
- Webhook deliveries API
- Webhook endpoints API
- Workflows API
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
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
| Field | Type | What it is |
|---|---|---|
name | string | The name of the agent to get. Required. |
#Response
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/agents/{agent}. |
uid | string | agt_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
spec | AgentSpec | Desired state: the definition the next version takes. Required. |
status | AgentStatus | Observed state. 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. |
#AgentStatus
| Field | Type | What it is |
|---|---|---|
observed_generation | int64 | The generation this status was computed from. Output only. |
conditions | Condition[] | Ready, Reconciling, Stalled. Output only. |
current_version | string | The newest version, which new sessions pin unless they name another. Output only. |
current_version_number | int64 | The number of the newest version, from 1. Output only. |
#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. |
#Condition
| Field | Type | What it is |
|---|---|---|
type | string | The condition type, for example Ready. |
status | ConditionStatus | Whether the condition holds. One of true, false, unknown. |
observed_generation | int64 | The generation this observation was made against. |
reason | string | A machine-readable UpperCamelCase reason. |
message | string | A customer-safe human-readable message. |
severity | Severity | How severe a FALSE condition is. One of info, warning, error. |
transition_time | timestamp | When status last changed. |
#BuiltinTool
| Field | Type | What it is |
|---|---|---|
id | string | The built-in tool's id. Required. |
config | struct | Tool-specific settings, at most 16 KiB of JSON. |
#HttpTool
| Field | Type | What it is |
|---|---|---|
openapi_uri | string | An HTTPS URL of an OpenAPI 3 document. One of the source group. |
openapi | struct | An OpenAPI 3 document, at most 1 MiB of JSON. One of the source group. |
operation_id | string | The operation the tool calls; empty exposes every operation as its own tool named <tool>_<operationId>. |
credential | CredentialBinding | The credential the gateway injects at egress; the model never sees it. |
#FunctionTool
| Field | Type | What it is |
|---|---|---|
uri | string | The HTTPS endpoint the gateway calls, a Hosting route or a verified Network Domain of this project. Required. |
timeout | duration | One call's deadline, 1s to 15m; default 60s. |
#ClientTool
| Field | Type | What it is |
|---|---|---|
timeout | duration | How long the session waits for the result before the call fails, 1s to 24h; default 10m. |
#CredentialBinding
| Field | Type | What it is |
|---|---|---|
secret | string | A Kernel Secret of this environment, by name. One of the source group. |
connection | string | A Kernel Connection (a third-party OAuth installation), by name. One of the source group. |
end_user_provider | string | The 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. |
placement | string | How the value is sent: bearer (default), header:<Name> or query:<name>. |
handle | string | An 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
| Field | Type | What it is |
|---|---|---|
tool | string | A tool name, <mcp label>__<tool> for an MCP tool; * matches any characters. Required. |
decision | PolicyDecision | The decision. Required. One of allow, deny, ask. |
condition | string | A 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
| Field | Type | What it is |
|---|---|---|
uri | string | The repository URI. Access uses the session's bound credential handles. Required. |
revision | string | The commit or ref to check out; empty uses the repository's default branch. |
#LeaseNetwork
| Field | Type | What it is |
|---|---|---|
egress | EgressPolicy | Default ALLOW. One of allow, deny, allowlist. |
allowed_domains | string[] | Hosts reachable when egress is ALLOWLIST: exact names or one leading *. wildcard label, for example api.openai.com, *.github.com. |
allowed_cidrs | string[] | Public CIDRs reachable when egress is ALLOWLIST. |
blocked_cidrs | string[] | The ranges blocked under every policy. Output only. |
#LeaseBudget
| Field | Type | What it is |
|---|---|---|
max_cpu_seconds | int64 | End CPU_BUDGET after this many vCPU-seconds of guest CPU time. |
max_cost_micros | int64 | End COST_BUDGET once the shape's list price times wall seconds reaches this many millionths of a US dollar. |
#Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.
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"