display_name? |
string |
What a person calls the agent; its name unless given. |
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[] |
What the agent may call: a tool the server ships, by name; files for the file tools over the agent's own tree and the trees it shares; server/* for every tool of an MCP server; workers/* for every tool the connected tool workers offer it; self/* for its operations on itself; agents/* for its operations on other agents; or * for all of them. |
workspace? |
object |
Other agents' workspaces the agent mounts. Only those its resolver shares, and tools names files to reach them. |
workspace.shared? |
object |
Other agents' workspaces the agent mounts, by the name each is seen under at shared//: an agent's ID, or an ID and a mode. The resolver gives each with read or write access; mode read mounts a write share read only. |
context? |
| string[] | { files?: string[]; max_bytes?: number; } |
The files read into each turn, at most 20, in the agent's tree or one it shares, up to 16 KB of them unless max_bytes says. tools names files to read them with. |
policy? |
| string | { } |
- |
timeout? |
number |
How many seconds a turn may take. |
idle_timeout? |
number | "infinity" |
How many seconds the agent may have nothing to do before it sleeps, until something asks it. The server's default when absent. |
max_iterations? |
number | "infinity" |
How many rounds of tool calls a turn may make. |
retries? |
object |
How a turn tries a failed model call again, after a random wait of up to a second that doubles each time. A 4xx answer other than 408, 425 and 429 is not tried again. The host's defaults hold where this is absent. |
retries.attempts? |
number |
How many times a failed model call is tried again: 6 unless set. 0 never tries again. |
retries.max_wait? |
number |
The longest wait between tries, in seconds: 60 unless set. |
retries.on_exhausted? |
"ask" | "fail" |
What happens once the tries are spent: ask a person whether to try again, or fail the turn. ask unless set. |
compaction? |
| false | { at?: number; keep?: number; window?: number; } |
When the agent summarises its older history, as shares of the model's window; false never does. |
triggers? |
object[] |
The triggers that ask the agent something when they come round, each with a prompt or a prompt_file. A definition put again replaces them all, and PUT and DELETE /v1/agents/{key}/triggers/{trigger} change one. Any other field is the source's that the trigger watches, which one of them names; without one, it asks on every run. A trigger on a clock has every, and a timezone a cron expression is read in; a webhook has webhook in its place, holding its secret and how a request is verified, and is sent requests at POST /v1/hooks/{key}/{trigger}. |
notify? |
| string | string[] | { to: string | string[]; on?: ("parked" | "failed" | "finished")[]; } |
Who hears when the agent parks, fails or answers: a target its resolver names or a room in a channel, as slack:#updates; a list of them; or to and on. A room is posted in the workspace its resolver gives the channel. |
channels? |
string[] |
The chat channels, by name, it may be chosen to answer in. |