Skip to content
Controller AI Controller AI Controller AI Docs

Nodes and components

A node is one executable step. Getting a node from “added” to “ready” follows a fixed order, and most integration-node problems are a skipped step in it:

component → connection → props (in dependency order) → wiring → resolved output type

Discovery

Section titled “Discovery”

Around 80 built-in node types ship with the platform (flow control, Use AI, HTTP, Data, File, Agent, plus managed API nodes), and the integration catalog adds roughly 14,000 components across connected apps — each either an action (does something) or an event (can be a trigger).

Terminal window
cai node find "send slack message"
cai node component <nodeSlug> <componentKey>
cai integration search "hubspot"

Two discipline rules: never conclude a capability doesn’t exist without searching the catalog, and never infer a component key from a display name — keys are exact identifiers, and near-miss names are common. (Naming quirk worth knowing: the Use AI node’s action is named Ask AI; the trigger-canvas Run flow node shares its display name with the in-flow one and differs only by key.)

Connections

Section titled “Connections”

An integration node does nothing until a connection is assigned — the node won’t even show its configuration. Your default connection for the app is auto-assigned when one exists; otherwise connect in the browser:

Terminal window
cai connection list --integration slack
cai connection connect slack --wait

The browser handoff exists to keep provider credentials out of the terminal and the agent’s context — there is no credential entry in the CLI. Details and auth types: Connections.

Changing a node’s connection invalidates connection-scoped options — anything picked from that account’s dropdowns (channels, sheets, pipelines) must be re-resolved.

Props: order matters

Section titled “Props: order matters”

Node props are not independent form fields. Some props are reload selectors: choosing a value (a spreadsheet, an object type, a base) fetches a new prop set for its dependents (the sheet, the fields). Configure in dependency order — selector first, re-read props, then dependents:

Terminal window
cai node props <nodeId>
cai node options <nodeId> --prop <propName>     # provider-backed dropdown options
cai node set <nodeId> --prop <propName> ...
cai node status <nodeId>

Rules that prevent silent breakage:

  • A prop reload replaces the node’s whole prop map. Values whose props vanish from the new set are dropped — re-read props after every selector or connection change; don’t assume earlier configuration survived.
  • Provider-backed options are a value + label pair. Persist both exactly as returned — the label is not cosmetic; the platform uses it to re-resolve providers that don’t index opaque ids. Never inline a hand-typed value where a remote option is expected.
  • Text-like props are natively dynamic — expressions and templates go straight into the value. Number, dropdown, and similar props take expressions only when they offer the “Use dynamic data” switch.

Output types

Section titled “Output types”

A node’s output type is what lets downstream expressions be authored. Built-in actions largely ship static contracts (typed before any run). Dynamic nodes — HTTP, most catalog actions — resolve their type from one successful run, or from a declared contract when running is too consequential (type system):

Terminal window
cai run node <nodeId> --inputs values.json    # isolated: does NOT execute upstream nodes
cai node declare-output <nodeId> --sample-file shape.json

A node test proves configuration and resolves the output type; it never proves upstream-derived values — only a flow run does.

The HTTP node

Section titled “The HTTP node”

The escape hatch for anything without a catalog component: method, URL, headers, body (none / JSON / raw / form data), auth (none / basic / bearer), and a timeout setting. Its output type resolves from a real run like any dynamic node.

What nodes cost

Section titled “What nodes cost”

Flow control, logic, and data nodes are free; integration and AI nodes are metered per execution — see the cost model. Each node’s pricing note is shown in the builder and in cai node component.

Example prompts

Section titled “Example prompts”
Find the right component to create a HubSpot deal, connect my account, configure it in dependency order, and resolve its output type with one safe test.
I changed the connection on this node. Re-check every connection-scoped option and tell me what needs re-selecting.