Agent Versioning

Track agent changes and promote versions to production with confidence. Think of it as Git for agents — without the commands.

Overview

Agent Versioning automatically tracks every change to your agents:

• Automatic versioning — Every edit creates a new version
• Version isolation — Test new versions without affecting production
• One-click promotion — Promote to production when ready
• Instant rollback — Revert to previous versions in seconds

Each version is a separate agent ID. The “active” version is simply the one currently designated for production use.

The Problem It Solves

Agent configuration is complex. A single agent might have:

• Base prompt and system instructions
• Model selection and parameters (temperature, top-p, max tokens)
• Integrations with databases, APIs, and external tools
• Workflow definitions and scheduling rules
• Permissions and access controls

A change to any of these can cascade. Without version control, teams resort to workarounds: duplicating agents, copy-pasting configurations, hoping they remembered every parameter.

Agent Versioning gives you systematic change tracking with instant rollback.

How It Works

Version Creation

When you edit an agent and save, Scout can create a new version. This captures changes to:

• Prompts and instructions
• Model selection and parameters
• Database connections and schemas
• Workflow definitions
• Skills and integrations
• Scheduling and triggers

Each version gets its own agent ID and is preserved in the agent’s version history.

Version Isolation

Each version is a separate agent. When you create Version 2, Version 1 remains accessible with its original configuration. You can:

• Test new versions with sample inputs
• Compare outputs between versions side by side
• Debug issues specific to one version

Changes to a new version don’t affect previous versions.

Production Promotion

When a new version is ready, promote it with one click. The promoted version becomes the active version for:

• Scheduled runs
• Copilot deployments
• Manual executions

Previous versions remain in history for rollback.

Instant Rollback

If a promoted version causes issues, roll back in seconds. No redeployment required — Scout simply switches the active version pointer to a previous agent ID.

Demo

Saving Versions

When editing an agent, the split button gives you options:

• Save and Activate — Creates a new version and immediately promotes it (affects production)
• Save as Inactive — Creates a new version without promoting (staging only)

Use Save as Inactive to draft and test changes before promoting to production.

Viewing Version History

The version history panel shows each version with:

• Agent ID
• Status (Active/Inactive)
• Created date
• Author
• Diff showing what changed

When viewing a non-active version, a banner displays which version you’re viewing.

Testing Specific Versions

In Studio

Each version has its own agent ID. When viewing a specific version in the editor, the Interact panel tests that version directly.

Via API

Since each version is its own agent, simply use the specific agent ID in your API calls:

POST /agents/{agentId}/interact
{
  "message": "Hello"
}

Use the active version’s agent ID for production traffic, or test with an inactive version’s agent ID before promoting.

Copilot Deployments

Each Copilot deployment references a specific agent ID. To test changes before going live:

1. Save changes as a new version (inactive)
2. Create a test Copilot deployment pointing to the new version’s agent ID
3. Validate behavior
4. Promote the version and update production deployments

Use Cases

Iterative Prompt Development

Refine prompts with each iteration creating a new version. Test against validation data, compare outputs, and promote the best-performing version.

Integration Testing

Add a new database connection — a new version is created automatically. Test queries that exercise both databases. Compare the new version against the old to isolate issues.

Model Migration

Switch models or test new parameters. Run both versions in parallel, compare token costs and response quality, and make data-driven decisions.

Production Rollback

A newly promoted version causing issues? Roll back in seconds. The agent resumes normal operation while you debug in the newer version.

Technical Details

Agent IDs

Each version has a unique agent ID (e.g., agent_abc123). The “active” version is tracked separately as metadata — no special API parameters needed.

Version Storage

Versions are stored as immutable snapshots:

• Complete agent configuration (JSON)
• References to connected resources
• Metadata (creator, timestamp, parent version)

Access Control

• Version history visible to all team members with agent access
• Promotion and rollback require edit permissions

Limitations

• Version history retained for 30 days on standard plans
• Can’t edit historical versions — restore as a new version instead

Getting Started

1. Open any agent in Scout
2. Edit the configuration
3. Choose Save as Inactive to create a new version
4. Test the new version
5. Compare outputs with previous versions
6. Promote to production when ready

If something goes wrong, click Roll back to restore the previous version.

See PRO-6878  for implementation details.