# Agent versioning

Source: https://docs.usetone.ai/agent-versioning

> Editing an agent changes nothing. Publishing does. Every call pins the version that ran it, so a finished call stays explainable.

Prompts change constantly, and a call placed last Tuesday was placed by a
different prompt from the one in the editor today. Versioning is what keeps
"why did it say that?" answerable.

## The rules

1. **Editing writes a working copy.** `GET /v1/agents/{id}` returns it. Nothing
   about live traffic changes.
2. **Publishing freezes it** into an immutable, numbered version and points the
   agent at it. This is the only step that changes behaviour.
3. **Every call pins its version at creation.** `calls.agentVersion` says which
   one ran, forever — so you can bucket outcomes by prompt.
4. **Rolling back mints a NEW version** carrying the old content, rather than
   moving a pointer backwards. The history stays append-only, and the rollback
   itself is visible in it.

```bash
# publish the working copy
curl "$TONE_API/v1/agents/$AGENT/publish" -X POST -H "Authorization: Bearer $TONE_KEY"

# read the history
curl "$TONE_API/v1/agents/$AGENT/versions" -H "Authorization: Bearer $TONE_KEY"

# read exactly what ran on a call
curl "$TONE_API/v1/agents/$AGENT/versions/3" -H "Authorization: Bearer $TONE_KEY"
```

## Which version answers

| | Version used |
|---|---|
| An outbound call you place | Whatever is live when you place it |
| A running campaign | The version it launched with, for the whole run |
| An inbound call | Always the live version |

A running campaign finishing on its launch version is deliberate: a campaign is
one experiment, and changing the prompt halfway would make its results
uninterpretable. To change a running campaign, pause it, publish, and relaunch.

## What a version does and does not capture

A version pins the **set of knowledge-base ids** it was published with, not
their contents. Re-indexing a base changes what past versions answer with —
which is usually what you want, since the base is a source of truth rather than
a prompt.

Secrets are referenced, never copied. A version records that a tool authenticates
with secret X, not what X was at the time.

Versions are kept forever. Calls that predate the feature report
`agentVersion: null`, because "we do not know" is the truthful answer.