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

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 current flow is downloaded as a JSON file. Export is also possible in the read-only version view.

Import

In the draft, open the same menu and choose Import flow. Pick a previously exported JSON file; its 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.

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

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

​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

States

Transitions and conditions

Example

Tools in a state

State instructions

Validation

Versioning

Import and export flows

Structure of an export file

Example