Build a flow graph in Studio, from a blank canvas

This is the click-by-click path for building a flow: graph in Studio starting from nothing. If you've only seen flow apps as finished YAML, the canvas mechanics aren't obvious - this page covers exactly that gap.

For why you'd reach for a flow instead of letting agents coordinate themselves, see Flows. This page is only about the Studio mechanics.

Start from a blank canvas

Open Studio and either start a brand-new app or clear an existing canvas. You land on two big buttons: Build with AI and Add first step.... Click Add first step....

A panel opens with a few starting shapes, grouped by what they scaffold:

• Conversation - a chat agent, no flow: at all.
• Workflow - Empty flow.
• One-shot - a single request/response app.
• Background - Empty cron job, Empty webhook.

Click Empty flow. You'll be asked for an App ID - fill it in and continue.

What you get immediately

The canvas scaffolds a working spine for you, left to right:

That's a complete, compiling one-node flow already: Agent step is a real flow.agent node bound to your app's one declared agent, and Reply is a flow.terminal node. You can Install for Test right now and it'll answer.

Adding a step

Click on Agent step (or any flow node). A small floating toolbar appears above it, with a + and a row of quick-add icons (Parallel, Wait for approval are common ones). Click + More... to open the full step palette, organized in sections:

• Steps - Agent step, Transform (reshape data, no LLM call).
• Tools - your app's granted tool actions (says "grant first" if none are granted yet).
• Logic - IF (decision), Parallel, Wait for approval.
• Exit - Reply, End chat.
• Notes - a sticky note (canvas annotation only).

Click any entry - IF, say. It's inserted directly into the edge you clicked from, splitting it: Agent step -> IF -> Reply. You don't have to draw the connection yourself; picking the step type from an existing node's toolbar wires it in.

How branching actually looks

An IF node renders as a diamond, not a box. It has two default outputs: a green yes handle and a dimmer no handle, both visible right on the shape. Drag a new step off either handle the same way you'd drag off a normal node.

Need a third branch (a real multi-way switch, not just yes/no)? Connect a third edge from the diamond, it lands with an auto-generated label like branch_3. Double-click that label text on the canvas to rename it to whatever value your decision's expr should match against (for example refund, spam, p0); that becomes the real when: in the compiled YAML. The IF's own side panel also lists every branch as an editable row, with a Set as default button for whichever one should catch a value that matches none of the others. A decision with no such branch is refused at save time, because otherwise the flow would dead-end silently on an unexpected value.

Reading an edge

Every connection carries a small label at its midpoint - that label is the routing rule, not decoration:

What you see	What it compiles to
yes / no	when: "yes" / when: "no"
else	default: true (the catch-all)
a custom word (refund, p0, ...)	when: "<that word>"
red dashed line	a route pointing at a step that no longer exists - fix or delete it

Hover an edge to get its own small toolbar: insert a node mid-connection, or delete it.

Checking your work

The bottom-left status bar reads Compile OK the moment your graph is valid, and turns into a numbered error/warning list the moment it isn't - every message names the exact node and field that needs fixing. There is no separate "validate" button to remember to click; it's live as you edit.

Testing it

For a flow whose app is mode: one_shot, the top-right pill reads Live Test once the app is installed - click it for a real request/response tester against the deployed app (not a simulation). For mode: conversation, use the normal chat panel instead; the flow drives the same conversation you already talk to.

Going further

• Flows - the full node type reference (agent, tool, transform, parallel, decision, approval, terminal) and why you'd pick a flow over implicit coordination.
• Complete builder guide - every step type explained in depth: purpose, fields, what it connects to.
• Install for Test / Publish - the rest of the Studio workflow.