Workflow: Define conversation flow and business logic with state machines

Workflow configuration defines the conversation flow, states, and business logic of your agent using a state machine approach. This is the most complex part of agent setup and typically requires experimentation.

Prerequisites

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

When to Use Different Workflow Complexity

Simple Workflows (1-2 states)

Best for:

• Basic use cases requiring quick deployment
• Modern LLMs that follow instructions well
• Scenarios where flexibility is more important than strict control

Advantages:

• More intelligent, flexible agent behavior
• Can handle unexpected responses naturally
• Easier to maintain and modify

Complex Workflows (3+ states)

Best for:

• Highly regulated environments requiring exact compliance
• Processes with strict sequential requirements
• Legacy systems requiring predictable behavior

Advantages:

• Strict control over conversation flow
• Predictable, script-like behavior
• Clear audit trail of conversation stages

Disadvantages:

• Can become rigid and script-like
• Difficult to handle unexpected responses
• More complex to configure and maintain

Basic Workflow Structure

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

Key Components

1. States: Different stages or steps in your workflow
2. Processes: Groups of related states
3. Transitions: Rules for moving between states
4. Tools: Actions your agent can perform

Basic Structure Template

- process_name: YourProcessName
  name: StateName
  kind: StateConfig
  description: |
    Detailed instructions for the agent in this state
  state_scenarios:
    - next_state: NextStateName
      description: "When to transition to this state"
      transition_name: action_name

Creating a Basic State

Each state in your workflow starts with a dash (-) and contains several key pieces of information:

- process_name: CustomerSupport
  name: Greeting
  kind: StateConfig
  description: |
    Steps for greeting the customer and identifying their needs.

Essential Fields for Every State

Field	What it does	Example	Required
process_name	Names the process this state belongs to	CustomerSupport	Yes
name	Gives this specific state a unique name	Greeting	Yes
kind	Always set to "StateConfig"	StateConfig	Yes
description	Detailed instructions for this state	See below	Yes
init_state	Marks this as the starting state	true	For first state only
final_state	Marks this as an ending state	true	For ending states

Complete Example: Debt Collection Workflow

# Initial verification state
- process_name: DebtCollection
  name: Verification
  kind: StateConfig
  init_state: true
  description: |
    ## Steps to follow
      1. Greet the person politely
      2. Verify their identity
      3. Do NOT discuss the debt until identity is confirmed
    
    ## Important Guidelines
      - Be professional and respectful
      - Only proceed if identity is confirmed
      - If wrong person, apologize and end conversation
    
    ## Example dialogues
      ### Successful verification
        Agent: Hello! Am I speaking with John Smith?
        Human: Yes, this is John
        Agent: <Action: verify_identity>
      
      ### Wrong person
        Agent: Hello! Am I speaking with John Smith?
        Human: No, wrong number
        Agent: I apologize for the inconvenience. Have a great day!
  
  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage
      - FinishSession
  
  state_scenarios:
    - next_state: Collection
      transition_name: verify_identity
      description: "Identity confirmed, proceed to collection"
    
    - next_state: EndConversation
      transition_name: end_wrong_person
      description: "Wrong person, end politely"

# Main collection state
- process_name: DebtCollection
  name: Collection
  kind: StateConfig
  description: |
    ## Steps to follow
      1. Explain the reason for contact
      2. Ask about the overdue payment
      3. Understand their situation
      4. Negotiate payment arrangement
      5. Confirm next steps
    
    ## Important Guidelines
      - Use soft collection approach
      - No threats or aggressive language
      - Be understanding of their situation
      - Offer flexible payment options
    
    ## Example dialogues
      ### Customer needs time
        Agent: I'm calling about your payment from 30 days ago. 
                Can you help me understand the situation?
        Human: I had unexpected medical expenses
        Agent: I understand that can be challenging. 
                When would you be able to make a payment?
        Human: I can pay half next week
        Agent: <Action: schedule_payment>
  
  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage
      - SingleSearchFAQ
      - SchedulePayment
      - SendPaymentReminder
  
  state_scenarios:
    - next_state: PaymentScheduled
      transition_name: schedule_payment
      description: "Payment arrangement made"
    
    - next_state: ScheduleCallback
      transition_name: request_callback
      description: "Customer needs more time to decide"
    
    - next_state: Escalation
      transition_name: transfer_to_operator
      description: "Customer requests human operator"

# Final state
- process_name: DebtCollection
  name: PaymentScheduled
  kind: StateConfig
  final_state: true
  description: |
    ## Steps to follow
      1. Confirm the payment details
      2. Thank them for their cooperation
      3. End the conversation professionally
    
    ## Example dialogue
      Agent: Perfect! I've scheduled your payment of $500 for next Tuesday. 
             You'll receive a confirmation SMS. Thank you for working with us!
      Human: Thank you
      Agent: Have a great day!
  
  available_tools:
    SingleStatefulOutboundAgent:
      - FinishSession

Advanced Workflow Features

Skills Initialization and Finalization

init_skills:
  UpdateOutcomeStatusSkill:
    new_outcome_status: "COLLECTION_STARTED"
  LoadCustomerDataSkill:
    customer_id: "12345"

final_skills:
  SendConfirmationEmail: {}

Purpose:

• init_skills: Execute actions when entering a state (for example, load customer data)
• final_skills: Execute actions when leaving a state (less commonly used)

⚠️ Important: Skills can be parameterized with specific values for different states.

Prompt Overrides

Customize the agent's behavior for specific states:

prompt_fields_override:
  speech_style_extra: |
    Be extra empathetic in this state.
    Use softer language and show understanding.
  identity_override: |
    You are now in "good cop" mode. Be understanding and helpful.

Use Case: Change agent personality for specific situations (for example, switch from polite to more assertive after multiple failed attempts).

Process Dependencies

enable_at: "MainProcess.VerificationComplete"

Purpose: Start dependent processes only after certain conditions are met. For example, an information-sharing process might only become available after customer verification.

Repeat Limits

repeat_limit: 4
repeat_limit_next_state: "EscalationState"

Purpose: Automatically transition to another state after a certain number of attempts in the current state.

How State Transitions Work

From User Perspective

1. Agent follows instructions in current state
2. Based on user responses, agent takes actions
3. Certain actions trigger automatic state transitions
4. Agent behavior changes according to new state

Important Notes

• The agent doesn't "know" about states
• Transitions like verify_identity appear as normal actions to the agent
• The platform handles actual state changes behind the scenes
• State changes are transparent to end users

Choosing the Right Number of States

Key Principle

Balance between control and intelligence

Fewer States (Recommended for Modern LLMs)

Pros:

• More intelligent, flexible agent behavior
• Can handle unexpected responses naturally
• Easier to maintain and debug

Cons:

• Less predictable behavior
• Requires more sophisticated prompting

More States

Pros:

• Strict control over conversation flow
• Predictable behavior
• Clear audit trail

Cons:

• Can become script-like
• Difficult to handle unexpected responses
• Complex configuration and maintenance

Example Evolution

A collection workflow initially had 6 states (ask reason → ask when → ask how → confirm), but was simplified to 2 states (verification → collection) for better performance. The single collection state now handles all payment discussion naturally.

Testing and Debugging Workflows

Testing Strategy

1. Unit Test States: Test each state individually
2. Integration Test: Test complete workflow paths
3. Edge Case Testing: Test unexpected user responses
4. Load Testing: Test with multiple concurrent conversations

Debugging Tools

• Playground: Test individual conversations
• Session Logs: Analyze actual conversation flow
• Prompt Logs: See exactly what the agent received and generated

Related Resources

• AI Agent Tutorial
• Tools and Skills
• Knowledge Base Setup
• Session Monitoring
• Workflow Configuration Guide