Agent Versioning

Manage agent versions, promote configurations, and roll back changes with PromptRails' immutable versioning system.

Agent Versioning

PromptRails uses an immutable versioning system for agents. Every configuration change creates a new version, and you can promote any version to be the current active configuration. This enables safe iteration, A/B testing, and instant rollbacks.

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

Config is a typed discriminated union by agent type — SimpleAgentConfig, ChainAgentConfig, MultiAgentConfig, WorkflowAgentConfig, or CompositeAgentConfig. The SDK injects the type discriminator automatically and catches schema mismatches (like prompt_version_id → prompt_id) at compile time instead of runtime.

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.

Version Content

Each version includes:

Linked Prompts

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

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