Skip to main content
Once an Agent runs on a schedule, a trigger, or a Queue, its AOP is production code — and the most common way teams break a working Agent is editing it in place “just to tweak one line”. This page covers the safe loop: fork a draft, test it on real work, make it active deliberately, and roll back without fear. For pre-production testing of a brand-new Agent, start with Test Safely Before Going Live; this page is about Agents that are already live.

​
The One Rule: Don’t Type into the Active Revision

An Agent’s configuration lives in revisions, in one of three states: exactly one Active revision (the one schedules, triggers, Queues, and API starts use), any number of drafts, and the inactive history of everything that was active before. The trap: edits save to whichever revision you have selected — including the Active one. Selecting the Active revision and typing into the AOP box changes what the very next scheduled Run executes. No draft is forked for you, and there is no undo other than rolling back to an older revision. So make the fork explicit:

Create a draft

Open the revision picker in the builder header and choose New Revision. The draft starts as an exact copy of the revision you branched from — Connections, Files, Skills, and evaluation criteria included — and is labeled with a Draft badge. Production keeps running the Active revision, untouched.

Edit the draft

Make your changes there. The banner reading “Draft mode — changes here won’t affect your current active agent’s revision” confirms you’re in the right place.

Test it on real work

With the draft selected, use Test this Agent in the builder’s Current Run tab. The test Run executes the draft’s AOP with real Connections — same access rules as any Run — while scheduled and triggered Runs continue on the Active revision. Draft Runs can only be started from the builder; schedules, triggers, and the API always execute the Active revision.

Make it active

When the draft holds up — ideally across a happy-path Case, an edge case, and a failure case — click Make Active. The activation dialog asks for a revision name and a short description (pre-filled from the diff against the current Active revision) — keep them meaningful, they are what your team sees in the revision list. The previous Active revision becomes inactive history; nothing is deleted.
Test drafts against real inputs, not toy ones. Pick a recent Run that went wrong, feed the draft the same input, and check the new behavior — then check that a Run which used to work still does. The test plan template is reusable here in miniature.

​
What Switches Over When You Click Make Active

Activation is instant, and different surfaces pick it up differently: Two consequences worth planning around:
  • A backlog is a test set you didn’t choose. If a Queue has fifty pending Cases when you activate, all fifty run the new revision. For a risky change, activate when the backlog is small, then watch the first Cases through.
  • If your change reroutes Queues, check the trigger. When the newly active revision no longer consumes the Queue that the Agent’s Case trigger points at, that trigger is switched off rather than left firing into nothing — verify the Schedule & Trigger tab after activating a change that touches Queue wiring.

​
Let Evaluations Judge the Change

Every Revision carries its own set of Agent specific evaluations derived from its AOP, copied forward when you fork a draft and regenerated only when the success criteria genuinely change. That makes the Evaluations tab your before/after instrument: it shows issue rates and a per-criterion breakdown, and the revision picker on the tab scopes them to a specific revision — note the numbers before activating, then watch the first day of Runs on the new revision. A change that “reads better” but doubles Medium-severity issues is a change to roll back. Rolling back is the same motion as promoting: open the revision picker, select the last known-good revision (the banner will say you are viewing an inactive revision), and click Make Active. It keeps its original revision number, and the experiment stays in history for the post-mortem. One thing rollback does not restore: a Case trigger that an earlier activation switched off stays off — if the revision you rolled back to consumes that Queue, re-enable the trigger on the Schedule & Trigger tab.
Revisions are listed by number, name, creator, and date — the description you write at activation is what makes the list navigable later. Before a risky activation, note which revision is the known-good one — rollback under pressure shouldn’t start with archaeology.

Agent Versions

The full revision reference: history, selection, and states.

Test Safely Before Going Live

The pre-production test plan, mocking patterns, and checklist.

Writing Effective AOPs

What to change when a Run goes wrong — usually the AOP.

Make Every Run Auditable

Evaluations as the measuring stick for every change.