Skip to main content
An Agent is the mutable, Workspace-scoped resource you author. It has a stable agent_… ID and contains the configuration that defines its behavior: its name, model selection, system instructions, tools, MCP servers, Skills, and metadata. An Agent is not a process, a sandbox, or a Session. An AgentVersion is one immutable snapshot of that authored configuration. AgentVersions are immutable configuration history used to reproduce execution, not intermediate promotion artifacts. The Session event log remains durable execution truth.

​
Versions are automatic

Creating an Agent creates AgentVersion 1. A material update to the Agent creates the next AgentVersion automatically. An update whose effective configuration is unchanged returns the current Version instead of creating duplicate history. There is no separate draft or publish step. The stable Agent identity stays the same while its immutable Version history grows.

​
Compose capabilities in the console

The console’s Create Agent and Edit Agent dialogs configure the same fields the API accepts:
  • Built-in tools — the tools the Agent runtime provides. Leave the scope untouched for the platform default (every built-in tool enabled), or scope it per tool with an approval policy and optional web domain bounds.
  • MCP servers — named remote MCP endpoints with a default approval policy and optional per-tool overrides.
  • Skills — Skills from the Workspace catalog. Session admission freezes the Agent’s references; eligible context selection resolves each reference and records its exact version and digest. An exact reference stays pinned; latest can select a newer version for a later accepted input. Retries retain the original selection. If its catalog row disappears, the Agent detail page flags it as unavailable until you remove or restore it.
  • Selectable Skills — Skills the agent may find and activate during a Session beyond the ones it starts with. skill_selection is either listed (up to 100 Skills, each at an exact version such as "2", or "latest") or workspace (any active Skill in the Workspace). An activation pins one exact version, and a listed exact version admits that version only: asking for a newer one is refused as not selectable, and a Skill that is not listed is refused. A Skill activated mid-turn becomes eligible for read-only staging from the next user-driven turn, never in the same turn. Missing, archived or mismatched activations can be withheld before selection; see the Skill selection and retry boundaries for availability and exact-input rules. Activation never grants tools, credentials, or egress. Saving an Agent with the key omitted keeps the stored selection, and null removes it. In the dashboard, Create Agent and Edit Agent list these under Skills, separately from the skills loaded at start: choose none, a list with a version for each, or any Workspace skill. Each version is picked from the Skill’s published versions or left at latest. The Agent page shows the saved choice. Editing something else never restates it, and removing it sends the explicit null.
  • Custom tools — inline tool definitions with a JSON Schema input.
Selecting a capability on the Agent scopes what the Agent may call. It never grants account access. Connection access is a separate grant: assign a Connection to the Agent on its detail page, which mints an ordinary use_connection PermissionAssignment. An authenticated call without that grant is denied even when the capability is selected. Use the Create and version an Agent guide for current CLI, cURL, and TypeScript examples.

​
What a Session runs

A Session selects an Agent in one of two ways:
  • selecting only the Agent ID resolves its current Version at admission;
  • selecting the Agent ID and a Version pins that exact immutable Version.
Admission records the resolved AgentVersion and freezes it for the Session. Updating the Agent later affects future Sessions that select the current Version. It never changes a Session that has already been admitted. The Environment is selected separately. It is the reusable execution environment for the Session, while the AgentVersion is the immutable authored configuration. Models and harnesses remain replaceable execution lanes inside that shared Agent, Environment, and Session model.

​
Browser

The browser field is optional when creating or updating an Agent. Omit it or set it to null for no browser. Set it to { "tier": "isolate" } or { "tier": "chromium" } to declare a per-Session browser MCP server at that tier. The browser credential stays on the platform; it does not enter the sandbox, event log, or model context. Browser access is not yet generally available. It requires a configured browser deployment, refuses ZDR Workspaces, and never silently substitutes a different tier when the requested one is unavailable.

​
Update semantics

Agent updates are declarative:
  • omitted fields preserve their current value;
  • array fields replace the whole array;
  • metadata merges by key;
  • system and description can be cleared with null or an empty string;
  • an optional version rejects a stale write instead of overwriting a newer AgentVersion.
The version guard controls concurrency; it does not choose an authoring owner. UI, HTTP, SDK, CLI, and MCP are interfaces over the same Agent operations, not independent owners. An Agent has zero or one active desired-state owner. Direct writes are available while it is unclaimed; a Git- or YAML-backed source that actively reconciles it must be the sole owner and use an explicit, audited handoff before ownership changes. See Author an Agent project for the current source-authoring workflow. Do not run two active reconcilers against the same Agent.

​
Inspect history

Retrieving an Agent without a Version returns its current head. Retrieving an exact Version returns that immutable historical configuration. Listing Versions returns the Agent’s ordered configuration history. Earlier Versions remain unchanged when the Agent advances.

​
Archive

Archiving an Agent makes its authored head read-only. Existing immutable AgentVersions remain retrievable. List operations omit archived Agents unless you request them explicitly.

Create and version an Agent

Create Version 1, update the Agent, and retrieve exact history.

Edit instructions safely

Change instructions while existing Sessions keep their frozen AgentVersion.