> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Versioning

> Track changes to the whole agent definition, diff versions, and restore previous ones

Cotool keeps a version history for each agent. A version is a snapshot of the agent's **whole definition** — not just its prompt — so you can see exactly what changed between any two points, and roll back if a change makes things worse.

## What a Version Captures

Each version is a snapshot of the entire definition:

* System prompt
* Model and planning mode
* Tools (including agent-as-tool references) and skills
* Inputs and acceptance criteria
* Structured-output schema and tags
* Triggers

Versions are **append-only**: each one is recorded as a new entry in the timeline, and identical definitions are de-duplicated so a no-op change doesn't create noise.

## When a New Version Is Recorded

Cotool appends a version whenever the agent's **definition** changes:

* Editing the system prompt
* Accepting an [AI-suggested improvement](/improving-agents/ai-suggested-improvements)
* Creating, editing, or deleting a trigger
* A change applied by [Response Agents as Code](/agents/response-agents-as-code) sync (tagged with the source commit)

Toggling a trigger on or off does **not** create a version — whether a trigger is enabled is runtime state, not part of the definition.

## Viewing and Comparing Versions

Agent versions are visible in two places:

* **When editing an agent** — open the version dropdown to browse history, **diff** any two versions, and **Export as YAML** for the current definition.
* **On the Evaluations tab** — the per-version breakdown is labeled by version (`v1`, `v4`, …) so you can see which version produced each run and compare performance across versions.

## Restoring Previous Versions

If a new version performs worse, you can restore an earlier one:

1. Open the agent's version history
2. Select the version you want to restore
3. Click **Restore**

Restoring appends a **new** version that matches the one you chose (history is never rewritten — `A → B → restore-to-A` is three entries, not a rollback of the timeline). It also reconciles the agent's triggers back to that version: recreating, updating, or deleting them to match, minting fresh webhook secrets where needed, and resolving Slack/Linear integrations. A trigger whose integration isn't connected is skipped rather than failing the restore.

The agent immediately uses the restored definition for all new runs.

<Note>
  For agents managed by [Response Agents as Code](/agents/response-agents-as-code), the version history shows synced and manual changes together in one timeline. Since managed agents are read-only in the UI, you roll them back by reverting the change in Git.
</Note>