Publishing an agent

Publishing turns the draft into an immutable version and makes it what Live conversations — and every teammate, if shared — run. It is the one moment agent changes reach users, and it has sharper edges than “save”.

What a version contains

A publish snapshots: name, instructions, tool identities and descriptions, each tool’s approval policy, and the knowledge files. It does not contain: the runtime model (per-conversation), runtime files (rail-scoped, unversioned), or any workflow release — workflow tools always resolve the latest live release at call time.

Preflight first

cai agent publish-preflight <agentId>
cai agent publish <agentId>

Publish refuses when the draft can’t produce a runnable version. The concrete blockers:

• An attached workflow has never been published — there is no live release for the tool to run.
• The tool’s flow is absent from the workflow’s published release.
• A granted integration action no longer exists in the catalog.
• The action’s connection is missing, inactive, owned by someone else, or for a different app.

Preflight reports these as blockers (hasBlockers) before you commit.

Publish is a hard cutover

The moment a publish lands:

• Every existing live conversation is restamped onto the new version.
• Conversations mid-turn are interrupted — the in-flight answer never arrives; each conversation resumes on its own next message, running the new version.
• Every unexecuted approval request expires, including Slack approval cards.

If a live conversation might be mid-approval with a customer, that is the wrong moment to publish.

Recovery is forward-only

Published agent versions cannot be rolled back or re-activated. If a publish was wrong, fix the draft and publish again — the version history is a read-only record, not an undo stack. (Contrast with workflows, where restore is the undo.)

Also remember what publishing does not control: workflow releases and action connections are live bindings that change agent behavior without any agent publish — the full list.

Example prompts

Run publish-preflight on this agent, explain every blocker in plain language, fix what can be fixed, and stop before the actual publish.

Before publishing: list this agent's live conversations and tell me if any has a pending approval that the publish would expire.