> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Versioning: Git for Agents, Without the Commands
> Scout versions every change to your agents. Test changes in isolation, promote the best version to production in one click, and roll back instantly.
Agent Versioning is version control built into Scout. Every time you change an agent, Scout captures a new version automatically — so you can experiment freely, test changes without touching production, and roll back the moment something goes wrong. It's the safety net that lets you iterate on live agents with confidence.
* **Automatic versioning** — every edit creates a new version, no manual saves of "v2-final-final" required
* **Version isolation** — test changes without affecting the version your users see
* **One-click promotion** — make any version the production version instantly
* **Instant rollback** — revert to a previous version in seconds
Each version is its own agent ID, and the **active** version is the one designated for production.
## The Problem It Solves
Agent configurations are complex. A single agent ties together prompts, model parameters, database connections, workflows, skills and integrations, permissions, and scheduling. Change one prompt to fix an edge case and you might quietly break three others.
Without version control, teams resort to workarounds: duplicating agents, copy-pasting configs into documents, or simply hoping the last change was an improvement. Agent Versioning replaces all of that with systematic change tracking and one-click rollback — no workarounds needed.
## Demo
## How It Works
Saving an agent captures everything that changed — prompts, model parameters, database connections, workflows, skills and integrations, and scheduling. Each version gets its own unique agent ID.
Older versions stay accessible. You can open them, test them, compare them side by side, and debug — all without affecting the version running in production.
When a version is promoted, it becomes the active version for scheduled runs, Copilot deployments, and manual executions. Everything that points at "the agent" now points at the new version.
Rolling back switches the active version pointer to a previous agent ID. There's no redeployment and no rebuild — the change takes effect immediately.
## Saving Versions
When you save an agent, a split button gives you two choices:
* **Save and Activate** — creates a new version *and* immediately promotes it to production. Use this when you're confident the change is ready for users.
* **Save as Inactive** — creates a new version without promoting it. The version is staged for testing only and production keeps running the current active version.
The split between these two options is what makes safe iteration possible: you can keep saving and testing inactive versions until one is ready, then activate it in a single click.
## Viewing Version History
The version history panel lists every version of an agent. For each one, you can see:
* **Agent ID** — the unique identifier for that version
* **Status** — whether the version is Active or Inactive
* **Created date** — when the version was saved
* **Author** — who made the change
* **Diff** — what changed compared to the previous version
When you open a version that isn't the active one, a banner appears to make clear you're viewing a non-production version.
## Testing Specific Versions
Open the version you want to test and use the **Interact** panel. It tests the exact version you're viewing, so you can validate an inactive version before promoting it.
Target a specific version by using its agent ID directly:
```bash theme={null}
curl -X POST https://api.scoutos.com/agents/{agentId}/interact \
-H "Authorization: Bearer $SCOUT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "message": "Hello" }'
```
Because each version has its own agent ID, you can run automated tests against an inactive version without affecting production traffic.
### Copilot Deployment Versioning
Each Copilot deployment references a specific agent ID, which means you can validate a new version end to end before any user sees it:
Make your changes and choose **Save as Inactive** to create a new version.
Point a test Copilot deployment at the new version's agent ID.
Exercise the test deployment until you're confident the new version behaves correctly.
Activate the new version and update your production deployments to the new agent ID.
## Use Cases
Save each prompt iteration as an inactive version, test it against your validation data, and promote the one that performs best.
Add a new database connection in a fresh version and compare it against the current version before going live.
Run versions in parallel to compare token costs and output quality before switching models.
Revert to a known-good version instantly while you debug the newer one.
## Technical Details
* **Agent IDs** — every version has a unique agent ID (for example, `agent_abc123`). The active version is tracked as metadata on the agent.
* **Version storage** — each version is an immutable snapshot containing the full configuration (as JSON), references to the resources it uses, and metadata such as creator, timestamp, and parent version.
* **Access control** — version history is visible to anyone with access to the agent. Promoting and rolling back require edit permissions.
## Limitations
Version history is retained for **30 days** on standard plans.
* Historical versions can't be edited directly. To change an old version, restore it as a new version and edit that.
## Getting Started
Navigate to the agent you want to change in Scout Studio.
Make your changes — to the prompt, model, integrations, or anything else.
Choose **Save as Inactive** so production keeps running the current version.
Use the Interact panel to test the new version, and compare it against previous versions in the history panel.
Activate the new version once you're confident. If anything looks wrong later, use **Roll back** to return to a previous version.
***
## Next Steps
Manage where your agents are live across Slack channels.
Embed a specific agent version on your website or app.
Trace agent runs and debug behavior across versions.