Objects and Relationships

An agent is a chat assistant you build from instructions, reference files, and attached tools. A workflow contains flows, triggers, and shared schemas. Its flows use the workflow’s stored data for the selected environment. A workflow tool calls one flow. The flow’s inputs become tool arguments. Its returned values become the result. A direct integration action calls its provider operation without a flow.

How do the pieces fit together?

Support helper → Reference file: support-policy.md

Support helper → Integration action → Authorized app account

Support helper → Workflow tool → Support desk: Create escalation → Ticket data

Support desk can contain more flows, such as Find ticket. Within each environment, those flows share its ticket data.

The diagram uses examples for teaching. Your connected assistant helps build those objects. The in-product builder is the hosted assistant you open through Home → Build for me. Neither is the Support helper agent itself.

How does a support request become a record?

Suppose someone asks Support helper to escalate ticket T-104. The example policy calls for a ticket ID and short description. A workflow tool attached to Create escalation gives the agent a defined way to submit those values. The attachment identifies both the workflow and its particular flow.

The flow contract declares what the caller supplies and what it can receive. Its nodes perform configured actions or control steps. Its expressions supply calculations and values to node fields. In this example, a data action creates the escalation record. Then Return response sends the result to Support helper. Returning a value and storing a record are separate operations.

A second flow, Find ticket, reads the same ticket data. Both flows belong to Support desk. They do not need separate copies of the schema or collection. The callable contract is the flow, not the entire workflow.

The support exchange is saved in a separate object called a conversation. Its history shows the messages and tool activity in that chat. Ticket data shows what the escalation flow stored. When verifying a build, inspect both the answer someone received and the saved record it describes. Checking one does not replace checking the other.

When is one action enough?

If you only need to notify a support channel, one discovered integration action can attach directly to Support helper. It needs no wrapper workflow and creates no workflow execution. Verify it in the conversation’s tool activity and provider result. Only provider-catalog actions attach directly. Put a native action in a flow and attach that flow as a workflow tool.

When the notification also needs validation, stored state, or several steps, use a flow. Before executing a particular call, a tool can require approval.

Which values are stored?

A custom type describes a value’s fields. The Support example uses custom.ticket with field IDs ticket_id, customer_email, summary, and status. Those fields describe the ticket. They do not prove it was saved.

A data record is a stored row with its own ID and creation and update times. The type dataRecord.custom.ticket represents the saved ticket rather than only its shape. The example business identifier T-104 belongs in ticket_id. The record’s own ID is separate metadata. In Data tables, a collection holds records for one custom type in one workflow environment.

A workflow file value is metadata for a Controller-hosted file, including its name, type, size, and URL. It is not the parsed rows of an invoice CSV. In Agent file spaces, Reference holds source knowledge, Runtime holds shared working files, and Conversation holds one chat’s files.

In CLI/MCP, use knowledge for Reference and shared for Runtime (runtime is an alias). You can manage conversation files in the app. There is no CLI or MCP operation for those files.

What grants access, and what controls order?

A connection is an authorized app account. A direct integration-action tool binds a connection that belongs to the agent owner and matches the app. A workflow tool has no connection of its own. Each provider node uses its configured connection. An edge is a canvas wire from a node output to a downstream input. It supplies workflow wiring, not app authorization.

Agents and workflows have owners. A workflow attachment is checked against the owner’s workflow and selected flow. When you share an agent, those connections are not replaced with each visitor’s accounts. Direct actions use the owner’s connection.

Development and live select separate workflow definitions and data stores. Agent Test uses development workflows. Live workflow tools follow each workflow’s latest live release. A trigger provides another entry point through an event source and a mapping into one flow. The mapping passes the event payload to that flow.

Find these objects in your account

In the app: open Agents → Support helper → Edit for its instructions and tools. Once you have built that example, open Workflows → Support desk for flows, Inputs, Outputs, and Data tables.

With an assistant: without selecting a workflow, run these account-wide commands to list matching agents and workflows.

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

For MCP, use agent_list with ownership: "mine", search: "Support helper" and workflow_list with limit: 100. Workflow lists default to 25 rows and allow up to 100. Before treating the result as complete, check data.hasMore.

For either method, use the returned IDs. Similar names do not identify the same object.