Studio builder, complete guide
This page explains how the visual builder in Studio works: opening a blank
canvas, the two shapes an app can take, and how connections and the +
button behave. Everything here compiles to the same app.yaml the daemon
runs; nothing described here is Studio-only behavior.
Every step type on the flow canvas, field by field, lives on its own page: Flow step reference. The Architecture-view nodes behind every app - App, Runtime, Agent, Brain - each have their own page too.
Starting a new app
Studio opens on a blank canvas with a single button: Add first step.... Clicking it offers four starting shapes, grouped by what the app is for:
- Conversation, a chat assistant. Someone sends a message, the app replies, the conversation continues turn after turn.
- Workflow, a blank flow graph. You build the path step by step instead of letting a single agent decide everything on its own.
- One-shot, a single request in, a single answer out. No back-and-forth, no memory between calls. Meant to be called by another app or an external system, not chatted with directly.
- Background, nothing runs until something wakes it up: a schedule, an incoming webhook, a new item in an RSS feed. No live audience waiting on the other end.
Picking one of these sets runtime.mode in the underlying YAML
(conversation, one_shot, or background) and lays down a small starting
scaffold: an entry point, one agent, and, for Workflow, an empty flow ready
to build on.
Two ways an app can be built
Every app has an entry agent with a brain (a model) and a system prompt. From there, Studio supports two different shapes.
Agent shape. The entry agent reads the incoming message and decides everything itself: what to say, which tools to call, whether to hand off to a specialist. There is no explicit graph; the agent's own judgment is the routing logic. This is the right choice when the task is genuinely open-ended and a human reviewing transcripts would also have to use judgment to say what should happen next.
Flow shape. The graph itself decides what happens: this step runs, then that one, branching on a condition a previous step produced. Nothing is left to the model's judgment except inside the individual Agent steps you place. This is the right choice whenever the process can be drawn as a diagram before a single line of the app is written. Triage, then a specialist branch, then a reply, is a flow. Open-ended conversation is not.
An app can mix both: an entry agent that delegates to specialist agents (agent shape) can still contain, or be triggered by, a flow. Studio shows two canvases for this reason:
- Flow view, the execution path only: flow steps and the arrows connecting them. This is what you build day to day.
- Architecture view, everything else: the agent's own brain, installed tool modules, hooks, middleware. Toggle it with the Architecture button at the top of the canvas. A wire you see here (for example, the agent's own card connected to the app's runtime block) is bookkeeping about how the app is put together, not a step in the execution path. It will never appear in Flow view.
Reading a connection
Every arrow on the flow canvas has a direction that means something specific: it starts where a step's work is done, and ends at whatever runs next. A step reads what came before it from its incoming side; it decides what runs next through its outgoing side. On most step shapes these are the left and right edges of the card. On a diamond-shaped step (the IF/decision step) incoming and outgoing sides are kept strictly separate on purpose, so a wire arriving never lands on the same point as one of the branches leaving.
A label on an arrow, where one is shown, is the exact value that has to match for the flow to take that path. It is not decorative: renaming a branch changes what condition routes through it.
Adding a step
Click the + on a step to add whatever comes next, wired automatically. What gets offered depends on the step you clicked from: an ordinary step (Agent, Transform, Tool) offers a straightforward next step; a step with more than one real outcome (IF, Parallel, Wait for approval) offers to add a new branch instead. Only step kinds that make sense from that particular step are shown; the palette is contextual, not a flat list of everything that exists.
Reply and End chat never offer a +: nothing can run after them, they are where a path through the graph ends.