Agent Versioning

Every agent’s config — prompt, tools, voice, language, post-call metrics, and more — is managed as versions. You edit in isolated drafts, publish drafts as new versions, and activate the version you want live. Previous versions are kept so you can compare and restore at any time.

Core Concepts

When you open an older or non-active version, the editor is read-only — the only way to change it is to create a draft from it.

Creating a Draft

Drafts can be forked from either a published version or another draft:

• From the active version — click Create Draft on a read-only version.
• From any older version — open the Version history panel, then New draft next to the version.
• From an existing draft — hover a draft in the Drafts panel and click New draft to fork it.

Once the draft is created, the agent header switches from V1 (Read-only) to Draft #N and every field in the editor becomes editable.

Browsing Versions and Drafts

The version switcher at the top of the editor has two tabs:

Comparing Versions

Use Compare versions to see exactly what changed between any two snapshots — published versions or drafts.

Publishing a Draft

When a draft is ready, click Publish in the top right. The Review Changes dialog shows the diff against the current active version and asks for a label + description.

After publishing, the draft is removed and the new version appears in the Version history. If you chose to activate, it also becomes the new Active entry. The previous active version gets a Restore action.

Restoring an Older Version

Click Restore next to an older version to set it active again. The currently-active version is not deleted — you can swap back any time. Restoring never modifies config; it just changes which version serves live calls.

Managing Versions via API

Every action in the UI is available through the public API.

Full flow — edit, publish, activate

1
import os
2
import requests
3
4
API_KEY = os.environ["SMALLEST_API_KEY"]
5
AGENT_ID = "YOUR_AGENT_ID"
6
BASE = "https://api.smallest.ai/atoms/v1"
7
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
8
9
# 1. Read the active version
10
agent = requests.get(f"{BASE}/agent/{AGENT_ID}", headers=HEADERS).json()
11
active_version_id = agent["data"]["activeVersionId"]
12
13
# 2. Fork a draft from the active version
14
draft = requests.post(
15
    f"{BASE}/agent/{AGENT_ID}/drafts",
16
    headers=HEADERS,
17
    json={"sourceVersionId": active_version_id, "draftName": "tune-prompt"},
18
).json()
19
draft_id = draft["data"]["draftId"]
20
21
# 3. Update fields on the draft (any subset is allowed)
22
requests.patch(
23
    f"{BASE}/agent/{AGENT_ID}/drafts/{draft_id}/config",
24
    headers=HEADERS,
25
    json={
26
        "singlePromptConfig": {
27
            "prompt": "You are a helpful assistant..."
28
        },
29
        "synthesizer": {
30
            "voiceConfig": {"model": "waves_lightning_large", "voiceId": "nyah"},
31
            "speed": 1.2,
32
        },
33
    },
34
).raise_for_status()
35
36
# 4. Publish as a new version and activate it
37
published = requests.post(
38
    f"{BASE}/agent/{AGENT_ID}/drafts/{draft_id}/publish",
39
    headers=HEADERS,
40
    json={"label": "v2 - friendlier prompt", "description": "Softened tone", "activate": True},
41
).json()
42
print("New active version:", published["data"]["version"]["_id"])

Common operations

See the full schema in the API Reference.

Reading active config

GET /agent/{id} returns the agent document with the active version’s resolved config merged under _resolvedConfig:

$
curl -H "Authorization: Bearer $SMALLEST_API_KEY" \
>
  "$BASE/agent/$AGENT_ID" \
>
  | jq '.data | {activeVersionId, prompt: ._resolvedConfig.prompt, tools: ._resolvedConfig.tools, analytics: ._resolvedConfig.postCallAnalyticsConfig}'

Related