Check Resource Dependencies

What will a workflow change affect? Read its dependency map, which lists attached agents, calling workflows, connections, and triggers. Check draft and Live separately. Removing a draft tool leaves its published attachment in place until the agent is published again.

This example continues Support helper and its Support desk tool. Otherwise, substitute an existing owned agent and workflow. Commands assume no workflow pinned with cai use, so each scoped command supplies --workflow <workflowId>.

Find callers and bound accounts

In the app: open Agents → Support helper → Edit → Tools and inspect the workflow tool. Deletion dialogs list draft attachments, but they omit attachments found only in Live. Those Live-only attachments still block deletion. There is no main-menu Dependencies screen.

With an assistant: start by finding the agent and the workflow.

cai agent list --search "Support helper" --ownership mine --json
cai workflow list --limit 100 --json

MCP uses agent_list with search and ownership, and workflow_list with limit.

Search matches substrings, so select one exact displayed-name match. If several match, have the owner choose the ID. Note the selected data.agents[].id as <agentId> and data.items[].id as <workflowId>.

Now read the agent’s tools and the two dependency maps.

cai agent tools <agentId> --json
cai deps --workflow <workflowId> --json
cai deps --account --workflow <workflowId> --json

MCP uses agent_tool_list with string agentId, and dependency_map with string workflowId. Omit workflowId for the account map.

Even --account needs workflow context in the CLI. The account map covers your owned resources, not every organization resource. Read both sides of each relationship:

Relationship	Draft field	Live field
Agent attachments	draftAttachment	liveAttachment
Calling workflows	draftReference	liveReference
Connections	draftUsage	liveUsage
Triggers	draftEnabled	liveEnabled

In the account map, draft and live contain agent directActionConnectionIds and workflow connectionIds. These describe saved configuration, not provider health. Chat in Slack connections are absent from the map. Inspect Slack settings separately before deleting a connection.

Change contracts without deleting the flow

Edit existing inputs and outputs and update the callers. Reread renamed input bindings and output keys. Deleting a flow removes its development contract, nodes, and targeted trigger canvases, and clears local subflow references. Agent usage is a warning, not a block. You can test changes immediately, and Live changes when you publish the workflow.

For intentional removal, use Workflows → Support desk → Dev → the flow’s menu → Delete, then confirm Delete. With an assistant, discover the flow and save a checkpoint first:

cai flow list --workflow <workflowId> --json
cai workflow save --workflow <workflowId> --name "Before removing escalation flow" --json

MCP uses flow_list with workflowId, and workflow_state_save with workflowId and name.

Note the intended data.flows[].id as <flowId>. Keep data.headStateId for definition recovery, subject to restore access. The deletion below changes development immediately and takes no confirmation parameter.

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

MCP uses flow_delete with workflowId and flowId.

Confirm the flow is absent, and reread dependencies before publishing. To repoint an agent tool, remove the stale tool as below, then attach its replacement with cai agent add-workflow. update-tool cannot change a tool’s workflow or flow.

Detach agents before deleting the workflow

Deletion is refused while any agent draft or current published version includes the workflow. --force is deprecated and ignored. Other calling workflows do not block deletion. A refusal lists the detach and publish commands for each agent. Do not use deletion as a dependency probe, because it proceeds as soon as nothing blocks it.

In the app: open Agents → Support helper → Edit → Tools, hover the intended workflow tool, choose its trash icon (Remove), then Save changes. For a Live attachment, leave Edit and switch to Test. Review the whole draft, then choose Publish → Publish agent.

With an assistant: note the workflow tool’s data.tools[].id from the earlier list as <toolId>. Remove it, read the tools back, and run preflight.

cai agent remove-tool <agentId> --tool <toolId> --json
cai agent tools <agentId> --json
cai agent publish-preflight <agentId> --json

MCP uses agent_tool_remove with agentId and toolId, then agent_publish_preflight with agentId.

Confirm the tool is absent and resolve preflight blockers. For a Live attachment, review all draft changes and pending Live approvals before publishing. Publishing includes every draft change, moves existing Live conversations to the new version, and expires unexecuted approvals. Stopping running answers and updating Slack cards are best-effort cleanup, and a failure does not undo publication.

Publish the agent, then reread the map.

cai agent publish <agentId> --json
cai deps --workflow <workflowId> --json

MCP uses agent_publish with agentId.

If deleting the agent itself is intended, cai agent delete <agentId> --confirm --json is another exit. It revokes Live access. Conversations and history are retained but inaccessible, and the agent cannot be restored from the CLI. MCP agent_delete takes agentId without a confirmation parameter.

After handling callers, use Workflows → Support desk’s card menu → Delete and confirm, or:

cai workflow delete <workflowId> --yes --json

MCP workflow_delete takes workflowId, with neither yes nor force, and it deletes without another tool confirmation.

Deletion hides the workflow before it cleans up deployed triggers. A cleanup error can mean the workflow is already deleted. Reread the workflow list, then retry deletion with the same ID to finish the cleanup. Stored history remains, but neither the app nor definition restore undeletes the workflow. Inspect remaining Live callers from the earlier map.