The Staging feature lets you make changes to an agent's configuration in a staging environment before they reach your end-users and agent integrations. Nothing you change in Staging goes live until you publish. You can also revert any previously published changes at any time.This functionality protects end-users from seeing incomplete or broken configurations. Think of Staging as a space where you can experiment, iterate, and collaborate with others freely, and only promote changes to Production when everything is ready.
Make your changes to the agent — update the name, description, knowledge sources, tools, guardrails, or any other configuration. All edits apply to Staging only, allowing you to review and test before propagating them to your published agent.Your staging changes are preserved until you publish them, so you can work across multiple sessions without losing progress.
Working across sessions
You might update the system prompt on Monday, add a new knowledge source on Wednesday, and adjust the guardrails on Friday — all in Staging — and only publish the full set of updates once you're happy with how everything works together.
Before publishing, you can review a side-by-side comparison of what has changed between Staging and Production. The comparison covers:
Agent settings (name, description, model configuration, etc.)
Instructions
Knowledge sources
Tools
Guardrails
Each changed field shows the current Production value alongside the new Staging value, so you can verify everything looks correct before it goes live.
Only differences are shown
If a field is unchanged, it will not appear in the comparison — only the fields that differ between Staging and Production are highlighted. This keeps the review focused and easy to scan, even when your agent has many configuration options.
When you are satisfied with your staging changes, publish them to make them live. Production is updated instantly and a snapshot of the changes is saved to your publish history.:::note Nothing to publish? If Staging is already identical to Production, the publish endpoint is blocked and returns has_changes: false. :::
Review before you publish
Publishing is instant. Once confirmed, changes immediately reflect on the published agent. Always review using the staging diff before proceeding.
Every publish is recorded automatically. Each entry in your publish history shows who published, when, and a summary of what changed. You can browse this history at any time.
Why publish history matters
The publish history is useful for auditing purposes — for instance, if you need to understand who made a particular change and when. It also serves as the foundation for the Revert feature, since each history entry represents a known-good snapshot you can revert to.
If you need to roll back a change or return to an earlier configuration, you can revert any entry in your publish history. This is useful if a newly published configuration causes unexpected behavior. You are not limited to reverting only the most recent publish — you can select any entry from the full history.
Before committing to a revert, you can preview what would change in Staging so there are no surprises. The preview shows the side-by-side diff view — it compares the selected history entry against the current state of Staging, so you can see exactly what will be rolled back before you commit.
Reverting removes the changes introduced by that publish from Staging. Production is not affected immediately. This gives you a chance to review the reverted changes before they go live. Once satisfied, publish to make the revert live in Production.
Method
Endpoint
Description
PUT
/api/v2/agents/{agent_id}/rollback
Removes the changes made at a given change_track_id from the Staging environment. Production is not affected until POST /api/v2/agents/{agent_id}/publish is called.
Production is not immediately affected
Reverting does not immediately update Production. You are always in control of when changes go live.
