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

YAML Basics - Quick Reference

YAML is a human-readable format used for configuration files. Here's what you need to know:

Indentation: YAML uses spaces (not tabs) to show structure
- Always use consistent indentation (2 spaces recommended)
- Items at the same level must have the same indentation
Key-Value Pairs: Information is stored as keys and values
```
key: value
name: John Doe
age: 30
```
Lists: Use hyphens to create lists
```
fruits:
  - apple
  - banana
  - orange
```

Multi-line Text: Use the pipe character (|) for text with line breaks

description: |
  This is a long description
  that spans multiple lines.
  Line breaks will be preserved.

Nesting: Combine indentation with keys and lists

person:
  name: John Doe
  contact:
    email: john@example.com
    phone: 555-1234
  hobbies:
    - reading
    - hiking

Comments: Add notes with the hash symbol

# This is a comment
name: John # This is an inline comment

Common Mistakes to Avoid:
- Mixing tabs and spaces (use only spaces)
- Inconsistent indentation
- Forgetting the space after colons
- Using special characters without quotes

Key Concepts

States

Different phases of the conversation, each with specific goals and behaviors. Each state defines:

What the agent should do
What tools are available
How to transition to other states

Transitions

Rules for moving between states based on user responses or actions. Transitions are triggered by specific agent actions.

Tools

Available actions the agent can perform in each state, including:

Static tools (built into platform)
Custom tools from Skill Groups

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

States: Different stages or steps in your workflow
Processes: Groups of related states
Transitions: Rules for moving between states
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

Core Configuration Fields

1. Process and State Identification

- 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. 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 user intent
  
  ## Example dialogues
    ### Scenario 1
      Agent: Hello! How can I help you today?
      Human: I need help with my application
      Agent: <Action: provide_assistance>

Best Practices for Descriptions:

Use clear, step-by-step instructions
Include important guidelines and constraints
Provide dialogue examples for main scenarios
Be specific about expected behaviors

3. Available Tools

Define which actions the agent can perform in each state:

available_tools:
  SingleStatefulOutboundAgent:  # The agent type (from your configuration)
    - SendChatMessage          # Send a message to the user
    - SingleSearchFAQ          # Search the knowledge base
    - CreateJiraTicket         # Create a support ticket

Common Tool Types

Tool	What it does
`SendChatMessage`	Sends a message to the user
`SuggestChatMessage`	Suggests a message (for human operators)
`FinishSession`	Ends the conversation
`SingleSearchFAQ`	Search the knowledge base
`SchedulePayment`	Schedule payment arrangements
`TransferToOperator`	Transfer to human operator

Tool Categories

Communication: SendChatMessage, FinishSession
Knowledge: SingleSearchFAQ, SearchDatabase
External Actions: CreateJiraTicket, SendEmail, SchedulePayment
Custom Tools: From Skill Groups (varies by configuration)

4. State Transitions

Define how and when to move between states:

state_scenarios:
  - next_state: CollectionState
    transition_name: verify_identity
    description: "Move to collection after confirming identity"
    attached_tools:
      - SendVerificationTemplate
  
  - next_state: ScheduleReminder
    transition_name: begin_schedule_reminder
    description: "Schedule a callback if user is busy"

Transition Fields Explained

Field	What it does	Example	Required
`next_state`	The state to move to	`CollectingInformation`	Yes
`transition_name`	A name for this transition	`CustomerGreeted`	Yes
`description`	When to make this transition	`"Move to information collection..."`	Yes

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 (e.g., 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 (e.g., 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

Agent follows instructions in current state
Based on user responses, agent takes actions
Certain actions trigger automatic state transitions
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.

Best Practices

Start Simple and Iterate

Begin with 1-2 states and add complexity only when needed
Test simple version thoroughly before adding states
Most use cases work well with minimal states

Example Evolution:

Original (6 states): ask_reason → ask_when → ask_how → confirm → schedule → close
Simplified (2 states): verification → collection

Result: Better performance, more natural conversations, easier maintenance

Clear State Purpose

Each state should have one clear goal
Avoid states that try to do too many things
Use descriptive state names

Good vs Poor State Design:

✅ Good State Design:
- Verification: Confirm identity before proceeding
- Collection: Handle payment discussion and arrangement
- Escalation: Transfer to human operator

❌ Poor State Design:
- State1: Do various things depending on situation
- ProcessingState: Handle multiple different processes

Comprehensive Examples

Provide dialogue examples for main scenarios
Examples strongly influence agent behavior
Include both successful and problematic interactions

Explicit Transitions

Make transition conditions clear and unambiguous
Avoid overlapping transition conditions
Test all possible transition paths

Clear vs Problematic Conditions:

❌ Problematic:
- verify_identity: "When identity is confirmed"
- proceed_to_collection: "When ready to discuss payment"

✅ Clear:
- verify_identity: "When customer confirms they are the correct person"
- end_wrong_person: "When customer says they are not the target person"

Error Handling and Fallbacks

Always include paths for unexpected responses
Plan for edge cases and user confusion
Have fallback states for error conditions

Always Include Fallback Paths:

state_scenarios:
  - next_state: MainFlow
    transition_name: normal_progression
    description: "Standard flow continuation"
  
  - next_state: Clarification
    transition_name: handle_confusion
    description: "When user response is unclear or unexpected"
  
  - next_state: Escalation
    transition_name: request_human
    description: "When user explicitly requests human agent"

Plan for User Confusion:

description: |
  If the user's response is unclear or doesn't match expected answers:
  1. Politely ask for clarification
  2. Provide examples of expected responses
  3. If still unclear after 2 attempts, escalate to human operator

Use Templates

Leverage template library when available
Don't build complex workflows from scratch
Adapt existing templates to your use case

Common Issues & Solutions

Agent stuck in loop

Problem: Agent repeats the same messages or actions continuously.

Solution: Check transition conditions and add escape paths. Make sure state transitions have clear, non-overlapping conditions. Review your workflow for:

Circular transitions without exit conditions
Missing fallback states
Overlapping transition triggers

Example Fix:

state_scenarios:
  - next_state: ErrorHandling
    transition_name: escape_loop
    description: "Fallback when user gives unexpected response"

Unexpected state transitions

Problem: Agent moves to wrong states or transitions don't work as expected.

Solution: Review action names and transition_name values. Ensure they match exactly between state configurations. Check for:

Typos in transition_name fields
Case sensitivity issues
Missing transition definitions

Tool not found errors

Problem: Agent tries to use tools that aren't available, causing errors.

Solution: Verify available_tools configuration. Make sure all tools referenced in descriptions are listed in the available_tools section for each state where they're needed.

Example:

available_tools:
  SingleStatefulOutboundAgent:
    - SendChatMessage
    - SingleSearchFAQ  # Make sure this matches your knowledge base tool
    - FinishSession

Agent shows "Error" status

Problem: Agent won't start and shows Error status.

Solution:

Go to the agent's page
Click the three-dot menu (⋮) in the top right corner
Select "Show logs"
Click "Copy logs" and send to FlameTree support

Common causes:

YAML syntax errors in workflow
Missing required fields
Invalid tool or skill names
Broken integrations

Knowledge Base not working

Problem: Agent can't access knowledge base information.

Solution: Ensure all three requirements are met:

Knowledge Base is built: Click "Build" after adding/changing content
Knowledge Base is linked: Select it in the agent's Database section
Search tool is declared: Add SingleSearchFAQ to available_tools in your workflow

Example:

available_tools:
  SingleStatefulOutboundAgent:
    - SendChatMessage
    - SingleSearchFAQ  # Required for knowledge base access

Inconsistent behavior

Problem: Agent responses vary unpredictably or don't follow instructions.

Solution: Add more specific examples and guidelines. The agent learns primarily from the examples you provide in state descriptions. Include:

Detailed step-by-step instructions
Multiple dialogue examples
Clear behavioral guidelines
Specific formatting requirements

Changes don't take effect

Problem: Agent continues old behavior after saving changes.

Solution: Restart the agent after making changes:

Save your changes
Click "Stop" if agent is running
Click "Start" to reload with new configuration

Restart required for:

Workflow changes
Prompt modifications
Environment variables
Knowledge base updates
Integration changes

Repeated greetings

Problem: Agent sends greeting messages multiple times during conversation.

Solution:

Switch to a more stable LLM model (e.g., Llama models tend to produce fewer repeated greetings)

Define behavior explicitly in workflow by adding instructions like:

description: |
  Don't greet humans during sessions.
  Only send greeting once at the start.

Incomplete answers to long questions

Problem: Agent gives short or incomplete responses to complex questions.

Solution: Add explicit guidance in workflow descriptions:

description: |
  When answering complex questions:
  - Break responses into short paragraphs or bullet points
  - If space runs out, indicate that the answer will be continued
  - Offer to send information in multiple parts if necessary

YAML indentation errors

Problem: Workflow won't save or agent won't start due to YAML format issues.

Solution: Follow YAML indentation rules:

Use only spaces (never tabs)
Use 2 spaces per indentation level
Keep consistent indentation at same level
Add space after colons (:)

Example:

- process_name: MyProcess
  name: MyState
  kind: StateConfig
  description: |
    This is properly indented.

Over-segmentation

Problem: Too many small states make the agent less intelligent and harder to maintain.

Solution: Combine related functionality into single states. Modern LLMs work better with fewer, more comprehensive states rather than many small ones.

Under-specification

Problem: Vague descriptions lead to unpredictable behavior.

Solution: Be very specific about what the agent should do in each state. Include:

Clear step-by-step instructions
Specific examples
Expected user interactions
Error handling scenarios

Missing Examples

Agent behavior is inconsistent without examples. Include comprehensive dialogue examples for each scenario.

Complex First Attempts

Starting with complex workflows makes debugging difficult. Always start simple and iterate.

Inconsistent Tool Availability

Agent tries to use tools not available in current state. Carefully review available_tools for each state.

Testing and Debugging Workflows

Testing Strategy

Unit Test States: Test each state individually
Integration Test: Test complete workflow paths
Edge Case Testing: Test unexpected user responses
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

FAQ

How many states should I use?

Start with 1-2 states. Most use cases work well with minimal states. Add complexity only when needed for strict control or compliance requirements.

What's the difference between simple and complex workflows?

Simple workflows (1-2 states):

More intelligent and flexible behavior
Handle unexpected responses naturally
Easier to maintain and debug
Less predictable but more adaptive

Complex workflows (3+ states):

Strict control over conversation flow
Predictable, script-like behavior
Clear audit trail of stages
Can become rigid and difficult to modify

How do I handle unexpected user responses?

Always include fallback paths and error handling states. Use comprehensive examples in your state descriptions to guide the agent's behavior.

Best practices:

Add escape transitions in every state
Include examples of problematic interactions
Have a general error handling state
Use clear, unambiguous transition conditions

Can I change agent personality between states?

Yes, use prompt_fields_override to customize speech style or identity for specific states.

Example:

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.

What if my agent doesn't transition between states?

Check that transition_name values match exactly between states, and ensure transition conditions are clear and achievable.

Common issues:

Typos in transition names
Case sensitivity problems
Missing transition definitions
Overlapping conditions

How do I test my workflow?

Use multiple testing approaches:

Playground: Test individual conversations
Session Logs: Analyze actual conversation flow
Prompt Logs: Debug agent reasoning
Unit testing: Test each state individually
Integration testing: Test complete workflow paths

Should I build my workflow from scratch?

No, leverage existing templates when available. Most partners work with FlameTree support for initial workflow configuration.

When do I need to restart the agent?

Restart is required for these changes:

Workflow modifications (StateConfig, transitions, tools)
Agent prompts (Identity, Task, Speech Style)
Environment variables
Knowledge base updates (after Build)
Integration changes
Skill Group modifications

How to restart:

Save changes
Stop the agent
Start the agent again

What are the YAML indentation rules?

Follow these rules to avoid syntax errors:

Use only spaces (never tabs)
2 spaces per indentation level
Consistent indentation at same level
Space after colons (key: value)
Proper nesting with indentation

Example:

- process_name: MyProcess
  name: MyState
  kind: StateConfig
  description: |
    Multi-line description
    with preserved line breaks

How do I connect a knowledge base to my agent?

Three mandatory steps:

Create the Knowledge Base: Upload sources and click "Build"
Link to agent: Select KB in agent's Database section
Add search tool: Include SingleSearchFAQ in workflow available_tools

Example:

available_tools:
  SingleStatefulOutboundAgent:
    - SendChatMessage
    - SingleSearchFAQ  # Required for KB access
    - FinishSession

How do I set the initial greeting phrase?

Use environment variables to set the first message:

Go to agent's Advanced Settings
Open Set Environment Variables
Add new parameter:
- Key: START_PHRASE
- Value: Your greeting message
Save and restart the agent

Working with FlameTree Support

Most partners work with FlameTree support for initial workflow configuration because:

Workflow design requires understanding platform capabilities
Complex business logic needs careful state design
Integration with external systems requires coordination
Testing and optimization benefit from expert guidance

Don't hesitate to reach out for support when designing complex workflows or when agent behavior doesn't match expectations.

Prerequisites​

Key Concepts​

States​

Transitions​

Tools​

When to Use Different Workflow Complexity​

Simple Workflows (1-2 states)​

Complex Workflows (3+ states)​

Basic Workflow Structure​

Key Components​

Basic Structure Template​

Creating a Basic State​

Essential Fields for Every State​

Core Configuration Fields​

1. Process and State Identification​

2. State Description​

3. Available Tools​

Common Tool Types​

Tool Categories​

4. State Transitions​

Transition Fields Explained​

Complete Example: Debt Collection Workflow​

Advanced Workflow Features​

Skills Initialization and Finalization​

Prompt Overrides​

Process Dependencies​

Repeat Limits​

How State Transitions Work​

From User Perspective​

Important Notes​

Choosing the Right Number of States​

Key Principle​

Fewer States (Recommended for Modern LLMs)​

More States​

Example Evolution​

Best Practices​

Start Simple and Iterate​

Clear State Purpose​

Comprehensive Examples​

Explicit Transitions​

Error Handling and Fallbacks​

Use Templates​

Common Issues & Solutions​

Testing and Debugging Workflows​

Testing Strategy​

Debugging Tools​

FAQ​

Related Resources​

Working with FlameTree Support​

Prerequisites

Key Concepts

States

Transitions

Tools

When to Use Different Workflow Complexity

Simple Workflows (1-2 states)

Complex Workflows (3+ states)

Basic Workflow Structure

Key Components

Basic Structure Template

Creating a Basic State

Essential Fields for Every State

Core Configuration Fields

1. Process and State Identification

2. State Description

3. Available Tools

Common Tool Types

Tool Categories

4. State Transitions

Transition Fields Explained

Complete Example: Debt Collection Workflow

Advanced Workflow Features

Skills Initialization and Finalization

Prompt Overrides

Process Dependencies

Repeat Limits

How State Transitions Work

From User Perspective

Important Notes

Choosing the Right Number of States

Key Principle

Fewer States (Recommended for Modern LLMs)

More States

Example Evolution

Best Practices

Start Simple and Iterate

Clear State Purpose

Comprehensive Examples

Explicit Transitions

Error Handling and Fallbacks

Use Templates

Common Issues & Solutions

Testing and Debugging Workflows

Testing Strategy

Debugging Tools

FAQ

Related Resources

Working with FlameTree Support