Build Conversation Flows

A flow describes how a conversation proceeds. You build it in the flow editor as a state graph: a map made of states and transitions between them.

The flow editor

The flow editor is a graphical interface in which you arrange states as nodes and link them with connections (transitions). You can arrange the graph freely, add states, edit them, and remove them again.

Flow editor with state list and state configuration — The flow editor: on the left the list of states, on the right the configuration of the selected state (instructions, permitted tools, outputs).

Undo and redo

You can undo every change in the draft. This applies to edited fields and type changes as well as to deleted states and a flow import. Use the Undo and Redo buttons in the editor header or the keyboard shortcuts.

Action	Windows / Linux	macOS
Undo	`Ctrl` + `Z`	`⌘` + `Z`
Redo	`Ctrl` + `Shift` + `Z` or `Ctrl` + `Y`	`⌘` + `Shift` + `Z`

Typing several characters in a row into the same field counts as a single step. The history covers the last 50 steps and lasts as long as the editor is open. When the cursor is in a text field, the shortcuts act on the text field itself.

Confirmation dialogs

Before the editor discards anything, it asks for confirmation and names the consequences.

Delete state shows how many outputs of other states point to this state and lose their target as a result. If it is the start state, the dialog points out that the flow then has no entry point.
Change type (Standard, Forward, Hang up) lists what gets lost, such as outputs, conditions, allowed tools or the forward number. Switching the type back later does not restore them.
Import flow points out that the import replaces every state in the draft.

You can reverse all three actions afterwards with Undo.

States

A flow consists of states – the steps of the conversation. A state carries its own instructions, permitted tools, and transitions to subsequent states. Two additional points end the conversation:

Forwarding

Connects the call to an external phone number (e.g. to a human).

Hanging up

Ends the call.

Transitions and conditions

A state has outputs – named, ordered transitions to subsequent states. Each output is tied to a condition:

a tool that was called in the state,
an expected response code (the result of the tool),
optionally negated (“does not apply”).

While running, the agent checks the outputs in their order. The first matching transition determines the subsequent state.

No response code, no transition. If a tool does not trigger a declared response code, the agent stays in the current state. This keeps you in control of the conversation’s course.

Example

[Greeting & request]
   ── classify → "termin"    →  [Book appointment]
   ── classify → "sonstiges" →  [Forward: to practice]

[Book appointment]
   ── book_appointment → "ok"        →  [Hang up: Farewell]
   ── book_appointment → "kein_slot" →  [Book appointment]

Tools in a state

For each state, you define which tools the agent may use there. They come from three categories (details under Integrations & Tools):

Built-in tools – platform-native and configuration-free, such as classify for sorting the request. The categories become response codes for your transitions.
Connector tools – business actions such as “book appointment” or “look up patient” that go to your system via a connector (e.g. planorg PVS).
MCP tools – tools of a connected MCP server.

classify, transfer, and hang-up work fully. Connector-tool execution is live for the connected systems (MCP servers, planorg PVS, demo connectors).

State instructions

Each state can carry its own instructions that apply only there (in addition to the agent’s base instructions).

How to phrase good instructions – global and per step – is shown in the Prompting Guide.

Validation

The editor checks your flow continuously – for example whether all states are reachable and transitions are valid. Open issues are shown before you publish.

Versioning

Edit the draft

You always work on an editable draft.

Publish

On publishing, the draft is validated and stored as an immutable, numbered version.

Activate

You set a version as the live version. New calls use it immediately.

You can view earlier versions read-only and, if needed, reopen them as a draft.

Import and export flows

You can export a complete flow as a JSON file and import it elsewhere – handy for backing up, duplicating, or transferring flows between agents.

Export

In the flow editor, open the ⋮ menu (top right) and choose Export flow. The dialog shows the flow data as JSON. You can Copy it or save it as a JSON file with Download file. Export is also possible in the read-only version view.

Import

In the draft, open the same menu and choose Import flow. On the File tab, drag a previously exported JSON file into the dialog, or paste the JSON on the Text tab. With Import flow, the content replaces the current draft. Afterwards, check the result with a test call.

The import overwrites the existing draft. Already published versions remain untouched – the imported flow only becomes a version with the next publish. If you don’t like the result, bring back the previous draft with Undo.

You can import the same flow into any number of agents, even across tenants. Each agent manages the states of its draft separately from all others. To transfer a complete agent including instructions and connectors, use the agent export.

Structure of an export file

The file contains a flow object with:

startStateId – ID of the start state.
statesOrder – order of the states.
states – the states, one key per state ID. A state carries:
- type – REGULAR, FORWARD, or HANGUP.
- name – display name.
- stateInstructions – the instructions of the state.
- allowedTools – permitted tools (for REGULAR).
- outputsOrder / outputs – the outputs. Each output has a target (transitionTo) and conditions made of tool, responseCode, and isNegated.
A FORWARD state additionally carries the target phone number, a HANGUP state only a name and instructions.

Example

An exported flow (excerpt from the demo agent “Forderungsmanagement”):

{
  "flow": {
    "startStateId": "3b3aeb6f-3f07-4a7d-9e72-29ec1c728179",
    "statesOrder": [
      "3b3aeb6f-3f07-4a7d-9e72-29ec1c728179",
      "5ea95814-f003-4497-ab48-b7198ff6e4b1",
      "1d206d25-7529-407c-a29f-f516d66d2866",
      "ebc687d6-ed86-4ac8-b6ab-412061367298"
    ],
    "states": {
      "3b3aeb6f-3f07-4a7d-9e72-29ec1c728179": {
        "type": "REGULAR",
        "name": "S1 Begrüßung & Identifikation",
        "stateInstructions": "Begrüße den Anrufer und frage nach Geburtsdatum und Kundennummer. Frage so lange nach, bis beides genannt wurde.",
        "allowedTools": ["verify_customer"],
        "outputsOrder": ["0ee3293b-6e72-4472-9cb1-5a7f48a7b460"],
        "outputs": {
          "0ee3293b-6e72-4472-9cb1-5a7f48a7b460": {
            "name": "Ausgang 1",
            "transitionTo": "5ea95814-f003-4497-ab48-b7198ff6e4b1",
            "conditions": [
              { "tool": "verify_customer", "responseCode": "CUSTOMER_VERIFIED", "isNegated": false }
            ]
          }
        }
      },
      "5ea95814-f003-4497-ab48-b7198ff6e4b1": {
        "type": "REGULAR",
        "name": "S2 Saldo mitteilen & Absicht klären",
        "stateInstructions": "Rufe den offenen Betrag ab und lies ihn samt Rechnungsgrund und Fälligkeit vor. Frage, ob eine Ratenzahlung gewünscht ist.",
        "allowedTools": ["get_balance", "classify"],
        "outputsOrder": ["3477d025-58a5-4eb8-ae38-7369ada2ed13"],
        "outputs": {
          "3477d025-58a5-4eb8-ae38-7369ada2ed13": {
            "name": "Ausgang 1",
            "transitionTo": "1d206d25-7529-407c-a29f-f516d66d2866",
            "conditions": [
              { "tool": "classify", "responseCode": "Ratenzahlung gewünscht", "isNegated": false }
            ]
          }
        }
      },
      "1d206d25-7529-407c-a29f-f516d66d2866": {
        "type": "REGULAR",
        "name": "S3 Ratenplan aushandeln",
        "stateInstructions": "Frage nach Wunsch-Ratenanzahl ODER Wunschrate. Lies den Plan vor und hole ein klares Ja ein, bevor du verbindlich vereinbarst.",
        "allowedTools": ["propose_installment_plan", "agree_installment_plan"],
        "outputsOrder": ["0ac15add-b8f1-4f38-8c84-4b46352b2141"],
        "outputs": {
          "0ac15add-b8f1-4f38-8c84-4b46352b2141": {
            "name": "Ausgang 1",
            "transitionTo": "ebc687d6-ed86-4ac8-b6ab-412061367298",
            "conditions": [
              { "tool": "agree_installment_plan", "responseCode": "AGREEMENT_CONFIRMED", "isNegated": false }
            ]
          }
        }
      },
      "ebc687d6-ed86-4ac8-b6ab-412061367298": {
        "type": "HANGUP",
        "name": "Verabschiedung",
        "stateInstructions": "Fasse das Ergebnis in einem Satz zusammen, bedanke dich und verabschiede dich."
      }
    }
  }
}

Getting Started

Agents & Conversations

Integrations & Tools

Analysis & Administration

Build Conversation Flows

The flow editor

Undo and redo

Confirmation dialogs

States

Forwarding

Hanging up

Transitions and conditions

Example

Tools in a state

State instructions

Validation

Versioning

Import and export flows

Structure of an export file

Example

​The flow editor

​Undo and redo

​Confirmation dialogs

​States

Forwarding

Hanging up

​Transitions and conditions

​Example

​Tools in a state

​State instructions

​Validation

​Versioning

​Import and export flows

​Structure of an export file

​Example

The flow editor

Undo and redo

Confirmation dialogs

States

Transitions and conditions

Example

Tools in a state

State instructions

Validation

Versioning

Import and export flows

Structure of an export file

Example