Agent versioning and publishing

Use Agent versioning to keep an immutable record of an Agent’s configuration at a point in time, and to return the Agent to one of those snapshots.

How versioning works

When you edit a saved Agent, you work on a draft. Click Save to write your changes to the Agent’s saved configuration and record a draft snapshot.

Publishing records an immutable version snapshot and marks it as the Agent’s published version. Further edits create another draft.

Publishing does not gate what runs. Products, Surfaces, schedules, and every other entry point that names the Agent by ID execute the Agent’s saved configuration, so a save reaches them immediately, whether or not you publish afterwards.

Run a specific version

A request can name the version it wants instead of taking the saved configuration. On POST /v1/dispatch and POST /v1/agents/{agentId}/execute, supply exactly one selector beside the Agent identity:

• agent.versionId runs that immutable version snapshot.
• agent.alias runs whichever version the release alias currently points at. The live alias follows the saved configuration.

A selector runs a stored snapshot, so it cannot be combined with inline definition fields such as model, systemPrompt, or tools. Naming both alias and versionId is rejected, and an alias that does not exist answers 404 rather than falling back to the saved configuration. Selectors are not available for external or Claude Managed Agents.

A conversation binds to the first pointer it runs. A later turn on that same conversationId naming a different version or alias is refused with 409 and code: "session_pointer_mismatch"; start a new conversation for the other pointer.

Version numbers

Runtype assigns an increasing number to each version snapshot. The interface displays labels such as v1 and v2. Saving creates a draft before you publish, so the first published version does not necessarily use v1.

Version entries can include a label, notes, a configuration summary, and a creation time.

Draft and published versions

The following table compares draft and published versions:

View version history

To view version history, follow these steps:

1. Open the Agent.
2. Click More save actions, the arrow beside Save.
3. Click View versions.

The Version History panel lists version labels, status badges, configuration summaries, creation times, and notes when available. The current published version has a live badge. A superseded published version has a previously published badge.

When you have unsaved changes, the panel shows a Current draft entry with an unsaved badge. Publishing a version discards those changes, so save first if you need them.

Load or publish a previous version

Each version has two actions:

• Load retrieves the version’s stored snapshot and confirms it in a notification. It does not change the Agent or the editor.
• Publish makes the version the Agent’s live configuration and marks it as published. Publish is unavailable on the version that is already live.

To return an Agent to an earlier version, follow these steps:

1. In the Agent editor, click More save actions, then click View versions.
2. Find the version that you want to return to.
3. Click Publish beside it.

Publishing writes the version’s configuration back to the Agent and marks the version as published in one operation. The editor then reloads the saved Agent. Products, Surfaces, schedules, and other entry points run the restored configuration right away.

For Runtype and external Agents, the write covers the Agent’s name, description, icon, runtime configuration, capabilities, and external connection configuration recorded in the snapshot. Runtime configuration is replaced rather than merged, so settings added after the version was saved do not stay active accidentally.

Publishing also clears tool attachments that the version did not record: tools, MCP servers, runtime tools, subagent and code mode blocks, and approval settings. A tool that you attached after the version was saved does not survive publishing that version.

A version without a stored configuration cannot be published. The dashboard reports this when you click Publish.

What publishing cannot restore

Publishing restores every recorded field that can be changed atomically. It preserves these fields and reports them in applied and warnings:

• Claude Managed runtime settings and capabilities. Runtype cannot atomically update its database and the hosted Anthropic Agent. Publishing therefore preserves the current runtime configuration, hosted settings, credential custody, and capabilities instead of claiming an unsafe partial synchronization. Update and save the Agent to synchronize a historical hosted definition.
• Capabilities whose backing resource was deleted. If a historical capability refers to a Flow, Agent, or tool that no longer exists, Runtype preserves the current capability set and names the unavailable capability in a warning.
• Fields missing from older snapshots. A historical snapshot without runtime configuration or capabilities preserves the current value and reports that coverage gap.

Publishing an Agent managed in code

When an Agent is managed by ensure, the editor shows a Managed in code badge. Publishing rejects the write by default so it cannot silently detach the Agent from code management. The dashboard opens a confirmation dialog; non-interactive clients must explicitly select overwrite. The next ensure run then detects the change as an external modification. For the conflict options, see Manage agents as code.

Publish from the API

POST /v1/agent-versions/{agentId}/publish atomically applies the stored snapshot to the live Agent and marks that version as published. Send versionId in the request body. The TypeScript SDK exposes the same operation:

1
const result = await client.agentVersions.publish(agentId, versionId)
2
console.log(result.applied, result.warnings, result.lastModifiedSource)

For an Agent managed by code, the default returns 409 with code: "managed_by_code_conflict". After explicit confirmation, use the spelling for your client:

• REST and TypeScript SDK: onConflict: "overwrite"
• CLI: runtype agent-versions publish AGENT_ID --version VERSION_ID --overwrite-managed
• MCP: publish_agent_version with on_conflict: "overwrite"
• Code Mode: { onConflict: "overwrite" }

Always inspect applied and warnings to see exactly which parts of the snapshot were restored.

POST /v1/agents/{id}/publish snapshots the Agent’s current saved configuration as a new published version.

Best practices

Use these practices to manage Agent changes:

• Save small, incremental changes so each draft snapshot is easy to return to.
• Remember that saving is what changes live behavior. Test the Agent before you save, and try a change on a non-production Product before you save it on an Agent that production traffic uses.
• Review conversations and activity after you save.
• To go back to an earlier configuration, click Publish beside that version in Version History, then read the notification for anything the publish could not restore.

Next steps

Continue with these Agent guides:

• Creating and configuring Agents: create and configure Agents
• Manage agents as code: keep Agent definitions in your repository
• Agent tools: configure tool types and delegation