Publish and Share Agents

Publish the tested draft, then choose its audience in Share settings. Publication creates a version holding the agent’s name, instructions, tools, approval policies, and Reference files. Sharing grants use, not editing. Publishing preserves enabled state, visibility, and individual grants. A paused agent stays paused, and an already-shared audience receives the update immediately. Review existing access before publishing.

Release the intended workflow dependencies

An attached Support desk flow must exist in a published workflow release. These commands assume no workflow is pinned, so workflow commands show --workflow <workflowId>.

With an assistant: find the exact Support helper match:

cai agent list --search "Support helper" --ownership mine --json

Note its id in data.agents as <agentId>, then list its tools:

cai agent tools <agentId> --json

MCP uses agent_list, then agent_tool_list with agentId. If Support desk is attached, note its workflowId and flowId in data.tools as <workflowId> and <flowId>. Read that workflow’s release state, validity, and triggers:

cai --workflow <workflowId> workflow status --json
cai --workflow <workflowId> workflow validate --json
cai --workflow <workflowId> trigger list --json

MCP uses workflow_status, workflow_validate, and trigger_list, each with workflowId. If the intended live release already exists, skip workflow publication. Otherwise reuse support-escalation-inputs.json from Attach Agent Tools, with ticket T-104 and summary Account-specific policy review requested. Exercise every relevant subflow path, and verify terminal results and promised return values. A development call has real provider effects and consumes usage, so use the approved test destination.

cai --workflow <workflowId> run flow <flowId> --target dev --inputs support-escalation-inputs.json --json

MCP uses run_flow with workflowId, flowId, target: "dev", and parsed inputs.

Review every enabled trigger, because publishing activates Live dispatch. Armed Test events let one real event run in both development and Live. Disarm them, or approve dual dispatch explicitly. Recovery with --acknowledge-dual-dispatch and --acknowledge-validation-errors is explained in workflow publication.

In the app: open Workflows → Support desk → Dev → Publish. The assistant equivalent is:

cai --workflow <workflowId> workflow publish --name "Support desk release" --json
cai --workflow <workflowId> workflow status --json

MCP uses workflow_publish with workflowId and name. If browser-approval polling is interrupted, note the reported approvalId. The CLI calls this argument <id>. Run cai approval resume <id> --json, or approval_resume with approvalId through MCP. Do not publish again.

Publishing updates every Live agent following that workflow, without another agent publish. An idle session refreshes immediately. A turn in flight or a pending approval can finish on the previous release. If you see agent_session_refresh_failed, verify in a fresh Live conversation.

Check what would block publication

In the app: open Agents → Support helper → Test → Publish. For an unchanged draft, Publish is disabled and reads No unpublished changes. The dialog’s publish button stays disabled while checks are loading, unavailable, or blocked.

With an assistant: read the agent, then run the same checks:

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

MCP uses agent_get and agent_publish_preflight with agentId. Check data.hasUnpublishedChanges from agent get. If it is false, stop. Otherwise the CLI and MCP create an identical version and repeat the Live cutover.

Blocker	Correction
Workflow missing or unpublished	Remove the unintended tool, or publish the dependency.
Published workflow malformed, attached flow absent, or no starting action	Fix the flow and publish its workflow.
Direct action unavailable	Attach an available provider action.
Connection missing, inactive, mismatched, or not owner-owned	Select an active matching owner connection.

Preflight checks attached actions and workflow entry flows. It does not validate subflows recursively, and it does not prove returned values. Unpublished workflow changes alone do not block it. Compare Live’s release with Test evidence. A nonblocking schema_tier_changed diagnostic means configurable inputs changed, so recheck the arguments. Publishing refreshes the cached schema tier.

Publish the tested draft

Publication moves existing Live conversations to the new version. It expires their pending requests and requests approved but not yet run, and it stops active Live runtimes. Test conversations and approvals are untouched. Resolve Live approvals first, because expiry does not authorize repeating an action.

In the app: enter an optional Publish note, then select Publish agent. A note allows 280 characters. Whitespace-only input becomes no note.

With an assistant: publish, then list the versions:

cai agent publish <agentId> --name "Support helper launch" --json
cai agent versions <agentId> --json

MCP uses agent_publish with agentId and name, then agent_version_list with agentId. If the result is uncertain, reread the agent and its versions before retrying. A cleanup failure does not undo the committed release.

History and conversation models are preserved. Reference content is frozen, and Runtime files remain mutable. A direct action’s identity and approval policy are versioned, but its connection and authorization stay live. Rebinding redirects calls immediately. Revocation or detachment can block Live without publication.

Choose who can use Support helper

Shared users use the owner’s connected accounts and the organization’s usage pool. They cannot edit the agent or start owner-only Test.

In the app: open Live → Access → People & sharing → Share settings. Choose Anyone in the organization or Only me and people invited, then Save settings. Under the second option, where Specific people is available, Add teammate grants access immediately and attempts an email. A failed email does not undo the access. Organization visibility sends no broadcast email. An individual removal applies immediately.

With an assistant: open the agent to the organization, then reread it:

cai agent visibility <agentId> --value organization --json
cai agent get <agentId> --json

MCP uses agent_visibility_set with agentId and value: "organization". Individual grants are app-only. Organization visibility requires publication. Switching to private preserves explicit grants and stops every active Live and Test runtime. Removing someone’s last access source stops everyone’s runtimes too, and expires requests not yet run, so finish turns and approvals first. When sharing and organization collaboration are both enabled, organization administrators keep use access. Review the listed people separately.

Verify Live and repair the draft

In the app: start fresh Live conversations using the model recorded in Test. Repeat the policy question and authorized safe tool request below. Have an intended teammate check access from their account.

With an assistant: reuse Test’s claude-sonnet-5 model. For an attached notification action, use the selected safe channel ID as <channelId>. Approving authorizes a real provider call and consumes usage, so verify its result and destination.

cai agent test <agentId> --live --model claude-sonnet-5 --message "What should I include when escalating ticket T-104?" --json
cai agent test <agentId> --live --model claude-sonnet-5 --message "Send exactly this to channel <channelId>: Test escalation T-104: account-specific policy review requested" --json

MCP uses agent_test with agentId, rail: "live", model, and message. If the attached capability is Support desk, replace the second message with the tested request: Escalate ticket T-104 with summary: Account-specific policy review requested. Use only the safe destination configured for that test.

Note data.conversation.id. When approval or a timeout interrupts the wait, take the conversation ID from error.message instead. Then follow the history and approval procedure. Check the returned model against Test. After approval, wait for a terminal result without resending. Verify the policy answer, the adopted version, the tool result, the external effect, and any expected Live record. Test and Live use different workflow releases and stores.

To stop Live, choose Edit → name menu → Pause agent and confirm, or run cai agent update <agentId> --disabled --json. Pausing stops active Live and Test runtimes, auto-denies pending approvals, and expires requests approved but not yet run. The owner can start another Test turn afterward. Resume agent, or cai agent update <agentId> --enabled --json, restores the same version and audience. MCP uses agent_set_enabled with agentId and enabled: false or true. There is no public rollback to an earlier agent version. Fix the draft, test it, and publish again. The in-product builder hands agent testing, publishing, and sharing to the owner in the app.