> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Work in the flow builder

> Add, connect, group and find steps on the flow builder canvas, tidy it with auto layout, use keyboard shortcuts, and fix the issues the builder reports.

The flow builder is where you draw a flow agent: steps on a canvas, connected by their transitions. This page covers the canvas itself: adding and connecting steps, keeping a large flow readable, and fixing what the builder flags. What each step does is on the [step type pages](https://docs.tryhamsa.com/agents/flow/steps/overview.md).

## Before you start

* To edit, your role must allow editing agents. Without it the builder opens with **View only**: "You do not have permission to edit this agent. Changes you make here will not be saved." See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).
* The canvas can't be edited on a phone. On a small screen you get an overview of the agent and can test it, but not change it.

## Find your way around

![The flow builder with the Order Support flow: the header with Test, the tool rail on the left, the canvas toolbar at the bottom, and the Verify the order step's settings panel open on the right](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/flow-builder-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=2901869963a4ef48255f9c20f1e53d97)

| Area | What's there |
| - | - |
| Header | The agent's name, save status, and the **Test** menu (**Browser call**, **Phone call**, **Chat**) |
| Tool rail | **Add node**, **Variables** (every variable the flow can use), **Global settings** (settings for the whole flow) |
| Canvas | Your steps and the connections between them |
| Canvas toolbar | **Select**, **Pan**, **Auto-layout nodes**, **Find node**, **Open minimap**, **Keyboard shortcuts**, **Zoom out**, **Fit to view**, **Zoom in** |
| Settings panel | Opens from a step's **Node settings** button, or when you double-click the step. While it's open, clicking another step shows that one. It holds the step's main fields, then sections such as **Transitions**, **Variables** and **Global** |

The Start step has its own colour, a lime frame and a solid lime tab, so you can find where calls begin at a glance. No other step uses it.

The app calls steps "nodes" on some buttons and labels, such as **Add node**. These docs say "step".

## Add a step

**1. Open the step list**

Click **Add node** in the tool rail.

**2. Pick a type**

Type in **Search node types** or scroll the list, then click the type. Hover a type to read what it does.

![The Add node list open next to the tool rail, with Search node types and the step types Conversation to Change agent settings](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/add-node-menu-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=55d2a85f5b30688691a083533698a88f)

**3. Set it up**

The step appears in the middle of the canvas and its settings panel opens. Give it a label (up to 100 characters) so you can tell it apart on the canvas and in call logs.

You can also add a step from a transition: drag from a transition's handle on a step card and drop it on an empty part of the canvas. The step list opens, and the step you pick is connected to that transition. This works while the transition isn't connected to anything yet.

Every flow has exactly one Start step. It isn't in the list, and you can't delete or copy it.

## Connect steps

Steps are connected through their transitions. Each transition on a step card has a handle; the connection from that handle to another step says "when this transition is taken, go there".

**1. Add a transition**

On the step card, click **Add** ("Add new transition") and choose a type, such as **Prompt**. The types a step offers depend on the step. See [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md).

![The Add menu on the Start step card, offering Prompt, When a live variable matches, DTMF input and After user replies](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/add-transition-menu-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=3dfde32c2e8cc40cca6c9fb3669f7a97)

**2. Set it up in the settings panel**

Click anywhere on the transition on the card. The step's settings panel opens on that transition's settings. Fill in what it needs there, such as **When to take this path** for a **Prompt** transition or the **Keypad key** for a **DTMF input** transition. Changes save as you make them.

![The Verify the order step on the canvas, with its second Prompt transition tagged Conditioned, and the settings panel open on that transition: When to take this path, Offer it only when with one rule, Extractions, and Delete transition](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/transition-settings-panel-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=58fe80f57e73aaa4e11911cd89788b2b)

**3. Draw the connection**

Drag from the transition's handle to the step it should lead to.

The canvas enforces a few rules:

* A step can't connect to itself.
* Two steps can be connected only once in the same direction.
* Each transition handle has one connection.
* A step set to return to the step that called it has no outgoing connections. See [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md).

A transition with no connection does nothing on a call. To follow a connection on a large canvas, double-click it: the canvas moves to the step it leads to, and opens its group if it's in one.

To remove a connection, click it, then click the delete button that appears in its middle.

To delete a transition, open its settings and click **Delete transition** at the bottom, or hover the transition on the card and click its ×. Its connection goes with it.

A **Prompt** transition with **Offer it only when** rules shows a **Conditioned** tag on the card. See [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md#prompt).

## Select, copy and delete steps

* Click a step to select it and open its settings. Hold Cmd (Mac) or Ctrl (Windows) and click to add more steps, or hold it and drag to select everything in a box.
* Copy and paste the selection with Cmd+C and Cmd+V on Mac, Ctrl+C and Ctrl+V on Windows. The Start step is never copied.
* Press Delete or Backspace to delete the selected step. The builder asks first, and deleting a step also removes its connections.

## Move around the settings panel

The settings panel shows a step's main fields, then a row for each section. Sections, and rows inside them, open one level down, with **Back** to return:

* **Transitions** lists every transition of the step, in the order the card shows them. Click one to open its settings. **Else**, **Auto**, **After user replies** and a step's fixed transitions (such as **On Success**) are listed but have nothing to set.
* **Variables** lists the step's variables. Click one to open its card.
* Clicking a transition on the canvas opens the panel straight on that transition. Clicking the step itself, or its **Node settings** button, takes the panel back to the top of the step.

![The settings panel of the Verify the order step one level down, on the order\_id variable card, with Back at the top](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/settings-panel-variable-card-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=e81eaa9ad00228ce05a1263485104834)

## Group steps

Groups fold a part of the flow into one card, so a large flow stays readable.

**1. Select the steps**

Select two or more steps.

![Three steps selected on the canvas, with the Group 3 items button at the top left](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/group-selected-steps-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=892aec65830bdda4c9eb1a05b311bf7d)

**2. Create the group**

Click the group button that appears (for three steps it reads **Group 3 items**), or press Cmd+G on Mac, Ctrl+G on Windows. In **New group**, enter a **Group name**, for example "Book appointment", and click **Group**.

![The New group dialog with the group name Order help and the Group button](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/new-group-dialog-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=7e58a0c59834de4b7f255988b9d24fcb)

Once you have groups:

* Switch **Show** between **By groups** (each group is one card) and **All steps** (every step, as if there were no groups).
* Click **Open group** on a group card to open it. The path at the top (**Where you are**) shows how deep you are; click **Flow** to go back to the top.
* A group card shows how many steps it holds and how many need attention. During a test call, the group the call is in shows **In progress**.
* Use the card's **Group actions** menu (the ... button) to **Rename** or **Ungroup**.
* Use a step's menu to **Add to group**, **Move to group**, start a **New group…** or **Remove from group**.

Groups only change how the canvas looks. They don't change how a call moves.

![The canvas shown By groups, with the Order help group card listing its three steps and Open group](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/flow-by-groups-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=0971468c9f07f720203b8e29b1f0b9e5)

![The Order help group card with its Group actions menu open, offering Rename and Ungroup](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/group-actions-menu-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=314f2df513b7ed23d953704e8da151fc)

### Connections into and out of a group

Shown **By groups**, connections still show where a call can go:

* **A closed group.** Connections into or out of a group card are drawn as lines to and from the card. When one line stands for several connections, hover it to see how many ("3 connections"). Double-click a line into a closed group to open the group.
* **An open group.** Inside a group, a connection to or from a step outside it ends in a dashed label, such as **From Order status** or **To Anything else?**. Click the label to go to that step. When several steps are involved, the label reads, for example, **From 3 steps**: click it and choose one under **Go to a step**. A "×2" on a label means that step has two connections here.

![Inside the Order help group: its three steps, with dashed labels From Order status leading in and To Anything else? leading out](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/group-open-references-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=e3f6772e16f01346a48ae9d2b85b1664)

## Find a step

Press Cmd+F on Mac or Ctrl+F on Windows, or click **Find node**. Type in **Find in nodes and notes**. The search looks in step labels, step types, messages, transfer messages, phone numbers, descriptions and transition conditions.

![The Find box with the search order showing match 1 of 7, and the matching Greeting step selected](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/find-node-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=547852f7f929535f2eccb75f6e2b2b4e)

* Press Enter for the next match and Shift+Enter for the previous one. Each match is selected and centered.
* Use **Filter by type** (the button next to the search box) to search only some step types. The list shows how many steps of each type the flow has. Tick one or more types, or choose **All types** to clear the filter. Steps that don't match fade out.

![The Find box searching for order, with the Filter by type list open: Conversation ticked with 5 matches, then Start, Tool, End call, Transfer call and Router](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/find-filter-by-type-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=276763e7f952f7a448d06f57d967dec7)

## Tidy the canvas with auto layout

Click **Auto-layout nodes** in the canvas toolbar and pick a layout:

![The Auto-layout nodes menu above the canvas toolbar, with Vertical, Horizontal and Metro](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/auto-layout-menu-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=4dbfe8df326b0a9bc4ba775d6d04c731)

| Layout | What you get |
| - | - |
| **Vertical** | Steps flow from top to bottom |
| **Horizontal** | Steps flow from left to right |
| **Metro** | Left to right lines, with steps snapped to a grid |

The Start step always comes first. In a flow with groups, each group is laid out on its own.

## Keyboard shortcuts

Press **?** to see every shortcut. On the canvas:

| Keys (Mac / Windows) | What it does |
| - | - |
| Click | Select a step, or open a group |
| Cmd+Click / Ctrl+Click | Add a step to the selection |
| Cmd+Drag / Ctrl+Drag | Select everything in a box |
| Esc | Clear the selection |
| Cmd+G / Ctrl+G | Group the selected steps |
| Cmd+C / Ctrl+C | Copy steps |
| Cmd+V / Ctrl+V | Paste steps |
| Delete or Backspace | Delete the selected step |
| Cmd+F / Ctrl+F | Find a step |
| Enter / Shift+Enter | Next or previous match, in Find |
| Scroll | Move around |
| Cmd+Scroll / Ctrl+Scroll | Zoom in and out |
| Double-click a connection | Go to the step it leads to |

In the whole editor:

| Keys (Mac / Windows) | What it does |
| - | - |
| Cmd+S / Ctrl+S | Save now |
| Cmd+Shift+Enter / Ctrl+Shift+Enter | Start a test call, or end it |
| Cmd+Alt+Enter / Ctrl+Alt+Enter | Start a test chat, or open it |
| Cmd+K / Ctrl+K | Search or run a command |

![The Keyboard shortcuts panel listing the flow canvas shortcuts](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/keyboard-shortcuts-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=6e5cdd42fda1cb33d0a9f0ed1cc5bbf8)

## Save and fix issues

Your changes save to your draft automatically as you work, even while the flow has issues. Cmd+S (Ctrl+S on Windows) saves right away. Testing waits until changes are saved: "Please save changes before testing". See [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md).

When something in the flow is incomplete, a red issue button with a count appears in the header. Click it to open **Configuration issues**: it lists each problem by step, and **Focus** takes you to that step. Common ones:

* "System instructions are required": the **System prompt** in **Global settings** is empty.
* "All transitions must have descriptions": a transition hasn't been filled in, for example a **Prompt** transition with no condition.
* "Please select a tool for this node to use": a Tool step has no tool.
* "Trigger condition is required for global nodes": a global step has no trigger condition.

![The Configuration issues list open from the red issue button, showing a Tool step with 'Please select a tool for this node to use' and a Focus button](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/configuration-issues-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=bf09e73e01177488e5a28ada3642907b)

A variable a step uses but the agent doesn't define gets an amber chip that says it isn't defined in this agent, with **Add as dynamic variable**. That is a hint, not an error. **Add as dynamic variable** opens your dynamic variables with the name filled in. See [Test values and the undefined variable chip](https://docs.tryhamsa.com/agents/variables/test-values.md#the-not-defined-chip).

Deleting a variable that steps still use asks first, whatever its kind (a step's own variable, a live variable, a local or dynamic variable). The dialog lists the steps that use it; click one to go to it. **Delete anyway** removes the variable, and those steps then show it as not defined. See [Variables](https://docs.tryhamsa.com/agents/variables/overview.md#good-to-know).

![The Delete variable dialog: order\_id is used in 2 steps, with links to Share delivery update and Start a return, and the Delete anyway button](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/delete-variable-warning-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=3b09f2aeb12bf34c29c20cc6c7735708)

## Good to know

* There is no undo on the canvas. To go back to an earlier state, use a saved version. See [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md).
* When you view an older version, every panel is read-only.
* While a test call runs, the step the call is in gets a moving ring, and **Live call logs** show what happens step by step. See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

## Related

> [card] [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md)
>
> Each transition type and how the next step is chosen.

> [card] [Step types](https://docs.tryhamsa.com/agents/flow/steps/overview.md)
>
> What every step does and which transitions it has.

> [card] [Flow settings](https://docs.tryhamsa.com/agents/flow/flow-settings.md)
>
> The Global settings panel.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Browser call, phone call and chat.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.