Deployment overview and branches

Branches let a team change an agent without replacing the configuration currently serving customers. Every agent starts with Main. Additional branches copy a published version from a parent, begin with no traffic, and give their authors an independent draft and version history.

Read branch state#

Main is the canonical branch. Publishing Main updates the agent's active version pointer. Live means a branch currently receives some production traffic; it does not mean the branch is Main. A protected branch requires an owner or admin for sensitive changes such as publishing. An archived branch is read-only and excluded from active branch selection, but its immutable versions remain available for inspection.

The Branches page also reports whether a branch is Main, up to date with Main, or behind Main; whether it has a draft; its traffic percentage; and recent conversation count. These labels describe different dimensions. For example, a protected branch can be behind Main and still be Live.

Create and manage a branch#

Open the agent's Branches page and choose Create branch. Select a parent version, then provide a name and optional description. The new branch receives a copied immutable version and 0% traffic. Its draft begins separately from drafts on other branches.

From a branch row, authorized users can rename the branch, update its description, protect or unprotect it, archive it, or restore it. Main cannot be renamed or archived. A branch receiving traffic cannot be archived; first move its traffic elsewhere. An archived branch must be restored before any other edit, and a restored branch always returns at 0% traffic.

Use the public branch operations when automating the same lifecycle. The dashboard supplies confirmations and permission explanations; the API returns stable error codes. Neither path silently changes traffic to make an invalid archive succeed.

Permissions, limits, and recovery#

Branch endpoints accept workspace members, then enforce limits for the requested action and branch state:

A member can create a branch. On an active unprotected branch, a member can rename it or update its description, including a Live branch.
Only an owner or admin can protect or unprotect a branch. Members cannot change protection.
Main cannot be archived. A branch receiving traffic cannot be archived by any role. A member can archive or restore an unprotected non-Live branch; an owner or admin can do the same for a protected branch. Restore always returns it at 0% traffic.
Publish, merge, and rebase allow a member only when every participating branch is active, unprotected, and at 0% traffic. Owners and admins may perform those actions on protected or Live branches, but archived branches remain blocked. Merge force is also owner/admin-only.
Revert can copy a historical version into a member's draft on an active target branch. It does not publish. Changing the production traffic distribution is always owner/admin-only.

Protection controls mutations; it is not an access boundary for reading branch history. Live status has action-specific limits: it blocks archive and member publish/merge/rebase, but it does not block a member from renaming or describing an unprotected active branch.

If an action is unavailable, check the row badges before retrying:

For Live, move traffic using traffic and deployment history.
For Archived, restore the branch, then repeat the intended edit.
For Protected, ask an owner or admin to perform the change or remove protection.
For Behind Main, choose merge or rebase based on whether the destination or the working branch should move.

Creating or restoring a branch never deploys it. Publish a valid version, then explicitly assign traffic. Continue with drafts, publishing, and immutable versions.