Workflow Troubleshooting Guide

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:

1. Go to the agent's page
2. Click the three-dot menu (⋮) in the top right corner
3. Select "Show logs"
4. 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:

1. Knowledge Base is built: Click "Build" after adding/changing content
2. Knowledge Base is linked: Select it in the agent's Database section
3. 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:

1. Save your changes
2. Click "Stop" if agent is running
3. 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:

1. Switch to a more stable LLM model (for example, Llama models tend to produce fewer repeated greetings)
2. 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.

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:

1. Playground: Test individual conversations
2. Session Logs: Analyze actual conversation flow
3. Prompt Logs: Debug agent reasoning
4. Unit testing: Test each state individually
5. 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:

1. Save changes
2. Stop the agent
3. 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:

1. Create the Knowledge Base: Upload sources and click "Build"
2. Link to agent: Select KB in agent's Database section
3. 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:

1. Go to agent's Advanced Settings
2. Open Set Environment Variables
3. Add new parameter:
   • Key: START_PHRASE
   • Value: Your greeting message
4. Save and restart the agent

Related Resources

• AI Agent Tutorial
• Tools and Skills
• Knowledge Base Setup
• Session Monitoring
• YAML Syntax Guide