State Configuration

Workflow files are written in YAML format. Each workflow consists of states that define different stages of a conversation.

This article covers:

• Basic state structure
• Main state components
• Guidelines for writing clear state configurations

For more information about what a state is, and how it works, refer to the Workflow Basics article.

---

Prerequisites

• Basic understanding of state machines and conversation flow
• Familiarity with YAML configuration syntax
• Agent Identity, Speech Style, and Task already configured

Basic State Structure

important

The YAML examples in this article illustrate concepts and are not ready-to-use configurations. For complete setup instructions, see Advanced Mode article

The example below shows the basic structure of a state in a single-state workflow.

- process_name: SalesProcess
  name: SalesSupport
  kind: StateConfig
  init_state: true

  description: |
    - Answer questions about products
    - Collect contact info
    - Offer call scheduling if the humam is interested
    - Use FAQ and Knowledge Base when relevant

  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage
      - FinishSession
      - SingleSearchFAQ

A state consists of three main parts:

• Process and state identification block

• State description

• Available tools

State Fields Explained

The main state fields include:

Field	What it does	Example	Required
process_name	Names the process this state belongs to. Usually, one workflow contains one process, but more are possible if needed.	SalesProcess	Yes
name	Gives the state a unique name. — use descriptive names.	SalesSupport	Yes
kind	Defines the object type. Always set to StateConfig.	StateConfig	Yes
init_state	Marks the starting state of the workflow.	true	Starting state only
final_state	Marks a state where the conversation can end.	true	Optional
description	Contains the instructions for this state.	See State Description	Yes

warning

Workflows must include exactly one init_state: true. Otherwise, the agent cannot start conversations

Below, all the state components are discussed in more detail.

1. Process and State Identification

Each workflow consists of states. Each state consists of several mandatory fields that identify the process and the state:

- process_name: MyWorkflow        # Groups related states together
  name: InitialState             # Unique state identifier
  kind: StateConfig              # Always "StateConfig"
  init_state: true              # Marks the starting state (only one per workflow)
  final_state: true             # Marks ending states (can have multiple)

2. State Description

The description field contains detailed instructions for the agent. Typically, it is a good idea to have the following parts of the description:

• Steps to follow: write clear step-by-step instructions that tell your agent what to do in sequential order
• Important guidelines: these are not steps but important points for your agent to consider like where to look for information first, for example. This also includes agent limitations. Be specific about expected behaviors
• Example Dialogs: dialogs are very important for your agent. They show the agent the main scenarios and strongly influence its behavior. It is important to include both successful and problematic interactions

Use the pipe character (|) to write multiple lines:

description: |
  ## Steps to follow
    1. First, do this specific action
    2. Then, check for these conditions
    3. Route to appropriate next state
  
  ## Important Guidelines
    - Always be polite and professional
    - Use knowledge base for answering questions
    - Don't make assumptions about human intent
  
  ## Example dialogues
    ### Scenario 1
      Agent: Hello! How can I help you today?
      Human: I need help with my application
      Agent: <Action: provide_assistance>

Make sure you don't have conflicting instructions in the description. For example, "Do not provide any advice" and "Provide advice based on the knowledge base".

tip

In the workflow, it's better to call your customers humans. Practical tests show that it makes agent behavior more efficient

3. Available Tools

Use the available_tools section to specify which tools the agent can use in a state.

available_tools:
  SingleStatefulOutboundAgent:  # The agent type (from your configuration)
    - SendChatMessage          # Send a message to the customer
    - SingleSearchFAQ          # Search the knowledge base
    - FinishSession         # Finishes session

important

Most tools are optional. But for your text agents, the SendChatMessage tool is mandatory. Without this tool, your agent will not be able to send messages to customers

Other important tools to consider:

• SingleSearchFAQ — Most AI agents have knowledge bases. For the agent to use the knowledge sources, you will need this tool.
• FinishSession — Allows the agent to finish the session. Without this tool, the session by default will finish in 72 hours.

For details on using tools in workflows, see Tools & Skills section.

State Design Tips

Give each state one clear goal: Avoid states that try to do too many things or the instructions that are too vague

Clear ✅	Problematic ❌
Verification: Confirm identity before proceeding Collection: Handle payment discussion and arrangement Escalation: Transfer to human operator	State1: Do various things depending on situation ProcessingState: Handle multiple different processes

Write clear and focused instructions: Make sure the instructions in each state align with that state's purpose. Otherwise, the agent might behave inconsistently such as asnwer the same questions differently.

Clear ✅	Problematic ❌
Verification: Ask for the order number and confirm the human's identity before proceeding.	Verification: Confirm identity, explain refund policy, offer alternative products, and ask for feedback.

---

Next Steps

• Transitions Between States