Skip to main content

Dialogue builder

The Dialogue Builder is where you design the conversation flow for your agent. Think of it as creating a map of different conversation scenarios and how your agent should navigate between them.

Understanding States​

A state represents a specific context or phase in a conversation. Each state has its own instructions, available actions, and rules that guide how your agent behaves.

Example States​

For a customer support agent, you might have states like:

  • Initial Greeting: Welcome the customer and identify their need
  • Billing Support: Handle billing questions and payment issues
  • Technical Support: Troubleshoot technical problems
  • Order Status: Look up and provide order information
  • Closing: End the conversation professionally

Creating States​

To add a new state:

  1. Open the Dialogue Builder tab
  2. Click Add Node
  3. Give your state a descriptive name
  4. Configure the state settings

State Configuration​

Each state includes:

Name and Description​

  • Name: Short, clear identifier (e.g., "Billing Support")
  • Description: Brief explanation of what happens in this state

Instructions​

The instructions tell your agent how to behave while in this state.

Example instructions for a "Billing Support" state:

You are helping the customer with billing questions.

Available information:
- Payment methods: Credit card, PayPal, bank transfer (Enterprise only)
- Billing cycle: Monthly or annual
- Refund policy: Full refund within 30 days

Your tasks:
- Answer questions about charges and billing
- Explain pricing and payment options
- Help update payment methods
- Process refund requests (use the request_refund action)

If the customer needs to speak about technical issues, transition to the Technical Support state.

Actions​

Select which actions the agent can use while in this state. This prevents the agent from performing inappropriate actions in certain contexts.

State-specific actions require strict state separation

Actions can only be assigned to specific states when strict state separation is enabled for your agent. When this setting is disabled, all actions are globally available to the agent in any state.

Example:

  • In "Billing Support" enable the request_refund action
  • In "Order Status" enable the lookup_order action
  • In "Initial Greeting" don't enable any actions, just have a conversation

Globally Accessible​

Toggle this ON if the agent should be able to reach this state from anywhere in the conversation.

Examples of globally accessible states:

  • "End conversation" - Customer can end the call anytime
  • "Transfer to human" - Customer can request human help anytime

Examples of states that should NOT be globally accessible:

  • "Process Payment" - Should only be accessible after collecting payment details
  • "Confirm Appointment" - Should only be accessible after scheduling details are gathered

Transitions​

Transitions define when your agent moves from one state to another. Each transition has:

Source and target​

  • Source: The state the agent is currently in
  • Target: The state the agent will move to

These are configured using the connector lines between the states in the dialogue builder.

Condition​

The condition that must be met for this transition to occur. Write this in natural language. Make sure you the condition is as explicit as possible for the best performance.

Example transition conditions:

  • "Customer asks about billing or payment"
  • "Customer requests to speak with a human agent"
  • "Technical issue is resolved"
  • "Customer wants to check order status"

How Transitions Work​

The agent evaluates transition conditions during the conversation and automatically moves to the appropriate state when conditions are met.

Example flow:

  1. Agent starts in "Initial Greeting"
  2. Customer says: "I have a question about my bill"
  3. Condition "Customer asks about billing" is met
  4. Agent transitions to "Billing Support" state
  5. Agent now follows "Billing Support" instructions

Building Your First Flow​

Here's a simple example for a customer support agent:

Step 1: Create Core States​

  1. Initial Greeting

    • Instructions: "Greet the customer and ask how you can help"
    • Globally Accessible: No
    • Tools: None

  2. Billing Support

    • Instructions: "Help with billing questions and payment issues"
    • Globally Accessible: Yes
    • Tools: request_refund, update_payment_method

  3. Technical Support

    • Instructions: "Help troubleshoot technical issues"
    • Globally Accessible: Yes
    • Tools: create_support_ticket

  4. Transfer to Human

    • Instructions: "Politely inform the customer you're connecting them with a human agent"
    • Globally Accessible: Yes
    • Tools: handover_to_human

Step 2: Define Transitions​

From Initial Greeting:

  • → Billing Support (Condition: "Customer mentions billing, payment, or charges")
  • → Technical Support (Condition: "Customer mentions technical issue or product not working")
  • → Transfer to Human (Condition: "Customer requests to speak with a human")

From Billing Support:

  • → Technical Support (Condition: "Issue is technical, not billing-related")
  • → Transfer to Human (Condition: "Customer requests human agent or issue is complex")

From Technical Support:

  • → Billing Support (Condition: "Issue is billing-related, not technical")
  • → Transfer to Human (Condition: "Customer requests human agent or issue is too complex")

Step 3: Test the Flow​

Use the Playground to test different scenarios:

  • Try asking billing questions and verify the agent transitions correctly
  • Ask technical questions and see if it moves to the right state
  • Request a human agent from different states to test globally accessible transitions

State Switching Behavior​

In the agent's Details, you can configure state switching behavior by enabling or disabling strict state separation:

Strict mode enabled​

  • Agent must follow defined transitions explicitly
  • More predictable and controlled flow
  • Better for complex workflows with many states

Strict mode disabled​

  • Agent can move between states more freely
  • Easier to set up for simple agents
  • More natural conversation flow
Start Simple

Begin with 3-5 states maximum and flexible mode. Add more states and enable strict mode as you identify specific conversation patterns.

Using variables in states​

You can reference variables within state instructions to personalize the conversation:

Example:

You are helping {customer_name} with their order.

Order details:
- Order number: {order_number}
- Status: {order_status}

Provide helpful updates and answer any questions they have.

Best practices​

Keep states focused​

Each state should have a single, clear purpose. If you notice that the agent's performance is degrading because a state is doing too much, split it into multiple states.

Use clear transition conditions​

Write conditions in plain language that clearly describe when the transition should happen:

✅ Good: "Customer asks about billing or mentions charges" ❌ Too vague: "Customer has a question"

Test all paths​

Make sure you test transitions between all your states. It's easy to create states that agents can't reach.

Plan for edge cases​

Include states and transitions for:

  • Customer wants to end the conversation
  • Customer asks something unrelated
  • Customer becomes frustrated

Don't overcomplicate​

Start with a simple flow and add complexity only when you identify specific needs through testing.

Visual designer​

The Dialogue Builder includes a visual workflow designer:

  • Nodes represent states
  • Edges between the nodes represent transitions
  • Click on nodes or edges to edit them

Next Steps​

After building your dialogue flow:

  • Configure actions that states can use
  • Set up guardrails to ensure safe conversations
  • Test your flow extensively in the Playground
  • Set up evaluation rules to automatically assess conversation quality