Skip to main content
An agent version in the Brilo API works like a branch in git. Each version has a name, at most one unpublished draft, and a history of commits. Exactly one version is live, and inbound calls run its latest commit. Drafts are never heard by callers, so you can change freely and publish when ready.

​
What it is

An agent version is a named line of settings for one agent, such as “main” or “Holiday hours”. Each version holds three kinds of thing:
  • Commits. Every publish adds a commit, a full copy of the settings at that moment. The newest commit is what the version runs. Older commits stay in its history.
  • A draft. Changes you have written but not published. A version has one draft at most.
  • Everything the agent uses. A commit holds the greeting and instructions, and also actions, knowledge bases, workflows and every setting made in the dashboard.
One version is live. Inbound calls, demo links and calls you place all run the live version’s newest commit, chosen at the start of each call.

​
When you would use it

Agent versions help whenever a change should be checked before callers hear it:
  • A small fix. Update the live version, check the draft, publish. Two calls.
  • A bigger change. Start a new version from the live one, change it over several steps, then make it live in one call. Switching back is one call too.
  • Undoing a change. Restore an earlier commit from the version’s history.

​
How it works

The Brilo API offers one route for each step of that cycle. The table lists them with their MCP tools. PATCH /v1/agents/{id} and POST /v1/agents/{id}/publish are shortcuts for the live version, so a simple change never needs a version id. A draft starts as a copy of the version’s newest commit, with everything it holds. A change then touches only the fields you send. Publishing on the live version reaches callers on their next call, and the commit it replaces moves to history. Publishing on any other version changes nothing for callers until that version goes live.

​
Bring back an earlier commit

Agent versions keep every commit, so an earlier one can come back. restore with a commit_id from the version’s history makes a new commit with exactly what the earlier one held, including actions and knowledge bases set in the dashboard. History is never rewritten: the commit you replaced stays in history too, so a restore can be undone the same way. A version with a draft is refused with 409 draft_pending unless you send discard_draft: true, so unpublished work is never thrown away by accident.

​
Safe to retry

Every Agents API verb is safe to repeat. Publishing with no draft, making the live version live, restoring the newest commit and discarding a missing draft each return 200 with the object unchanged and a code in warnings, never a second effect. Writes that send a revision as If-Match (or if_revision over MCP) are refused with 409 stale_revision if the object changed since you read it.

​
What else you can do here

​
FAQ

No. Creating an agent version copies another version’s newest commit and leaves the live version alone. Callers hear the new version only after you call go_live on it. Until then you can change, publish and test it without any caller noticing.
Only if you discard the draft. A restore on an agent version with a draft returns 409 draft_pending, so unpublished work is never lost silently. Publish the draft first, or send discard_draft: true once the person you work for agrees to lose it.
An agent version needs at least one commit before it can go live, so a version that was never published returns 409 version_has_no_commit. While an A/B test is running, going live returns 409 ab_test_active; end the test in the dashboard first.
The live agent version cannot be deleted, because callers would have nothing to reach. The Brilo API returns 409 version_is_live. Make another version live first, then delete this one. A version in a running A/B test is refused with ab_test_active.
No. A/B tests between agent versions are set up and ended in the Brilo dashboard. While one is running, API changes that would disturb it, such as publishing a version in the test or going live, return 409 ab_test_active. A call you place during a test may use either version.
Edit the live version for small changes you can check in one go: the draft is invisible to callers until you publish. Start a new version for larger work, or when you want to switch back and forth, because going live and going back are one call each.