> ## 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.

# Flow agents: build a call out of steps

> What a flow agent is, when to pick it over a single prompt agent, and how a call moves from step to step, from the Start step to the end of the call.

A flow agent runs a call as a set of steps that you draw on a canvas. Each step does one job (talk with the caller, call an API, check a value, transfer the call), and transitions decide which step comes next. This page explains when a flow is the right choice and how a call moves through one.

## When to use a flow agent

Pick a flow agent when the call has a shape you want to control. Pick a [single prompt agent](https://docs.tryhamsa.com/agents/build/single-prompt.md) when one set of instructions can handle the whole conversation.

| Use a flow agent when | Use a single prompt agent when |
| - | - |
| The call has stages that must happen in order, such as verify, then collect details, then book | The conversation is open, such as answering questions about your business |
| A decision must follow a fixed rule on a value, not the model's judgment | The model can decide what to do from the conversation |
| You call APIs at set points and branch on whether they worked | Tools can be called whenever the caller asks for something |
| Different parts of the call need different instructions, voice or call settings | One prompt, voice and set of settings fit the whole call |

## Create a flow agent

**1. Start a new agent**

In **Agents list**, click **Create agent** and choose **Create flow agent**.

**2. Name it**

In **Create flow agent**, enter the **Agent name** and click **Create**. The [flow builder](https://docs.tryhamsa.com/agents/flow/flow-builder.md) opens with a Start step on the canvas.

**3. Write the system prompt**

Open **Global settings** and fill in **System prompt**. A flow can't be saved without it. See [Flow settings](https://docs.tryhamsa.com/agents/flow/flow-settings.md).

For importing, duplicating and deleting agents, see [Create, import and manage agents](https://docs.tryhamsa.com/agents/build/create-an-agent.md).

## The parts of a flow

* **Steps.** Boxes on the canvas. Every flow has one Start step, where the call begins. You add the rest with **Add node** (the app says "node" on some buttons and labels; these docs say "step"). See [Step types](https://docs.tryhamsa.com/agents/flow/steps/overview.md).
* **Transitions.** Each step lists the ways out of it. You connect each transition to the step it leads to. See [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md).
* **Global steps.** Steps the agent can jump to from anywhere, for example a step that answers "what are your opening hours?" in the middle of a booking. See [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md).
* **Variables.** Values the flow knows or collects: the caller's number, values passed when the call starts, details the caller gives, results from an API. Steps can read them in messages and conditions. See [Variables](https://docs.tryhamsa.com/agents/variables/overview.md).
* **Live variables.** Values the agent keeps up to date after every caller turn, in every step, such as the caller's name or a request for a person. A transition can move the call as soon as one matches. See [Live variables](https://docs.tryhamsa.com/agents/variables/live-variables.md).
* **Global settings.** Settings for the whole flow: system prompt, model, voice, tools, live variables, call settings. See [Flow settings](https://docs.tryhamsa.com/agents/flow/flow-settings.md).

## Step types at a glance

| Step | What it does |
| - | - |
| [Start](https://docs.tryhamsa.com/agents/flow/steps/start.md) | Where the call begins: speaks a first message, or runs a tool first |
| [Conversation](https://docs.tryhamsa.com/agents/flow/steps/conversation.md) | Talks with the caller and waits for answers |
| [Router](https://docs.tryhamsa.com/agents/flow/steps/router.md) | Picks the next step by checking variables against rules, without the model |
| [Tool](https://docs.tryhamsa.com/agents/flow/steps/api-request.md) | Calls one of your APIs |
| [Web tool](https://docs.tryhamsa.com/agents/flow/steps/web-tool.md) | Asks your web page to do something during a website call |
| [Transfer call](https://docs.tryhamsa.com/agents/flow/steps/transfer-call.md) | Transfers the call to a phone number |
| [Transfer to agent](https://docs.tryhamsa.com/agents/flow/steps/transfer-agent.md) | Hands the call to another agent |
| [Set local variables](https://docs.tryhamsa.com/agents/flow/steps/set-variables.md) | Sets variable values |
| [Change agent settings](https://docs.tryhamsa.com/agents/flow/steps/change-settings.md) | Changes the system prompt, voice or call settings from that point on |
| [End call](https://docs.tryhamsa.com/agents/flow/steps/end-call.md) | Ends the call |

## How a call moves through a flow

**1. The call starts at the Start step**

In conversation mode it speaks its message. In tool mode it calls a tool first and follows **On Success** or **On Failure**.

**2. Steps run one after another until one waits for the caller**

Routers, tools, set variables and change settings steps run straight away and move on through their transitions. The caller doesn't hear anything from a router or a set variables step.

**3. A conversation step speaks and waits**

It plays its message, then waits for the caller's reply. The model can't take a transition while it speaks a step's opening line, so the caller always gets a chance to answer. (A step with an **Auto** transition is the exception: it plays its message and moves on.)

**4. The next step is chosen**

When the caller replies, the model decides whether one of the step's prompt transitions (or a global step) fits what the caller said. Other transition types follow fixed rules: a key press, a rule on a [live variable](https://docs.tryhamsa.com/agents/variables/live-variables.md), or "the caller replied". [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md) explains each one.

**5. The call ends**

At an End call step, after a transfer, or when the caller hangs up. A router whose conditions don't match and whose **Else** isn't connected also ends the call.

![The Order Support flow during a test call, with the Verify the order step ringed as the active step and Live call logs listing the call so far](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/flow-test-call-active-step-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=b4f1cc8002e62aeebb675813b2b06e8d)

## How it works on a call

* The system prompt applies on every step. Each conversation step adds its own message as instructions for that part of the call, so the model always knows which step it is in.
* Only conversation steps (and the Start step's opening message) can be interrupted by the caller. Every other step plays its message to the end. See [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md).
* While the caller is in a step, the model can only move to the steps that step's transitions point to, or to a global step. It can't skip ahead on its own.

## Related

> [card] [Work in the flow builder](https://docs.tryhamsa.com/agents/flow/flow-builder.md)
>
> Add and connect steps, group them, find them.

> [card] [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md)
>
> How the next step is chosen on a call.

> [card] [Design flows that hold up](https://docs.tryhamsa.com/agents/flow/design-tips.md)
>
> Advice based on how the runtime behaves.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Call your flow from the browser before you publish.


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