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

# Publishing and versions

> How the mutable draft graph becomes an immutable, numbered version, and how a published version pins live traffic.

Every agent has one mutable graph, the **draft**, and a series of immutable, numbered **published versions**. Publishing is the whole of shipping an agent: there is nothing to build and nothing to roll out. The shared engine loads an agent and version straight from the database on each turn.

## The draft

The builder always edits the draft. The draft is never a numbered version, and it keeps that identity forever; publishing does not create a fresh draft afterward. There is one draft, and you keep editing it.

In APIs, the draft is addressed by the string `draft`. (Internally it is stored as the integer `0` so ordering and indexes stay simple, but that sentinel is never exposed as a product version.)

## Publishing

Publishing copies the **reachable** draft into the next positive integer (`1`, `2`, and so on). Only the part of the draft reachable from the entrypoint is copied, so an orphaned node you have not wired in does not ship. Published rows are immutable: you never edit a version, you publish a new one.

```mermaid theme={null}
flowchart LR
    D["draft<br/>(mutable)"] -->|publish| V1["version 1<br/>(immutable)"]
    D -->|publish| V2["version 2<br/>(immutable)"]
    V1 -.->|restore| D
    V2 -.->|restore| D
```

Each publish takes a short label (required) and an optional description, and returns the new version number.

<Steps>
  <Step title="Open the agent">
    In the dashboard, open the agent you want to ship.
  </Step>

  <Step title="Publish">
    Use **Publish**, give the version a short label, and confirm. You can also publish over the API or the `publish_agent` MCP tool.
  </Step>

  <Step title="Point traffic at it">
    The new version is immediately loadable by the engine. Send it chat traffic, or map a phone number to it.
  </Step>
</Steps>

## How a version pins traffic

Each node versions independently, but the **entrypoint version pins the whole reachable graph**. A published `agent_swap` names its target as `(target_key, target_version)`, so a handoff always lands on the exact node version it was published against.

That means later draft edits, and even later publishes, cannot change a graph that is already serving traffic. Once callers are on version `1`, version `1` cannot move under them.

## Selecting a version

APIs, MCP tools, and engine turns accept either `draft` or a published positive integer.

* The [public invoke endpoint](/api/agents/invoke) requires a published positive integer, not `draft`.
* A [phone number](/run/voice) either follows the newest published version or pins an explicit entrypoint version.
* The dashboard [Conversation](/run/chat) talks to your published agent; the builder additionally lets you chat the draft to test unpublished changes.

## Restore

Restore copies a published revision back over the draft, one node or the whole reachable graph. It edits the draft like any other change; it does not rewrite history. The next publish bumps to a new positive integer as usual.

<Note>
  Agent-level forking and branch merges are intentionally not offered yet. The one draft plus immutable numbered versions is the whole model for now.
</Note>

## No deploy step

Publishing is the entire shipping operation. Agents do not deploy to per-agent compute. The shared engine loads `(agent, version)` from the database on each turn, so a freshly published version is live the moment it is written. See [Chat](/run/chat) and [Voice](/run/voice).