display_name? |
string |
The name shown to people. Defaults to the agent's name. |
description? |
string |
What the agent is for, in words a person reads. |
instructions? |
string |
The system prompt. |
model? |
string |
The model, as provider:model. |
tools? |
string[] |
The tools the agent can call. Each entry is one of these: the name of a built-in tool. files, for the file tools. server/, for all tools of the MCP server named server. workers/, for all tools from connected tool workers. self/, for operations on the agent itself. agents/, for operations on other agents. *, for all tools. |
workspace? |
object |
Other agents' workspaces to mount. Only workspaces the resolver shares are mounted, and the agent's tools must include files. |
workspace.shared? |
object |
Other agents' workspaces to mount. Each key is the name of the mount, at shared//. Each value is an agent ID, or an agent ID and a mode. The resolver decides whether the agent can read or write. Set mode to read to mount a writable workspace as read-only. |
context? |
| string[] | { files?: string[]; max_bytes?: number; } |
Files to add to each turn. The files can come from the agent's workspace or a shared workspace. You can list up to 20 files. Their total size is limited to 16 KB. Set max_bytes to change the limit. The agent's tools must include files. |
policy? |
| string | { } |
- |
timeout? |
number |
The maximum length of a turn, in seconds. |
idle_timeout? |
number | "infinity" |
Seconds without work before the agent sleeps. It wakes on the next message or trigger. Defaults to the server's setting. |
digest? |
boolean |
Whether the agent writes a digest of each conversation to digests/ in its workspace before it sleeps. A later conversation finds it with search_files. It needs the files tool, and counts towards the agent's budget. Defaults to true. |
max_iterations? |
number | "infinity" |
The maximum number of tool-call rounds in one turn. |
retries? |
object |
How a turn retries a failed model call. Each retry waits a random delay of up to one second, doubling each time, or the provider's Retry-After, capped at max_wait. 4xx responses other than 408, 425 and 429 are not retried. The server's defaults apply if this is not set. |
retries.attempts? |
number |
Retries for a failed model call. Defaults to 6. 0 disables retries. |
retries.max_wait? |
number |
The maximum wait between retries, in seconds. Defaults to 60. |
retries.on_exhausted? |
"ask" | "fail" |
What happens when all retries fail. ask asks a person whether to retry. fail fails the turn. Defaults to ask. |
model_options? |
object |
Options for the agent's model calls. Only these keys are accepted. The server sets all other model options. |
model_options.temperature? |
number |
The sampling temperature. |
model_options.top_p? |
number |
Top-p sampling. The model samples from the most likely tokens whose probabilities add up to this value. |
model_options.max_tokens? |
number |
The maximum number of tokens in one model response. |
model_options.reasoning_effort? |
| "default" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" |
The reasoning effort for models that support it. |
model_options.receive_timeout? |
number |
Seconds a model call waits for a response. Defaults to 300. |
model_options.stream_idle_timeout? |
number |
Seconds a model's stream may be idle. Defaults to 300. |
model_options.total_timeout? |
number |
The maximum length of one model call, in seconds. Defaults to the turn's timeout. |
compaction? |
| false | { at?: number; keep?: number; window?: number; } |
When the agent summarizes older history. The values are fractions of the model's context window. Set to false to turn off summarizing. |
triggers? |
object[] |
Triggers that run the agent. Each trigger has a prompt or a prompt_file. Defining the agent again replaces all its triggers. To change one trigger, use PUT or DELETE /v1/agents/{key}/triggers/{trigger}. A scheduled trigger has every and an optional timezone. A feed trigger has feed. A webhook trigger has webhook, with its secret and verification method. It receives requests at POST /v1/hooks/{key}/{trigger}. |
notify? |
| string | string[] | { to: string | string[]; on?: ("parked" | "failed" | "finished")[]; } |
Where to send a notification when the agent parks, fails or finishes. Use a target that the resolver defines, or a chat room like slack:#updates. You can also give a list of targets, or an object with to and on. Chat rooms are in the workspace that the resolver sets for the channel. |
channels? |
string[] |
Names of the chat channels the agent can reply in. |