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. Workflow-scoped tool calls carry an explicit workflowId.
Attach the intended action and account
Section titled “Attach the intended action and account”A direct attachment accepts native integration actions that the catalog marks agentAttachable. Control-flow, data, file, agent, AI and HTTP steps are never attachable; put them 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. Tool changes made through the assistant tools count too. History remains, and the next message uses the saved draft. A failed batch saves nothing.
With an assistant: find the exact name with agent_list:
{ "search": "Support helper", "ownership": "mine" }Note data.agents[].id as <agentId>. Attaching the same action or flow twice fails, so update the existing tool. Read the tools with agent_tool_list:
{ "agentId": "<agentId>" }Search for integrations that publish actions with integration_search:
{ "query": "Slack", "kind": "actions" }Note the selected data.items[].slug as <slug>, then list matching actions with integration_action_list:
{ "query": "send message", "integration": "<slug>" }Note the action’s data.items[].key as <key>. Read its schema with integration_action_get:
{ "integration": "<slug>", "key": "<key>" }List connections with connection_list:
{ "integration": "<slug>" }Every entry is a native integration. An entry that is missing, removed, not an action, or not attachable to agents fails with Registry action not found. Rediscover the pair, or use a workflow for that step. 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, get a connection link with connection_connect_url:
{ "nodeSlug": "<slug>" }Give the user the returned data.url, then re-list after authorization.
Attach the action with agent_tool_action_add, using that connection, requiring approval, and posting requests to Slack through slackRoute. Re-list tools with agent_tool_list.
{ "agentId": "<agentId>", "integration": "<slug>", "action": "<key>", "connectionId": "<connectionId>", "requireConfirmation": true, "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 description set through the assistant tools is stored, but runtime routing uses the provider description instead.
Attach a flow that returns a useful result
Section titled “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 descriptions set through the assistant tools when edited.
With an assistant: call workflow_list:
{ "limit": 100 }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 with flow_list:
{ "workflowId": "<workflowId>" }Note the escalation flow’s data.items[].id as <flowId>, then read the flow with flow_get:
{ "workflowId": "<workflowId>", "flowId": "<flowId>" }Prepare the run inputs, replacing these keys with the matching data.flowInputs[].id values:
{ "<ticketInputId>": "T-104", "<summaryInputId>": "Account-specific policy review requested"}Run the flow on development with run_flow before attaching it, passing that object as inputs. Providers still perform real actions and consume usage.
{ "workflowId": "<workflowId>", "flowId": "<flowId>", "target": "dev", "inputs": { "<ticketInputId>": "T-104", "<summaryInputId>": "Account-specific policy review requested" } }The run must reach terminal success, and data.output must carry every promised value. Preflight does not prove useful results.
Attach the flow with agent_tool_workflow_add, with a description, requiring approval, and posting requests to Slack through slackRoute. Re-list tools with agent_tool_list.
{ "agentId": "<agentId>", "workflowId": "<workflowId>", "flow": "<flowId>", "description": "Use for account-specific escalation after collecting ticket ID and summary; returns the escalation identifier.", "requireConfirmation": true, "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
Section titled “Decide what requires approval”The public app and the assistant tools 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 with agent_conversation_history:
{ "conversationId": "<conversationId>" }Note data.pendingHitlRequests[].requestId as <requestId>, then approve with agent_conversation_approve:
{ "conversationId": "<conversationId>", "requestId": "<requestId>" }To refuse instead, use agent_conversation_deny, optionally including message:
{ "conversationId": "<conversationId>", "requestId": "<requestId>", "message": "Wrong destination" }Approval resumes the turn without waiting for completion. Repeat agent_conversation_history 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. Use last: true for completion, and omit last for approvals and errors.
{ "conversationId": "<conversationId>", "last": true }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
Section titled “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 and change it with agent_tool_update. To rebind the connection:
{ "agentId": "<agentId>", "toolId": "<toolId>", "connectionId": "<connectionId>" }To require approval:
{ "agentId": "<agentId>", "toolId": "<toolId>", "requireConfirmation": true }To also post approval requests to Slack, add "slackRoute": { "connectionId": <slackConnectionId>, "targetType": "channel", "channelId": "<channelId>" }, with optional "approvers": ["<slackUserId>"] inside it for who can answer. To remove the route:
{ "agentId": "<agentId>", "toolId": "<toolId>", "slackRoute": null }To allow calls without approval:
{ "agentId": "<agentId>", "toolId": "<toolId>", "requireConfirmation": false }To detach the tool, use agent_tool_remove:
{ "agentId": "<agentId>", "toolId": "<toolId>" }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.