Agent versioning provides a robust system for managing changes to your agents over time. Every modification creates an immutable revision, allowing you to track changes, experiment safely, and roll back when needed.

​
Understanding Agent Versioning

When you create or modify an agent, the system automatically creates a new revision containing the complete configuration snapshot at that point in time. This approach ensures:
  • Complete audit trail of all changes
  • Safe experimentation with draft revisions
  • Reliable rollback to previous working versions
  • Consistent run execution tied to specific configurations

​
Key Concepts

A revision is an immutable snapshot of an agent’s configuration at a specific point in time. Each revision includes:
  • Model configuration
  • Goal prompt and instructions
  • Tool settings
  • Input/output schemas
  • All other configuration parameters
  • Published Revision: The “production” version that runs execute against by default
  • Draft Revisions: Unpublished changes that can be tested before promoting to production
In the Console, agents display one of three status indicators to help you understand their current state:
  • Unpublished: The agent exists but doesn’t have any published version yet - you’ll need to publish a revision before it can run in production
  • Published: The agent has a live version that’s ready for production use, with no pending changes waiting to be published
  • Unpublished Changes: The agent has a published version, but you’ve made additional changes that haven’t been published yet
These status indicators are calculated from your agent’s publishing history and recent modifications, making it easy to see at a glance whether your latest changes are live or still in draft.

​
Working with Versions

​
Creating Revisions

Every time you update an agent’s configuration through the API or Console, a new revision is automatically created: 
# Update an agent (creates a new revision)
curl -X PATCH https://api.ag.dev/v0.1/agents/{agentId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goalPrompt": "Updated instructions for the agent",
    "tools": ["web", "news"]
  }'
Updating only the agent’s name or description does not create a new revision. Revisions are created only when configuration changes are made.

​
Publishing Revisions

To make a revision available for production use, you need to publish it:
1

Make your changes

Update your agent’s configuration through the API or Console. This creates a new draft revision.
2

Test the revision

You can run specific revisions before publishing to verify they work as expected:
curl -X POST https://api.ag.dev/v0.1/agents/{agentId}/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revisionId": "{revisionId}",
    "input": { ... }
  }'
3

Publish the revision

Once satisfied, publish the revision to make it the default for all future runs:
curl -X POST https://api.ag.dev/v0.1/agents/{agentId}/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revisionId": "{revisionId}"
  }'

​
Viewing Revision History

You can view all revisions for an agent to understand its evolution:
Navigate to your agent’s details page and click the Versions tab to see:
  • Complete revision history with timestamps
  • Which revision is currently published
  • Quick publish actions for draft revisions

​
Comparing Revisions

To understand what changed between revisions, you can compare them: 
# Compare two revisions
curl "https://api.ag.dev/v0.1/agents/{agentId}/revisions/diff?from={fromRevisionId}&to={toRevisionId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
The response shows property-by-property changes with before/after values.

​
Running Specific Versions

​
Default Behavior

When you create a run without specifying a revision:
  • If the agent has a published revision, that version is used
  • If the agent has no published revision, the run will fail with an error
# Uses the published revision (or fails if none exists)
curl -X POST https://api.ag.dev/v0.1/agents/{agentId}/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "input": { ... } }'

​
Targeting Specific Revisions

You can run any revision, published or not, by specifying its ID: 
# Run a specific revision
curl -X POST https://api.ag.dev/v0.1/agents/{agentId}/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "revisionId": "{revisionId}",
    "input": { ... }
  }'
This is useful for testing draft revisions before publishing them or for running older versions when troubleshooting.

​
Troubleshooting

Cause: No revision has been published for the agentSolution: Publish a revision using the /agents/{id}/publish endpoint or specify a revision ID in your run request
Cause: Changes are in a draft revision that hasn’t been publishedSolution: Publish the latest revision or explicitly specify the revision ID when creating runs