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
- Editing writes a working copy.
GET /v1/agents/{id}returns it. Nothing about live traffic changes. - Publishing freezes it into an immutable, numbered version and points the agent at it. This is the only step that changes behaviour.
- Every call pins its version at creation.
calls.agentVersionsays which one ran, forever — so you can bucket outcomes by prompt. - 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.
# 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.