Organize with Labels

How do I keep related agents and workflows easy to find? Assign labels, then filter their lists. Use Support on Support helper and Support desk, Finance on Invoice intake, and Daily on Daily invoice digest. Labels belong to you, not to the organization. An agent shared with you displays its owner’s labels, and you cannot change them.

These examples continue Your first agent and Add agent tools. Otherwise, substitute an existing owned agent and workflow. Commands below use explicit targets without cai use.

Assign labels to related work

In the app: open Workflows, hover over Support desk, and click the + beside its labels. Select Support, or choose Create new label → Label name → Create and apply. Repeat on Agents → Support helper with its + control.

With an assistant: list your labels and targets.

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

MCP uses label_list, 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>. The agent ID must be a positive integer. The commands below replace each target’s complete label set with Support, creating that name if it is missing, so include every label you want to keep.

cai label set --agent <agentId> --label Support --json
cai label set --workflow <workflowId> --label Support --json

MCP uses label_set with exactly one string agentId or workflowId, and labels: ["Support"].

label set ignores cai use and CAI_WORKFLOW, so pass exactly one explicit --workflow or --agent. Read the saved assignment from data.labels. Within data, created, attached, and detached report completed writes.

Find everything with a label

Choose Workflows → Labels → Support or Agents → Labels → Support. Multiple selections match any selected label. Clear the selected-label chips to widen the list.

cai label list --json returns names and usage counts, not the IDs of matching objects. Workflow counts include deleted workflows, and agent counts exclude deleted agents. Neither the CLI nor MCP lists objects by label, so use the app filters.

Replace one object’s assigned set

Repeat --label for the full set you want. If you run the earlier Support-only command afterwards, it removes Daily from this workflow.

cai label set --workflow <workflowId> --label Support --label Daily --json

To clear every assignment:

cai label set --workflow <workflowId> --none --json

MCP uses label_set with workflowId and labels: [] to clear assignments.

These commands leave your label definitions and other objects’ assignments intact. In the app’s item picker, untick a label to remove one assignment.

Replacement uses separate writes. After a partial failure, inspect the target’s label chips, or reread its labels through cai workflow get <workflowId> --json or cai agent get <agentId> --json. Then rerun the complete set you want, and check data.labels afterwards. No workflow run is needed.

Assignments accept up to 50 names, each at most 64 Unicode characters. Names are trimmed, and empty or duplicate names are rejected. Names are case-sensitive, so Support and support are separate.

Rename or delete your labels

In Workflows or Agents, choose Labels → Manage labels. Hover the label row and choose the pencil (Rename), edit Label, then Save. Renaming updates every assignment. Renaming Finance to an existing Support fails with Label name must be unique, so combine them by reassigning objects instead.

To remove a label and its assignments without deleting workflows or agents, choose the trash icon (Delete), then confirm Delete. Renaming and deleting happen in the app, while CLI and MCP expose listing and assignment. List labels afterwards to verify the change.

Workflow folders are retired, so use labels for workflows. Folders inside agent files organize files separately.