Agents and versions¶
An agent is a role definition shared by every team that uses it: its system prompt, its tool list, its
confirmation policy, its egress, its MCP servers and its context documents. A template's role names an agent
(agent: coder); the team runs whatever version of that agent is current when a run starts.
Versions¶
Editing an agent never overwrites it. POST /agents/{name}/versions (or the Console's Agents page) with
{from_version, ...} creates a new version that changes only what you send and makes it current. The old
version stays and can be made current again by posting a version whose from_version is the old one.
- A run that is already going keeps the version it started on; the next run of every team that runs the agent starts on the new one.
- Writes of an existing agent need
If-Matchwith the ETag of a freshGET: 428 without, 412 when stale. - Deleting an agent is refused with 409 while a template or a team still uses it.
- Reading is open to every role; changing agents is for admins.
What an agent holds¶
| Part | Meaning |
|---|---|
system_prompt |
What the agent is told about its job. |
tools |
The worker tools it is offered (send_task, ask_requester, memory_*, ...); a role file without a list is unrestricted. |
| Confirmation policy | NeverConfirm by default, because the sandbox and the gateway are the boundary; ConfirmRisky makes risky actions wait for a person. |
egress |
The hosts it may reach, see egress and destinations. |
mcp_servers |
Platform MCP servers attached to it. |
| Documents | Context documents every team of the agent gets. |
| Skills | Skills a role may name. |
A team can override an agent's egress for one role (PUT /teams/{name}/roles/{role}/egress); DELETE returns
that role to the agent's own.
Where definitions come from¶
Agents live in the control-plane database. A fresh database is filled from roles/ by the importer, and
just console-export writes the current versions back as repository files, so the files and the database can
be compared. See templates for how a role picks an agent.
Depth: architecture, Agent runtime.