Product Glossary

An agent answers users. An assistant builds it. A workflow contains flows you can call.

Who builds and uses an agent?

• Controller AI agent: A chat assistant you build from instructions, reference files, and tools, such as Support helper.
• Assistant: Your external assistant that operates Controller AI, such as Claude, ChatGPT, Codex, or Cursor.
• In-product builder: The hosted assistant at Home → Build for me. It is already configured with managed access.
• Instructions: Directions for how the agent behaves, such as Support helper’s rule for escalating account-specific requests.
• Plugin: A package for the host containing Controller AI connection configuration and skills. It is separate from product objects.
• Skill: Versioned instructions and files that teach an assistant a Controller AI task.
• Conversation: One agent chat with messages, files, and Test or Live context.

What gives an agent a capability?

• Tool: An integration action or one callable flow from a workflow, attached to an agent as a capability.
• Integration action: One provider-catalog app operation attached directly to an agent without a workflow.
• Workflow tool: One flow attached to an agent as a callable capability. Live calls follow the workflow’s latest live release.
• Connection: An authorized app account used by provider nodes or direct integration-action tools.
• Approval request: A request to authorize an agent tool call before execution.

What makes up a workflow?

• Workflow: A container for flows, triggers, shared schemas, and stored data.
• Flow: A part of a workflow that you can call, with typed inputs, nodes, edges, and outputs.
• Flow input: A named, typed value a caller supplies to a flow.
• Flow output: A named, typed Return response value, such as review_needed.
• Node: A configured action or control step inside a flow.
• Edge: A canvas wire from a node output to a downstream input. It is separate from app authorization.
• Expression: A typed calculation or reference to a value, used in a node field or condition.
• Trigger: An event source plus a mapping that passes its payload into one flow, such as the Daily invoice digest schedule.
• If / Else: A control step that chooses the first matching branch. When none matches, it uses Else.
• Router: A control step that sends input through every matching route.
• Join Paths: Depending on its selected mode, this control step combines incoming paths or continues with an active path.
• Only when: A condition on a node that skips its action when the condition is false.
• Continue on error: A node setting that captures errors as output and continues downstream execution.
• Return response: The action that supplies values for the current flow’s declared outputs.
• Run flow: An action that calls another flow with supplied inputs.
• Run flow on list: An action that calls a flow once per list item.
• Ask AI: An action that generates a response in a selected format inside a flow.

Which values and files persist?

• Schema or custom data type: A value’s fields and types, such as custom.ticket with ticket ID, customer email, summary, and status.
• Data record: A stored row with its own ID and creation and update times. The type dataRecord.custom.ticket represents a saved ticket.
• Collection or data table: Records for one custom type in one workflow environment, shown in Data tables.
• File value: Metadata for a Controller-hosted file, including its name, type, size, and URL.
• Reference file: An agent source document, such as support-policy.md. CLI/MCP call it knowledge. Publication freezes the file.
• Runtime file: A file in the agent’s workspace that can change. Live sees current Live files. Test overlays Dev/Test files. At matching paths, those files win. CLI/MCP use shared, with runtime as an alias.
• Conversation file: A file belonging to one conversation that you manage in the app. CLI/MCP have no operations for conversation files.

Which version runs, and what does it cost?

• Draft: The editable agent configuration used by the owner’s Test conversations.
• Published agent version: An immutable Live snapshot of instructions, tool settings, and reference files.
• Enabled / disabled: A runtime switch independent of publication. Disabling blocks Live use. The owner can still Test.
• Private / organization: Organization-wide access requires publication. Switching to private removes that access and stops active sessions. Individual grants remain.
• Development version: The editable workflow definition. It is Dev in the app and dev in assistant operations.
• Live release: A numbered, immutable workflow definition created by publishing.
• State: One saved snapshot of a workflow definition. Expand a history group to obtain a restorable state ID. Restoring changes the definition. Records and external effects stay untouched.
• Checkpoint: A named development state.
• Run or execution: One recorded node or flow execution with inputs, results, status, and outputs.
• Test (tooltip: Test current flow): The header button that runs the selected flow in Dev or Live.
• Usage balance: The organization’s available amount for runtime usage. It is separate from your external assistant’s model subscription.
• Usage credit: Extra usage purchased for the organization.

How do app labels map to assistant fields?

Commands specify --workflow <workflowId> explicitly without pinning. Run these commands to list your agents and workflows and get their IDs.

cai agent list --ownership mine --json
cai workflow list --limit 100 --json

Use the selected data.agents[].id as <agentId> and data.items[].id as <workflowId>. When data.hasMore is true, the workflow list is incomplete.

For MCP, use agent_list with ownership: "mine" and workflow_list with limit: 100.

List the workflow’s flows to get their IDs.

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

Note the selected data.items[].id as <flowId>. For MCP, use flow_list with workflowId.

In the app	CLI command	MCP tool and differing fields
Test: start a conversation	cai agent conversation create <agentId> --draft --json	agent_conversation_create: agentId, rail: "draft"
Live: start a conversation	cai agent conversation create <agentId> --live --json	agent_conversation_create: agentId, rail: "live"
Test a flow in Dev	cai run flow <flowId> --workflow <workflowId> --target dev --json	run_flow: workflowId, flowId, target: "dev"
Test a flow in Live	cai run flow <flowId> --workflow <workflowId> --target live --confirm-live --json	run_flow: workflowId, flowId, target: "live", confirmLive: true
Reference files	cai agent files <agentId> --space knowledge --json	agent_file_list: agentId, space: "knowledge"
Runtime files	cai agent files <agentId> --space shared --json	agent_file_list: agentId, space: "shared" (runtime alias)
Expect data record with id	Type dataRecord.custom.ticket	Type dataRecord.custom.ticket

To start a conversation, use the send arrow, whose accessible name is Start conversation. Live requires a published agent version. For a never-published agent, CLI/MCP Live creation can create a draft conversation before reporting CONVERSATION_RAIL_MISMATCH. Before retrying, run this command to list the existing conversations for inspection.

cai agent conversation list <agentId> --json

For MCP, use agent_conversation_list with agentId.