Versions
Every change to an agent's definition is captured as a numbered version. Versions let you see what changed and who changed it, restore an earlier definition, and pin the version your tasks run while you keep editing.
What a version is
A version is a snapshot of the agent's definition: instructions, entrypoint, installed skills, tools, playbooks, harness and default model. Versions are captured automatically a few seconds after an edit settles. Each task records the version it ran on, shown as a badge on the task.
Name and restore versions
- Name a version: give the latest version a label and description so it is easy to find later.
- Restore a version: copy an earlier version's definition back onto the agent. Restoring creates a new version, so nothing is lost.
Pin a version
By default an agent always runs its latest definition. Pinning changes that: new tasks run the pinned version until you move or remove the pin, while edits keep saving and keep creating new versions. Pin a version from the Versions page or from a version's detail page. Tasks that are already running keep the version they started with.
- 01Open the agent's Versions page.
- 02Choose the version to pin and click Pin.
- 03Confirm. The Version tile on the agent overview now reads "Pinned".
- 04To go back to running the latest definition, click Unpin.
What a pin freezes
The rule: a pin freezes the agent's definition; it never freezes operational state. Credentials, resources, integrations and safety policy are always current, so pinning an older version can never revert a rotated secret or a tightened permission rule.
| Frozen by the pin | Always current |
|---|---|
| Instructions | Secret values |
| Entrypoint | Tool credentials (MCP env and headers, matched by tool name) |
| Installed skills (which ones are installed) | Skill file contents — these follow the current skill version |
| Tools (MCP url, command, arguments, enabled) | Machine kind, size and accelerator |
| Playbooks | Memory, browser and shared-folder toggles |
| Harness | Slack, GitHub and meeting connections |
| Default model | Permission rules, modes, functions, workflows |
| Agent name and tagline | Revision number (the sync marker the CLI compares against) |
Run a task on a specific version
Any new task can be started on a specific version, whether or not the agent is pinned — for example to compare a candidate version against the pinned one. Choose the version in the new-task composer, or pass agent_version_id when creating a task with POST /v2/tasks. A per-task model or machine size you choose explicitly still applies.
Limits
- A task's version is fixed when the task is created. Moving the pin does not change tasks that already exist.
- Skill file contents are not frozen: a pinned task installs the skills the version lists, at their current contents.
- Workflows, functions, modes and permission rules are not part of the pinned definition yet.
- Pushing configuration from inside a pinned task with the CLI is refused; edit the agent in the web app or push from outside the task.
- Any agent can be pinned, but a task only starts when the pinned version's harness is one the managed runtime can execute. Pin a version whose harness is the legacy
kafkaharness and every new task is refused with422 pinned_harness_unavailableuntil the agent is unpinned or pinned to a supported version — the Version tile still reads "Pinned" in the meantime. - Unpinning is the only way to take an agent back to live: it clears the pin and the Version tile updates. If an operator disables pin enforcement service-wide instead, existing pins stay recorded but stop applying — tasks run the latest definition while the tile still says "Pinned". Clear pins before enforcement is disabled if the tile must stay truthful.