On this page
- Request
- Agent
- ResourceMeta
- AgentSpec
- Tool
- McpServer
- Skill
- ToolPolicy
- AgentBudget
- EnvironmentSpec
- AgentModels
- Response
- ResourceMeta
- AgentSpec
- AgentStatus
- Tool
- McpServer
- Skill
- ToolPolicy
- AgentBudget
- EnvironmentSpec
- AgentModels
- Condition
- BuiltinTool
- HttpTool
- FunctionTool
- ClientTool
- CredentialBinding
- ToolPolicyRule
- RepositorySpec
- LeaseNetwork
- LeaseBudget
- Errors
- Examples
Create an agent
Creates an agent and its version 1.
Creates an agent and its version 1.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents - Scope
agents:write - Effect
write— a successful call changes state. - Collection agents
- Query
agent_id,validate_only
Request
| Field | Type | What it is |
|---|---|---|
parent | string | The parent to create in. Required. |
agent_id | string | The agent id, the final name segment; the server assigns one when empty. |
agent | Agent | The agent to create; only caller-writable fields are read. Required. |
validate_only | bool | Validate and return the result without writing anything. |
Agent
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/agents/{agent}. |
meta | ResourceMeta | Resource metadata. |
spec | AgentSpec | Desired state: the definition the next version takes. Required. |
ResourceMeta
| Field | Type | What it is |
|---|---|---|
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. |
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. |
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.UNKNOWN_FIELD— The request has a field the schema does not know.INVALID_FIELD— A field failed validation.RESOURCE_ALREADY_EXISTS— A Resource with this name exists.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.PLAN_LIMIT_REACHED— The plan's limit is reached.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agents" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spec":{"models":{"light":"…","primary":"…"}}}'