Agent Versioning

Ship agent changes safely by saving versions, promoting the right one, and rolling back when behavior gets worse.

PromptRails keeps agent versions immutable. Instead of editing production behavior in place, you create a new version, test it, and promote it when it is ready. If the change misbehaves, promote an older version back to current.

PromptRails Studio showing the agent Version Control panel with saved versions — Agent version history lives inside Studio. Open Version Control to see the current snapshot, saved versions, change counts, restore actions, and compare-to-current controls next to the live agent configuration.

How Versioning Works

Each agent has one or more versions. A version captures the complete execution configuration at a point in time:

Configuration object (system prompt, model, temperature, tools, etc.)
Input and output schemas
Linked prompt versions (with roles and sort order)
Version identifier (e.g., v1, v2, v3)
Version message (release notes)

Versions are immutable once created. To change an agent's behavior, you create a new version rather than modifying an existing one.

Current Version

Exactly one version per agent is marked as is_current = true. When an agent is executed without specifying a version, the current version is used. The current version is what API consumers and chat sessions interact with by default.

Creating a Version

When you create a version from an SDK, use the config type that matches the agent: simple, chain, multi-agent, workflow, or composite. The SDK validates the shape before the request is sent.

Technical detailsCreate, promote, and roll back versions with SDKs

Python SDK

from promptrails import SimpleAgentConfig
 
version = client.agents.create_version(
    agent_id="your-agent-id",
    version="1.0.0",
    config=SimpleAgentConfig(
        prompt_id="your-prompt-id",
        temperature=0.7,
        max_tokens=1024,
        approval_required=False,
    ),
    input_schema={
        "type": "object",
        "properties": {
            "message": {"type": "string"}
        },
        "required": ["message"]
    },
    message="Initial version",
)
 
print(f"Version created: {version.version}")

JavaScript SDK

import { SimpleAgentConfig } from '@promptrails/sdk'
 
const simple: SimpleAgentConfig = {
  type: 'simple',
  prompt_id: 'your-prompt-id',
  temperature: 0.7,
  max_tokens: 1024,
  approval_required: false,
}
 
const version = await client.agents.createVersion('your-agent-id', {
  version: '1.0.0',
  config: simple,
  input_schema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
    },
    required: ['message'],
  },
  message: 'Initial version',
})
 
console.log(`Version created: ${version.data.version}`)

Go SDK

simple := promptrails.SimpleAgentConfig{
    PromptID:    "your-prompt-id",
    Temperature: &temperature,
    MaxTokens:   1024,
}
 
version, err := client.Agents.CreateVersion(ctx, "your-agent-id", &promptrails.CreateVersionParams{
    Version: "1.0.0",
    Config:  simple,
    Message: "Initial version",
})

For chain, multi-agent, workflow, and composite configs see the Linked Prompts section below.

Promoting a Version

Promoting a version sets it as the current active configuration for the agent. The previously current version is demoted automatically.

Python SDK

client.agents.promote_version(
    agent_id="your-agent-id",
    version_id="version-id-to-promote"
)

JavaScript SDK

await client.agents.promoteVersion('your-agent-id', 'version-id-to-promote')

After promotion, all new executions (unless a specific version is requested) will use the newly promoted version.

Version History

List all versions of an agent to review the change history:

versions = client.agents.list_versions(agent_id="your-agent-id")
 
for v in versions["data"]:
    current = " (current)" if v["is_current"] else ""
    print(f"{v['version']}{current} - {v['message']} - {v['created_at']}")

Rolling Back

To roll back to a previous version, simply promote it:

# List versions to find the one to roll back to
versions = client.agents.list_versions(agent_id="your-agent-id")
 
# Promote the previous version
previous_version = versions["data"][1]  # second most recent
client.agents.promote_version(
    agent_id="your-agent-id",
    version_id=previous_version["id"]
)
 
print(f"Rolled back to {previous_version['version']}")

Rollbacks are instant because versions are immutable -- there is no rebuild or redeployment step.

Technical detailsVersion payload details

Version Content

Each version includes:

Field	Type	Description
`id`	KSUID	Unique version identifier
`agent_id`	KSUID	Parent agent ID
`version`	string	Version label (e.g., `v1`, `v2`)
`config`	JSON	Complete execution configuration
`input_schema`	JSON	Input validation schema
`output_schema`	JSON	Output structure schema
`is_current`	boolean	Whether this is the active version
`message`	string	Version message / release notes
`created_at`	timestamp	When the version was created
`prompts`	array	Linked prompt versions with roles and sort order

Linked Prompts

Chain, multi-agent, workflow, and composite configs reference prompts through a PromptLink:

Field	Description
`prompt_id`	The prompt to use. Execution auto-follows the prompt's current version — you don't pin a specific prompt version.
`role`	The role of the prompt in the agent (e.g., `main`, `writer`, `critic`)
`sort_order`	Execution order for chain-type agents

Auto-follow means promoting a new prompt version instantly changes the behaviour of every agent linked to that prompt — no agent version bump required. If you want deterministic, pinned behaviour, cut a new prompt (rather than a new version) and switch the agent to link to it.

Chain example

from promptrails import ChainAgentConfig, PromptLink
 
chain = ChainAgentConfig(
    prompt_ids=[
        PromptLink(prompt_id="researcher-prompt-id", role="research", sort_order=0),
        PromptLink(prompt_id="writer-prompt-id",     role="write",    sort_order=1),
    ],
)
 
client.agents.create_version(agent_id="your-agent-id", version="1.0.0", config=chain)

Breaking change (SDK v0.3). The old opaque config: Dict[str, Any] / Record<string, unknown> / map[string]any is gone. The config JSON key prompt_ids[].prompt_version_id was renamed to prompt_ids[].prompt_id. Typed SDK callers don't need to touch anything — the SDK emits the right shape.

Best Practices

Always include a version message describing what changed and why
Test new versions by executing them directly (by version ID) before promoting
Keep previous versions as they serve as an audit trail and enable instant rollbacks
Use input/output schemas to catch breaking changes early
Coordinate prompt and agent versions -- when updating prompts, create a new agent version that links to the new prompt versions