The flow editor
Enterprise module
Flows is part of the Enterprise edition. See Flows.
Open a flow from Agents → your agent → Flows. The editor has a palette on the left, the canvas in the middle, an inspector on the right and a test panel at the bottom.
Create a flow
On the Flows tab, New flow asks for a Name, an optional Description and the Surface (Headless or Conversation). On a Smart Agent you can also tick Expose as tool and give the tool a name and description. The new flow opens in the editor. Import brings in a flow file (see Import from Studio).
Build on the canvas
Add a step by dragging it from the palette, or click it to add it after the selected step. Drag from a step's output to another step to connect them. Steps with more than one exit have named outputs (true and false on a condition, the cases and default on a switch, body and done on a loop, approved and rejected on an approval, and an error output when a step is set to follow it).
The toolbar has Undo, Redo, Validate, Test, Copilot, Versions, Save and Publish. The More actions menu has Auto-layout, Fit to view, Export JSON, Import JSON and Duplicate flow. Select several steps to move, align or delete them together.
The flow panel
With nothing selected, the inspector shows the flow itself:
| Setting | Meaning |
|---|---|
| Surface | Headless or Conversation. |
| Inputs | Declared inputs. Read them in steps as input.<name>. They are also the API and tool input schema. An input marked Secret is never stored on the run and is masked in step logs. |
| Outputs | Declared outputs: a name and a value template. This is what a run returns. A lone {{ expression }} keeps its raw type. With no outputs the run returns an empty result. |
| Variables | Run-scoped values, read as vars.<name> and set with a Set variables step. |
| Limits | Run timeout (active time only, waiting is not counted), Max steps and Max loop iterations. |
Using values from earlier steps
Template fields take {{ }} expressions: {{ steps.<key>.output.text }} for an earlier step, {{ input.<name> }}, {{ vars.<name> }}, {{ loop.item }} inside a loop and {{ trigger.* }} for what started the run. Condition fields take a bare expression. Secrets are not part of the expression scope: a step that needs one names a Config item and reads it when it runs.
Every step can be disabled (it is skipped), given a Timeout, Attempts (retry), and an On error policy: fail the run, continue, or follow the error output. A write step that fails with an error marked not retryable is not run again, even when it has a retry policy.
Steps
The palette groups steps by category.
| Category | Steps |
|---|---|
| Triggers | Start (one per flow; its output is the run input). |
| Logic | Condition, Switch, For each, While, Delay, Stop, Run flow, Set variables, End. |
| Data | Transform, Parse JSON, Stringify JSON, Regex, Split text, HTML to markdown, Array. |
| AI | LLM, Classify, Extract data, Guardrail, Redact PII, Render prompt. |
| Knowledge | Search knowledge. |
| Agents | AI Agent, Run agent. |
| Human | Human approval. |
| Conversation | Send message, Ask a question, Ask with a form, End conversation (Conversation flows). |
| Integrations | HTTP request, Web search, Scrape web page, Send email, memory steps (Remember value, Recall value, Save user memory and others). |
| Files | Save file, Read file. |
| Code | Run code, and the sandbox steps (Create sandbox, Run command, Run code in sandbox, Write file to sandbox, Read file from sandbox, Manage sandbox files, Stop sandbox, Delete sandbox). |
| Connectors | One step per action of an active connector. |
Use the palette search to find a step. A step the project cannot use (a service that is off, no sandbox runtime) is shown as unavailable with the reason.
AI Agent steps
An AI Agent step owns a hidden agent. You pick its model, write its instructions and give it tools, MCP servers, knowledge and guardrails with Configure agent. The agent decides which tools to call, can ask a person for tool approval or a question, and answers as text or structured JSON. It belongs to the flow: it is not listed under Agents and is published together with the flow. A copied step gets its own agent with the same settings.
The step's Task is what the agent should do now, for example {{ trigger.message }}. By default the agent keeps the whole chat across the runs of one conversation. When the agent waits for a person (a tool approval or a question), the run shows Waiting for an agent with the request, and answering it resumes the run. See Runs.
To run an agent that exists on its own under Agents, use Run agent instead.
The Copilot can create and configure the agents of AI Agent steps when it proposes a flow change.
Connector action steps
Every action of an installed connector package is a step of type connector.<package>.<action>, unless the package hides it. The palette lists the actions of the project's active connectors, grouped by package and then by the package's own groups. The step's form is built from the action's input schema: field kinds, help, options read from the connector and show-if conditions.
- The step has a Connector field: it uses a connector of its own package that has the action on.
- Option lists (a repository, a bucket) are read only while the connector has a working account.
- A connector whose source feeds a knowledge base with access control offers no read actions to flows.
See Connector tools and approvals for how connector actions are marked read, write or destructive.
Code steps
Run code runs a Python or JavaScript (Node.js) snippet in a fresh sandbox that is deleted afterwards (code.run). Pass data in through Input (written to /workspace/input.json, and its path is in FLOW_INPUT_PATH) and read the result back from the step output. The code is not template-rendered: {{ }} stays as written. Settings include the Sandbox template, CPU, memory and disk, Block network access, Environment variables, Secret variables (Config items), a Command timeout (seconds) and Fail on non-zero exit.
The other sandbox steps work on a sandbox that belongs to the run: Create sandbox starts one, later steps use it, and it is deleted when the run ends or sits idle too long.
Sandbox steps need the Sandbox runtime and a sandbox template under Sandbox → Templates. A run may own at most 8 live sandboxes by default. See Sandbox and the limits.
Human approval
Human approval pauses the run until a person decides. You set a Title, Details, the Approvers (project members; empty means anyone with Flows admin access), whether the approver must differ from the run starter, the Time to decide (5 minutes to 7 days) and what happens If nobody decides in time (Reject or Approve automatically). It continues on approved or rejected.
Validate
Validate lists problems (a missing required field, a broken connection, an unknown step type). Click a problem to jump to the step. Publish runs the stricter publish check.
Test
Test opens the test panel. It runs the saved draft: save first, unsaved changes are not included. Fill the Inputs as a form or as JSON and choose Run draft. The panel shows the step timeline; select a step to see its input, output, error and logs. A Conversation flow gets a Chat simulator where you type messages. Open in Observability opens the run under Flow runs.
A test run is a real run: it calls real models, connectors, HTTP endpoints and sandboxes. Point steps at test targets while you build.
Versions and publishing
The editor saves the draft. Publish freezes the current draft as a new numbered version with an optional Note; unsaved changes are saved first. Callers that do not name a version (the API, a tool, a FlowBase agent set to Published) run the last published version. A flow that was never published can only be run as a draft by Test or by naming version: "draft".
Versions lists published versions with their notes. Select one to inspect its definition read-only, and Restore to draft to copy it back (the published version stays as it is). If someone saves the flow while you edit, the editor offers Reload theirs, Keep editing or Overwrite with mine.
A flow can be exported as a cognipeer.flow JSON file (Export JSON) and imported again, including the hidden agents of its AI Agent steps without their secrets.
Read-only view
With read access only, the flow opens as a read-only canvas: click a step to see its settings, and the Runs link opens its runs. Edit is disabled with "You have read-only access to flows".