Skip to main content
Create an agent. Every field is optional; omitted fields fall back to server defaults (service_tier to auto, tools to []).

Endpoint

Authentication

Authorization: Bearer <api_key> or Authorization: ApiKey <key>. Optional if AGENT_CLOUD_API_KEY is unset (open mode).

Request body

string
Human-readable name.
string
Model identifier (for example gpt-4o-mini).
string
Custom instructions appended to the agent’s base instructions.
object
Optional { "effort": string, "summary": string }.
object
Optional { "enabled": boolean, "max_concurrent_subagents": number }.
string
Defaults to auto.
object
Optional { "format": string, "verbosity": string }.
array
Tool definition objects. Built-in families are fs, shell, jobs, terminal, skills, web, ask, plan, todo and memo; browser tools use a six-image catalog (chromium, firefox, webkit, chrome, edge, brave). Every call goes through permission presets and approvals, with approval frames delivered as agent.turn.approval.*.

Response

string
Agent id (agent_<hex>).
string
Always agent.
string
Display name, if set.
string
Model identifier, if set.
string
Instructions, if set.
object
Reasoning config.
object
Multi-agent config (enabled, optional max_concurrent_subagents).
string
Service tier.
object
Text format/verbosity, if set.
array
Registered tools.
integer
Creation time in Unix epoch milliseconds.