Flows

A flow is a workflow you draw on a canvas. Each step is a node (call a model, branch on a condition, loop over a list, run a connector action, run code in a sandbox, ask a person for approval), and the lines between nodes say what happens next. A run starts at the Start node and follows the lines.

Enterprise module

Flows is the enterprise flows module. Starting, resuming and sweeping runs needs an active Enterprise license. Reading history (the flow list, runs, steps and events) stays open after a license lapses, so nothing you already have is hidden. A start without a license is refused with 402 and requiresEnterprise: true.

Where flows live

Where	What you do there
Agents → your agent → Flows tab	List, create, import, duplicate, delete and open the flows of one agent. Expose a flow to the agent as a tool, or pick the entry flow of a FlowBase agent.
The flow editor (opened from the Flows tab)	Build the flow on the canvas, test it, publish it. See The flow editor.
Operate → Agent Observability → Flow runs	Every run of every flow in the project, with steps, input and output, and events. See Runs.

A flow belongs to a project. The Flows tab shows the Flows tab only when your role can read the flows service.

Two surfaces

Each flow has a surface, chosen when you create it:

Surface	What it is for
Headless	Runs on its own: inputs in, outputs out. Use it as an agent tool, from the Flows API, or from another flow with the Run flow step.
Conversation	Talks to a person in a chat. It can also use the conversation steps (Send message, Ask a question, Ask with a form, End conversation).

The FlowBase agent

When you create an agent you pick its type. A Smart Agent is a model loop: instructions, a model and tools. A FlowBase Agent (stored as agent kind flow) has no model or prompt of its own: a conversation flow answers every turn. On its Build tab you pick the Entry flow and the version that runs, Published or Draft. Callers and channels always get the last published version unless you switch to Draft for testing.

A Smart Agent can use flows too: Expose as tool on a flow in its Flows tab gives the model a tool that runs the flow with the flow's declared inputs.

An AI Agent step inside a flow is a different thing: it has its own hidden agent that belongs to the step. See AI Agent steps.

How a run starts

A run starts from:

• the Test panel in the editor (the draft);
• the client API (POST /flows/{idOrKey}/runs);
• an agent: a flow exposed as a tool, or the entry flow of a FlowBase agent on each chat turn;
• the Run flow step of another flow.

A flow is started by its trigger.start node only. A connector event (a GitHub webhook, a poll) does not start a flow by itself. Connector triggers start an agent; if that agent is a FlowBase agent, its entry flow runs and reads the event as {{ trigger.payload.* }}.

What is in this section

• The flow editor: the canvas, the steps, the test panel, publishing.
• Runs: the runs list, run detail, cancelling, resuming, approvals, and the limits you can set.
• Import from Studio: bring Cognipeer Studio flows into a project.
• Flows API: the client API for reading flows and running them.

Permissions

Flows uses the flows service level:

Level	What it allows
Read	See flows, run summaries and the canvas (read-only). Run input and output are hidden.
Write	Create, edit, test and run flows, cancel and resume runs, see step input and output.
Admin	Publish, delete a flow, import from Studio.

Who may decide an approval is the run's own rule, see Approvals.