AI Agents Troubleshooting Guide

How do I debug agent workflows?

For debugging workflows:

• Use built-in logging and test with sample user inputs
• Check YAML for indentation or syntax errors
• Verify all required tools and skills are declared
• Restart the agent after configuration changes
• If the agent shows "Error" status, check logs via the three-dot menu → Show logs → Copy logs

Which parameter is used to set the first message?

To configure the initial greeting phrase in a Flametree AI agent, use the START_PHRASE parameter, which is set via the environment variables mechanism.

Steps:

1. Go to the AI agent card
2. Click Advanced Settings → Set Environment Variables
3. Click the plus icon and create:
   • Key: START_PHRASE
   • Value: Your greeting phrase
4. Click Save

What are the indentation rules in AI agent fields?

Requirements:

• Use spaces only - tabs are prohibited
• Use 2 spaces per indentation level (recommended)
• All items at the same level must have identical indentation
• Nesting is indicated by left-hand indentation

Example:

- process_name: CustomerSupport
  name: Greeting
  kind: StateConfig
  description: |
    This is a multi-line description
    with preserved line breaks.

Common mistakes:

• Using tabs instead of spaces
• Missing space after : in a key
• Inconsistent indentation at the same level

Can I use different voices in TTS (Text-to-Speech)?

Yes, Flametree supports TTS integration with Azure Speech and ElevenLabs.

Required parameters:

Parameter	Description	Example
type	Provider type	azure_speech or elevenlabs
region	Azure region (Azure only)	eastus
voice	Voice identifier	en-US-DavisNeural, Rachel
api_url	Provider API endpoint	Provider-specific
api_key	Authentication key	Your API key

Finding voices:

• Azure Speech: Visit Azure documentation
• ElevenLabs: Register at ElevenLabs → Voice Library

How to choose a different LLM?

Basic selection:

1. Open the AI agent card
2. In Models - LLM field, select the desired model
3. For external models, set up manual integration

Custom/external models:

1. Go to Settings > Connectivity.
2. Open AI Models > Large Language Model (LLM).
3. Configure the following parameters:

Parameter	Description	Example
model_name	Model identifier	gpt-4, gpt-3.5-turbo
api_url	API endpoint URL	Provider-specific
api_key	Authorization token	Your API key
temperature	Response creativity (0-1)	0.7 for balanced

Temperature values:

• 0.0 - Deterministic answers
• 0.7 - Balanced variation
• 1.0 - Maximum creativity

Model comparison:

Model	Provider	Advantages
gpt-4	OpenAI	High accuracy, complex queries
gpt-3.5-turbo	OpenAI	Faster, cheaper, basic tasks
mistral-7b	HuggingFace	Lightweight, local hosting
Qwen-2-72B	Alibaba	Cost-effective, good with KBs

When is a restart required after making changes?

Restart is required for changes that affect runtime behavior:

Change	Restart Required	Reason
Agent prompt (Identity, Task, Style)	✅	Instructions must be reloaded
Workflow modifications	✅	Process must be recompiled
Integration updates	✅	Settings must be recompiled
Environment variables	✅	Environment needs reinitialization
Knowledge base updates	✅	After Build/Rebuild
Name/description changes	❌	No runtime impact

Manual restart process:

1. Click Save → Stop → Start

❗ Important: Changes may not take effect until the agent is restarted, even after saving.

How to fix repeated greetings?

Solutions:

1. Switch to a more stable LLM model (for example, Llama)
2. Define explicit behavior in workflow:
   • Add instruction: "Don't greet humans during sessions"
   • Place in relevant state's description field

How to handle incomplete answers to long questions?

Add explicit guidance in the Workflow description field:

• Break responses into short paragraphs or bullet points
• If space runs out, indicate continuation
• Offer to send information in multiple parts

💡 Note: Clearly instruct the agent on structuring long-form responses in your workflow configuration.

How to connect tools and skills to an AI agent?

Three steps required:

1. Connect Skill Group:

AI Agents → Open your agent's card → Skill Groups → Add Skill Group

2. Declare Tools in workflow:

A Tool is a Python function that the AI agent calls to perform a specific action (for example, sending a message, scheduling a meeting).

Inside the relevant state (StateConfig) in the workflow YAML file, list the tools under available_tools.

available_tools:
  SingleStatefulOutboundAgent:
    - SendChatMessage
    - FinishSession

Where to declare:

• In every state where the AI agent should have access to the tool(s).
• Under the available_tools key.

3. Declare Skills in workflow:

A Skill defines logic that the AI agent should activate automatically, such as triggering a handoff to an operator.

init_skills:
  - TransferToTheOperatorSkill

Avoid naming confusion:

Recommendation	Explanation
Check the tool/skill name in the YAML of the Skill Group	The name must match the object_name of the tool or skill.
Pay attention to case sensitivity	Names are case-sensitive (for example, TransferToTheOperatorSkill, not transfertotheoperatorskill).
Verify that the tool/skill is in a connected Skill Group	Even if the workflow is correct, the AI agent won't see the tool or skill unless the group is attached.
Maintain consistent naming conventions	Typically, use camelCase for tools and PascalCase for skills.

❗ Important: The agent can only use tools and skills from connected Skill Groups.

How to connect a knowledge base to an AI agent?

Three mandatory steps:

1. Create Knowledge Base:

   • Go to Knowledge Bases → Create Knowledge Base
   • Configure: name, source type, settings (chunk_size, chunk_overlap, etc.)
   • Click Build

2. Link to agent:

   • Go to agent page → Knowledge Base section
   • Select the created knowledge base

3. Add tool to workflow:

  available_tools:
        SingleStatefulOutboundAgent:
          - SendChatMessage
          - FinishSession
          - SingleSearchFAQ

💡 Note: Fast Access KB doesn't require a tool call, but RAG (vector KB) requires explicit tool declaration.

Do I need the Translator?

No, the Translator is not required for standard AI agent operation.

Instead:

• Set agent's communication language via Speech Style and Language field
• Use multilingual models for Knowledge Base if supporting multiple languages

How to set up push notifications for the agent?

Configure in Advanced card → Set Push Notification Configuration:

Configuration:

• URL: Endpoint for HTTP POST requests
• Headers: Optional key-value pairs (for example, authorization)
• Events: Select which agent events trigger notifications
• Enable/Disable: Toggle notifications on/off

Notification payload format:

{
  "name": "<Event Name>",
  "data": {
    "user_id": "<User ID>",
    "session_id": "<Session ID>",
    "message": "<Agent's response>"
  }
}

AI Agent Troubleshooting Guide

AI Agent shows "Error" status

This indicates a failure during agent creation, build, or startup.

Scenarios:

1. During Creation: If an agent stuck in Creating switches to Error, click the status icon to view the error report explaining why the generation failed (for example, issue with knowledge base processing).
2. During Startup: If an existing agent fails to start.

Resolution steps:

1. Go to the agent's page
2. Click the three-dot menu (⋮) → Show logs
3. Click Copy logs
4. Send the logs to Flametree support team

Common causes: syntax errors in workflow, integration issues, or tool logic problems.

Agent claims information isn't available when it should be

Symptoms: Agent claims information isn't available when it should be

Solutions:

1. Use vector search tool to test information retrieval
2. Adjust chunk size and overlap parameters
3. Increase Top-K results
4. Improve source document structure

Agent provides old or incorrect information

Symptoms: Agent provides old or incorrect information

Solutions:

1. Update source documents regularly
2. Remove outdated sources before rebuilding
3. Restart agents after rebuilding knowledge base
4. Implement regular content review processes

Agent responds differently to similar situations

Symptoms: Inconsistent behavior across similar scenarios

Solutions:

1. Add more comprehensive examples in workflow
2. Be more specific in state descriptions
3. Review and align all configuration elements
4. Test systematically with consistent scenarios

File upload issues in Knowledge Base

Cause: Unsupported file format or size limitations

Solution:

1. Verify file format is supported (PDF, DOCX, TXT, MD, JSONL, XLSX, HTML)
2. Keep files under 100-300 MB for stability
3. Convert unsupported formats before upload
4. Check file encoding (UTF-8 recommended for text files)

Related Resources

• AI Agent Setup - Step-by-step guide to building your first AI agent
• Creating Knowledge Bases - Information management and search optimization
• Sessions and Monitoring - Conversation analysis and performance tracking
• Integrations Guide - Channel and system connections