Add Agent Tools

Attach an integration action for one app operation. Attach a workflow flow when the task has inputs, processing, and a result. For Support helper, choose a support-channel notification or a Support desk escalation flow, with Require approval. These commands assume no workflow is selected with cai use, so workflow commands include --workflow <workflowId>.

Attach the intended action and account

A direct attachment accepts provider actions only. Put a native registry action in a workflow and attach that flow. Attaching an action does not prefill the channel or message. The agent supplies them when calling the tool.

In the app: open Agents → Support helper → Edit → Add tool → Integration actions. Select integration, connection, and action. Under Approval, choose Require approval. Use Slack approvals to post requests to a channel, then select Add action → Save changes.

Finish Test turns and resolve or deny their requests before saving. A successful save that changes the draft stops Test runtimes. CLI and MCP tool changes count too. History remains, and the next message uses the saved draft. A failed batch saves nothing.

With an assistant: find the exact name:

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

Note data.agents[].id as <agentId>. Attaching the same action or flow twice fails, so update the existing tool. Read the tools, then search for integrations that publish actions:

cai agent tools <agentId> --json
cai integration search "Slack" --actions --json

MCP uses agent_tool_list and integration_search with query: "Slack", kind: "actions".

Note the selected data.items[].slug as <slug>, then list matching actions:

cai integration actions "send message" --integration <slug> --json

MCP uses integration_action_list with query and integration.

Note the action’s data.items[].key as <key>. Read its schema and list connections:

cai integration action --integration <slug> --key <key> --json
cai connection list --integration <slug> --json

MCP uses integration_action_get with integration and key.

Discovery mixes native and provider entries without labeling their source. An entry that is native, missing, removed, or not an action fails with Pipedream action not found. Rediscover the pair, or use a workflow for native actions. Check data.hasMore. Search defaults to 20 results and actions to 50. Narrow the query, or raise --limit to at most 100.

Choose the intended owner’s account with status: "ACTIVE". Note its data.items[].id as <connectionId>. Attachment accepts an inactive connection, but execution and publication reject it. If none is active, connect one:

cai connection connect <slug> --no-open --json

MCP uses connection_connect_url with nodeSlug. Give the user the returned data.url, then re-list after authorization.

Attach the action with that connection, require approval, and post requests to Slack. Re-list tools:

cai agent add-action <agentId> --integration <slug> --action <key> --connection <connectionId> --require-confirmation --slack-connection <slackConnectionId> --slack-channel <channelId> --json
cai agent tools <agentId> --json

MCP uses agent_tool_action_add with connectionId and requireConfirmation: true. To post approvals to Slack, include slackRoute: { connectionId: <slackConnectionId>, targetType: "channel", channelId: "<channelId>" }.

Check action, connection, and requiresConfirmation. Keep data.tools[].id as <toolId>. Generated names are internal, so describe the capability and channel in plain language in Instructions. The app has no description field for a direct action. A CLI or MCP description is stored, but runtime routing uses the provider description instead.

Attach a flow that returns a useful result

Flow inputs become the tool’s arguments. Require a ticket ID and summary, reject blank strings, create one escalation, and map its identifier in Return response. Required text still accepts "". Declaring outputs alone returns no values.

In the app: test the flow, then choose Add tool → My workflows → Support desk → the escalation flow → Settings. Set Description and Require approval. Use Slack approvals to post requests to a channel, then Add tool → Save changes. The description is optional, and blank uses the flow name. The app caps it at 280 characters and truncates longer CLI or MCP descriptions when edited.

With an assistant: list workflows:

cai workflow list --limit 100 --json

The default page size is 25. Check data.hasMore before treating Support desk as absent. Note its data.items[].id as <workflowId>.

List its flows:

cai --workflow <workflowId> flow list --json

Note the escalation flow’s data.items[].id as <flowId>, then read the flow:

cai --workflow <workflowId> flow get <flowId> --json

Create support-escalation-inputs.json, replacing these keys with the matching data.flowInputs[].id values:

{
  "<ticketInputId>": "T-104",
  "<summaryInputId>": "Account-specific policy review requested"
}

Run the flow on development before attaching it. Providers still perform real actions and consume usage.

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

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

The run must reach terminal success, and data.output must carry every promised value. Preflight does not prove useful results.

Attach the flow with a description, require approval, and post requests to Slack. Re-list tools:

cai agent add-workflow <agentId> --workflow-id <workflowId> --flow <flowId> --description "Use for account-specific escalation after collecting ticket ID and summary; returns the escalation identifier." --require-confirmation --slack-connection <slackConnectionId> --slack-channel <channelId> --json
cai agent tools <agentId> --json

MCP uses agent_tool_workflow_add with workflowId, flow, and requireConfirmation: true. To post approvals to Slack, include slackRoute: { connectionId: <slackConnectionId>, targetType: "channel", channelId: "<channelId>" }.

A workflow call first returns pending and workflowExecutionId. Mapped results arrive later. Previews larger than 256 KiB are truncated. When completeness matters, the completion tells the agent to call built-in get_workflow_execution_result before answering.

Test uses development workflows. Live follows published releases, and pinning is unsupported. Publishing a workflow updates every Live agent following it, without another agent publish. A turn or approval already in flight finishes on the previous release before the refresh. Publish intended workflow changes before the agent.

Decide what requires approval

The public app, CLI, and MCP default to Run without approval. Choose deliberately for anything that sends, writes, spends, deletes, changes permissions, contacts customers, or has an ambiguous destination.

In the app: open Agents → Support helper → Test or Live → the pending conversation. Approve only the safe channel ID selected for the test and the exact message Test escalation T-104: account-specific policy review requested. Inspect every displayed value. For a dynamically configured action, the summary redacts sensitive fields, truncates values after 200 characters, and omits entries beyond 24. If a hidden value matters, deny. Deny opens a reason field. Select Deny again to confirm.

With an assistant: use <conversationId> from the Test result and read the history:

cai agent conversation history <conversationId> --json

Note data.pendingHitlRequests[].requestId as <requestId>, then approve:

cai agent conversation approve <conversationId> --request <requestId> --json

MCP uses agent_conversation_approve with requestId. To refuse, use agent_conversation_deny, optionally including message.

To refuse through CLI instead:

cai agent conversation deny <conversationId> --request <requestId> --message "Wrong destination" --json

Approval resumes the turn without waiting for completion. Repeat these reads until data.turnComplete is true, the full history shows another approval, or an error or INTERRUPTED or CLOSED status ends the turn. Do not resend.

cai agent conversation history <conversationId> --last --json
cai agent conversation history <conversationId> --json

MCP uses agent_conversation_history with last: true for completion, and without last for approvals and errors.

Verify the terminal tool result and external effect. Approval is not proof of success.

State	Meaning	Next check
PENDING	Decision needed	Arguments and destination
APPROVED	Authorized, not consumed	Same conversation
DENIED	Refused	Agent’s response
EXECUTED	Approval consumed	Result and actual effect
TIMEOUT	Unusable approval	Whether a new call remains wanted

Approval requests wait without a deadline and survive the agent runtime stopping. Answering later resumes the run. Stop cancels them. A failed Slack delivery leaves the request waiting in the app. Publishing moves Live conversations to the new version and closes their approvals not yet run. An approval for a conversation started in Slack must be resolved in Slack.

Change a tool without redirecting an outstanding call

A direct action uses the owner’s current connection for every user. Rebinding redirects Live immediately, including calls resumed from pending approvals. When the account matters, deny outstanding Live approvals before rebinding. Detachment blocks Live immediately, and publication removes its listing. Removing and re-adding creates a new tool ID, so republish the replacement.

Turning approval on blocks an older published direct action outright until publication carries the new policy. It does not start asking instead. Turning approval off keeps the published requirement until publication.

In the app: the row’s Edit changes connection, approval policy, Slack approvals, or a workflow description. Remove detaches it. Finish with Save changes. To replace an action or flow, remove it and add the new one.

With an assistant: use <toolId> from the tool list. To rebind the connection:

cai agent update-tool <agentId> --tool <toolId> --connection <connectionId> --json

To require approval:

cai agent update-tool <agentId> --tool <toolId> --require-confirmation --json

To also post approval requests to Slack, add --slack-connection <slackConnectionId> --slack-channel <channelId>, with optional repeatable --slack-approver <slackUserId> for who can answer. To remove the route:

cai agent update-tool <agentId> --tool <toolId> --no-slack --json

To allow calls without approval:

cai agent update-tool <agentId> --tool <toolId> --no-confirmation --json

To detach the tool:

cai agent remove-tool <agentId> --tool <toolId> --json

MCP uses agent_tool_update with toolId plus the chosen connectionId or requireConfirmation change, and agent_tool_remove with toolId. Set slackRoute: { connectionId: <slackConnectionId>, targetType: "channel", channelId: "<channelId>" } to post approvals to Slack, or slackRoute: null to remove the route.

An omitted field keeps its value, so a connection-only update preserves approval. Re-list the tools to verify. The in-product builder can attach workflow tools. Direct attachments and changes to existing tools require the app. Next, test tool choice, approval, and results.