Versioning

A voice agent's configuration is stored as numbered versions. One of them is published, and that one is the configuration every call to the agent runs. The rest are drafts: saved, editable, and serving nobody.

Drafts and the published version

• Draft — a saved version that is not live. Edit it, publish it, or delete it. Nothing about it reaches a caller.
• Published version — the configuration the agent answers with. It can't be overwritten or deleted while it's published. You can edit it in the editor, but the edits save as a new draft.

The agent's name isn't versioned: renaming it takes effect when you save, on every version, including the published one.

Changing a live agent is two steps: save the change as a new draft, then publish that draft. Publishing points the agent at the new version, and the version it was on becomes an ordinary draft again: editable, and available to publish if you need to go back.

The published version is resolved when a call connects, so a call already in progress keeps the configuration it started with. Publishing never changes a conversation part-way through.

Version numbers

A version number is major.minor and you choose it. When you save a new draft, Tandem offers the next number for you: a minor step for an ordinary change, a major one for a change you'll want to find again later. Numbers are ordered numerically rather than alphabetically, so 1.10 is newer than 1.2.

Each version can carry a short note saying what changed. It's optional, and it's the only record of intent the version list has.

An agent holds at most 20 versions. Saving a 21st is refused, so delete one you no longer need first. A published version can't be deleted, so publish a different version before removing the one that's live.

Publishing

Publishing is the only action that changes what callers get.

It's also the point at which the rules only the server can check run. How much a draft save checks depends on where the draft comes from. The editor's Save Configuration and Save as New Draft both refuse an incomplete draft: a missing system prompt, model, or voice stops the save with the field's own message, such as "System prompt is required." Over the API, a draft save checks the shape of what you sent and little else — you can write a draft with no system prompt and no voice picked, and stop half-way through building one. Publish runs every rule a live call depends on, whichever way the draft was saved, so a draft written over the API can surface several problems here at once.

Publish is refused when:

• a required field is empty, or a set of fields required in combination is incomplete
• the agent uses an ElevenLabs voice and the ElevenLabs integration isn't connected for your organization
• an agent tool points at an agent with no published version of its own, so the hand-off would reach an agent that can't answer
• the configuration references a secret and you aren't an organization admin
• the version you picked is already the published one

Each problem names the field it's about, and several can come back at once. Nothing is saved and nothing changes for callers until a publish succeeds.

An agent with nothing published

Creating an agent saves its configuration as version 0.1 and publishes nothing. The editor opens it editable, and Save Configuration keeps revising that same 0.1 draft, so creating an agent and starting to build it are one step. Publishing is a separate action you take when the agent is ready to answer.

Every agent therefore begins with nothing published, and stays there until you publish. An agent in that state can't answer: a call routed to it doesn't connect, and neither does a chat. That makes attaching it to anything pointless, so Tandem says so at the point of attachment rather than after:

• Picking an agent in Phone Numbers or on a SIP trunk, in a chat widget, as a transfer_to_voice_agent destination, or as an agent tool target shows it as not published — can't answer calls, and the option can't be chosen. It stays in the list rather than disappearing, so an agent that's already attached doesn't vanish from the picker holding it.
• The AI Voice Agent workflow node's agent picker says nothing about publish state, and lets you pick any agent. That picker is built on the server, from agent records that don't carry the published pointer.
• An agent's own Phone Numbers card warns when the agent you're editing has nothing published, since there's no option to disable there — the agent is fixed and the rows are numbers.

Over the API a draft can still reference an unpublished agent; nothing checks it until you publish, which is what makes a half-built configuration saveable.

An agent that was already answering calls before your organization moved onto versioning keeps answering: its existing configuration becomes its published version, with nothing for you to do.

Testing a draft before you publish

Call Agent in the editor places a browser preview call against the configuration on screen, including edits you haven't saved. It's the way to hear a draft, and it's unaffected by which version is published. Preview Calls covers what such a call does and doesn't exercise.

There is no way to route a real phone call to a draft. If you need one, publish the draft on an agent that isn't in front of customers.

Limits and defaults

Versioning over the API

Everything above is available over the API. Creating an agent saves its configuration as version 0.1 and publishes nothing, so an integration that creates an agent has to publish a version before that agent can answer. See List an agent's versions for the endpoints and Publish a version for the publish call.

Two consequences matter if you write configurations from your own code.

PUT /v1/agent-media/agents/{agentId} stops accepting a configuration once the agent holds any version at all — a published one or a draft — which, since a create writes a 0.1 draft, means from the moment the agent exists. The only keys it still takes are name and sourceTemplateId, and a body carrying anything else is rejected with 409 config_put_retired without saving. Write the configuration to a draft with PUT /v1/agent-media/agents/{agentId}/versions/{version} and publish it.

POST /v1/agent-media/agents also no longer overwrites. Supplying an agentId that already exists is rejected with 409 create_upsert_retired, whatever versions that agent has: a create writes identity to the agent record and the configuration to a 0.1 draft, so repeating one over a live agent would take its configuration off the record and publish nothing in its place. Edit through the version endpoints instead. A create with no agentId, or with one that is genuinely new, is unaffected.

The changelog entry has the full note.

Troubleshooting

The fields are all greyed out. You're on a published version, which is immutable. Save it as a new draft to make changes. A draft is editable, so this never happens on an agent you have just created.

A version number comes back as already taken. That number is in use. Pick another, or open the existing version and edit it.

Saving a version is refused for the version limit. The agent already holds 20. Delete one first; the published version isn't deletable until you publish a different one.

Publish reports several field errors at once. The draft was written over the API, where a save doesn't check completeness the way the editor's Save does, so the first publish is where they all surface. Fix them and publish again.

Publish reports that a linked agent has no published version. The agent tool's target can't answer. Publish a version of the target agent, then publish this one.

An agent is marked "not published" in a picker. It has no published version, so the option isn't selectable. Publish a version of that agent, then reopen the picker. The one exception is an agent that predates versioning in an organization the rollout hasn't reached yet: it carries no published version and is labelled this way, but it is still answering calls.

Your integration gets 409 config_put_retired. That agent's configuration lives on its version rows, which is true of every agent created since versioning shipped — a publishedVersion of null does not mean the old route still works. Write configuration through PUT /v1/agent-media/agents/{agentId}/versions/{version} and keep the agent PUT for name and sourceTemplateId.

Your integration gets 409 create_upsert_retired. You posted an agentId that already exists. Creating is no longer a way to overwrite one. Write a draft with PUT /v1/agent-media/agents/{agentId}/versions/{version} and publish it.

Next steps