Planned Feature — Coming Soon

🚧 This feature is not yet released. The documentation below describes planned behavior and may change before launch.

Versioning

Every change to an agent's configuration creates an immutable revision. This lets you track changes, test new versions safely, and roll back instantly.

How Versioning Works

v1 (Published)  →  v2 (Draft)  →  v2 (Published)  →  v3 (Draft)
    │                                    │
    └── Production traffic ──────────────┘

When you update an agent, a new draft revision is created. The published version continues serving production runs until you explicitly publish the new revision.

Revision States

State	Description
Unpublished	Agent has never been published. Only testable via explicit revision ID
Published	Active production version. All runs use this revision by default
Unpublished Changes	Published agent with draft edits. Previous version remains active

Listing Revisions

revisions = client.agents.list_revisions(agent_id="agent_abc123")

for rev in revisions:
    print(f"Revision {rev.id} - {rev.status} - {rev.created_at}")

Comparing Revisions

View what changed between two revisions:

diff = client.agents.get_revision_diff(
    agent_id="agent_abc123",
    revision_id="rev_v2"
)

print(diff)
# {
#   "goal": {
#     "old": "Research a topic and summarize.",
#     "new": "Research a topic, verify claims, and produce a sourced summary."
#   },
#   "tools": {
#     "added": ["browse_website"],
#     "removed": []
#   }
# }

Testing a Specific Revision

Run against a draft revision before publishing:

# Test the draft revision
test_run = client.runs.create(
    agent_id="agent_abc123",
    revision_id="rev_draft_v3",
    input={"topic": "test query"}
)

result = client.runs.wait(test_run.id)

# Check results before publishing
if result_looks_good(result):
    client.agents.publish(
        agent_id="agent_abc123",
        revision_id="rev_draft_v3"
    )

Publishing a Revision

client.agents.publish(
    agent_id="agent_abc123",
    revision_id="rev_draft_v3"
)

After publishing:

• All new runs use the published revision
• In-progress runs continue with the revision they started with
• The previous published version is preserved in revision history

Rolling Back

To roll back, simply re-publish a previous revision:

# List revisions to find the one you want
revisions = client.agents.list_revisions(agent_id="agent_abc123")

# Re-publish a previous version
client.agents.publish(
    agent_id="agent_abc123",
    revision_id="rev_v1"  # previous stable version
)

Best Practices

1. Test before publishing — Always run a few test executions with the draft revision before promoting to production.

2. Use descriptive updates — When updating an agent, make purposeful changes so revision diffs are meaningful.

3. Monitor after publishing — Watch the first few production runs after publishing a new revision to catch regressions early.

4. Keep working versions — Don't delete recent revisions in case you need to roll back.

Next Steps

• Agents — core agent configuration
• Runs — executing agent tasks