Tools and approvals

An agent’s power comes entirely from its tools, and every tool carries two decisions you make: what it may do and whether a human approves each call.

Two kinds of tool

	Integration action	Workflow tool
What it is	One ready operation from a connected app	A flow you built, exposed with a typed input contract
Use when	A single existing operation completes the capability	The capability needs steps, branching, durable state, or a deterministic contract
Runs on	The owner’s selected connection — a live binding	The workflow’s dev head (Test) or latest live release (Live)
Evidence	An action run in the conversation	An action run plus a full workflow execution trace

Prefer the action when one operation is enough; don’t build a one-node workflow around it. Build the workflow when logic, not access, is the point.

cai agent add-action <agentId> --integration slack --action send-message --require-confirmation
cai agent add-workflow <agentId> --workflow <wfId> --flow <flowId> --description "..."
cai agent tools <agentId>
cai agent update-tool <agentId> <toolId> --require-confirmation

Two live-binding facts to internalize (details: Safety): rebinding or revoking an action’s connection changes live behavior immediately, and cai agent remove-tool revokes an action’s live authorization immediately — the visible tool list updates on the next publish.

The approval policy

Any tool can require human approval per call (requiresConfirmation). When a gated tool fires, the agent pauses with the exact tool input shown; the user approves or denies (optionally with a reason), and the turn resumes or the agent adapts.

Decide the policy explicitly for every attached tool. In the app’s wizard and the CLI, new integration actions default to no approval — the platform does not guess which operations are dangerous. The question to ask: what does one bad call cost? Creating a note: nothing — leave it open. Sending an email, deleting a record, spending money: gate it.

What happens at approval time

An approval request is part of a live conversation turn, not a durable work item:

• It blocks the turn until resolved:

cai agent conversation approve <requestId>
cai agent conversation deny <requestId> --reason "wrong recipient"

• It expires rather than waiting forever: if the conversation’s runtime session ends, delivery fails, or the agent is published, pending requests transition to timed-out. Publishing an agent expires every unexecuted approval request on its live conversations — time publishes accordingly.
• Slack-routed approvals can be configured per tool, so approvals land as cards in a Slack channel. For a conversation that lives in Slack, approvals resolve only from the Slack thread — the app shows them read-only.
• Approving executes the call with the input that was shown. Denying returns control to the agent, which sees the denial (and reason) as context.

Designing the tool surface

• Fewer, sharper tools beat many vague ones. Every tool’s description competes for the agent’s routing judgment — the 280-character cap is a feature.
• Match approval friction to blast radius, not to novelty. An agent that asks for approval on everything trains its users to click yes.
• For a shared agent, remember every action runs on your connection: the tool surface you approve is what teammates can do as you. See Sharing with your organization.

Example prompts

Attach the send-email action with approval required, then test it in a Test conversation and show me exactly what the approval request looks like before I approve.

Audit this agent's tools: for each, tell me its approval policy, what one bad call would cost, and whether the policy matches.