Quick Start: Build Your First AI Agent

This comprehensive guide walks you through creating a simple assistant AI agent on the Flametree platform. By the end of this tutorial, you'll have a fully functional AI agent that can answer questions, collect contact information, and schedule calls with potential customers.

What You'll Build

Your AI agent will be capable of:

• Respond to user questions in a conversation
• Use an uploaded FAQ and knowledge base for accurate answers
• Store key session parameters (name, interest, contact details)
• Offer a convenient time for a call
• End the conversation at the right time
• Operate based on a defined scenario (workflow) and tools

What You'll Learn

This tutorial covers the essential configuration areas:

• Agent identity and behavior
• The main task
• Knowledge base and FAQs
• Conversation result
• Conversation logic (workflow)

Prerequisites

• Access to a Flametree account
• Basic understanding of YAML formatting (we'll guide you through this)
• Content for your knowledge base (optional but recommended)

---

Step 1: Creating Your Agent

1. Navigate to the AI Agents section in your Flametree dashboard

2. Click Create Agent

3. Select Text Agent type

   Why Text Agent? This type provides full control over agent behavior, including workflow configuration, tool selection, and knowledge base integration.

Step 2: Defining the Agent’s Role

The AI agent’s role is how it presents itself to the user, the position it takes, and the primary function it performs. This description influences the agent’s tone and behavior in conversation.

Configuration Steps

Simply put: the role is a short summary of the virtual employee — who they are and what they’re supposed to help with.

1. Go to the Identity section in the AI agent card.
2. Enter a brief description of the role and behavior.

Example for a simple assistant agent:

You are a multilingual digital consultant designed to assist users with questions about products or services. You communicate clearly, concisely, and professionally, always aiming to understand the user's needs and provide relevant, helpful information.

Step 3: Setting the Agent's Task

Task is a brief textual description of the AI agent’s high-level objective:

• When the AI agent should act
• What overall goal it should achieve
• What constraints apply to its actions

Important: Do not describe behavior details or step sequences here — those will be defined separately in the Workflow.

Configuration Steps

1. Go to the Task section in the agent settings.
2. Enter a clear description of the AI agent’s role and actions.

Example Task Configuration

Your main task is to assist users with product-related questions, collect contact information if needed, and suggest a time for a call. Your actions are restricted to the tools listed in the “Available Tools” section. You are not allowed to perform any other actions.

You should not take action unless the user has clearly expressed intent. Always respond politely, professionally, and helpfully, using natural language.

Step 4: Communication Style & Language

Speech Style and Language is where you define which language the AI agent speaks and how it communicates with users.

This affects message tone, whether a formal or conversational style is acceptable, and the agent’s ability to switch languages.

Configuration Steps

1. Go to the Speech Style and Language section.
2. Choose a style appropriate for your business context.
3. Specify which languages the agent should support and how it selects them.

Example Configuration

You speak clearly, politely, and professionally. Avoid unnecessary jargon. Detect the language used by the user (e.g., English, Russian, Spanish) and respond in that language. If the user switches language mid-conversation, adapt accordingly.

Key Settings to Define

• Style: formal, friendly, expert, neutral, etc.
• Allowances: whether slang, abbreviations, emojis, etc. are permitted
• Languages: which are supported and how the language is determined (e.g., automatically based on the user’s message)
• Flexibility: whether switching languages during the conversation is allowed

Step 5: Adding FAQ

Fast Access FAQ is a list of pre-defined question–answer pairs the AI agent can reference first if the user’s question matches in meaning.

Benefits

• Reduce response time
• Avoid unnecessary text generation
• Provide accurate, controlled information

Configuration Steps

1. Go to the Fast Access Knowledge Base section in the AI agent settings.
2. Specify the possible user question.
3. Provide an answer — this should be clear and conversational, not a copy-paste from a document.

Example FAQ Entries

## Question 1. Do you offer delivery?
Marketing name of the Slana company is **$lana**. It's the same things.

## Question 2. What brands are available in your catalog?
We work with leading brands and update our selection regularly.

## Question 3. Do you offer delivery?
Yes, you can return or exchange a product within 14 days if it's in its original condition and packaging.

Best Practices

• Use short, specific questions written as users would phrase them.
• Rewrite answers in a conversational tone — don’t copy legal text.
• If the information is variable (e.g., prices, availability), place it in the Knowledge Base, not the FAQ.

Step 6: Setting Up Knowledge Base

(See the Knowledge Base section for more details)

A Knowledge Base is a data source the AI agent uses to answer questions — including prices, specs, availability, etc.

Quick Setup Steps

1. Go to Knowledge Bases → Create Knowledge Base
2. In the Description field, enter a name (e.g., “Price List”)
3. Go to the Sources tab and click “Add +”
4. Choose the type of source. For a quick start, uploading a file is enough. Flametree supports PDF, TXT, MD, JSON, Word, Excel formats.
5. Click Build — your knowledge base is ready.

Supported File Formats

Format	Use Case	Notes
PDF	Documents, manuals, reports	Full text extraction
DOCX	Word documents	Formatting preserved
TXT	Plain text files	UTF-8 recommended
MD	Markdown documentation	Ideal for structured content
XLSX	Spreadsheets, data tables	Data extraction supported
HTML	Web pages, articles	Clean HTML preferred
JSONL	Structured data	JSON Lines format

The AI agent can now search and use data from this knowledge base.

For more, see the Knowledge Base section of the User Guide.

Step 7: Configuring the Workflow (Conversation Logic)

The Workflow defines how the AI agent behaves — what it does at the start, what tools it uses, when it ends the session.

Basic Workflow Example

- process_name: SalesProcess  
name: SalesSupport  
kind: StateConfig  
init_state: true  
description: |    - Answer questions about products
    - Collect contact info
    - Offer call scheduling if user is interested
    - Use FAQ and Knowledge Base when relevant
    available_tools:    
        SingleStatefulOutboundAgent:      
            - SendChatMessage      
            - FinishSession      
            - SingleSearchFAQ      

Key Workflow Components

What is StateConfig and why is it needed?

In Flametree, the AI agent follows a scenario (workflow) composed of states. Each state is described using a StateConfig block. Think of it as a set of instructions for one stage of the user interaction.

• process_name: SalesProcess — Name of the business process (in this case, sales).

• name: SalesSupport — Name of the current state (a step in the process).

• kind: StateConfig — The entity type (AI agent state).

• init_state: true — Marks this as the initial state of the scenario.

• description — What the agent does in this step

  description: 
  |    - Answer questions about hardware  # The agent answers product-related questions
      - Collect contact info             # Collects user contact info
      - Offer call scheduling if user is interested  # Offers to schedule a call if the user is interested
      - Use FAQ and Knowledge Base when relevant  # Uses FAQ and knowledge base when applicable

• available_tools — Tools agent can use

  available_tools:    
      SingleStatefulOutboundAgent:      
          - SendChatMessage             # Send a message to the user      
          - FinishSession               # End the session      
          - SingleSearchFAQ             # Search the knowledge base  

YAML Best Practices

⚠️ Important: If there is a YAML syntax error when saving the Workflow, Flametree will automatically discard the changes and revert to the last valid version.

• Use an external YAML validator before saving (e.g., yamlchecker.com).
• Save drafts locally if working on complex logic.

Step 8: Defining Data Collection

Conversation Results are the data points to be extracted from the dialogue (e.g., user’s name, product of interest, preferred time for a call).

Example Configuration

- field_name: HumanFullName
  kind: FormInfoField
  field_description: Client's full name

- field_name: HumanEmail
  kind: FormInfoField
  field_description: Contact email

- field_name: InterestedProduct
  kind: FormInfoField
  field_description: Product the user is interested in

- field_name: MeetingTimeslot
  kind: FormInfoField
  field_description: Preferred time for a call

Field Configuration

Parameter	Purpose	Example
field_name	Technical variable name	HumanFullName
kind	Data type	FormInfoField
field_description	What to collect	Client's full name

Step 9: Testing Your Agent

1. Go to the Playground section
2. Select the agent you created
3. Enter a prompt
4. Check how the AI agent:
   • Understands the request
   • Finds the product
   • Records the interest and suggests a meeting

Test Scenarios

• Product Inquiries: Ask about features, pricing, availability
• Contact Collection: Provide information and see how it's captured
• Meeting Scheduling: Test the appointment booking flow
• Knowledge Base: Ask questions that require KB searches
• FAQ Testing: Verify quick-access responses

Step 10: Monitoring & Analytics

(See Sessions & Logs for more details)

After launch, you can monitor the AI agent’s performance in real-time:

1. Go to the Sessions section

   Here you’ll see a list of all active and completed user sessions.

2. Click on the session you want

   Inside, you’ll be able to:

   • View the entire dialogue
   • See which parameters were collected (Conversation Result)
   • Track state transitions (for complex workflows)

3. Go to Logs to:

   • View the AI agent’s actions step by step
   • See which tools were triggered
   • Identify errors (if any)

Important Notes

Agent Lifecycle Management

1. If your Workflow YAML contains a syntax error, pressing Save will cause all unsaved changes to be discarded, and the form will revert to the last valid version.

   Recommendation:

   Always check YAML validity in an external editor before saving.

2. The newly created AI agent may not appear immediately.

   After saving, the system might redirect you to the create-agent form again without confirmation. The AI agent has already been created, but you’ll need to find it manually in the AI agent list.

   Recommendation:

   Always verify the AI agent list after creation to confirm it was saved.

3. Comment highlighting in Workflow

   Comments (#) in the YAML Workflow starting from the 4th character onward may not be highlighted in green. Adding the comment at the beginning of a block line restores syntax highlighting. This is a visual quirk of the editor and does not affect execution.

4. Before saving the AI agent, you must select an LLM model, otherwise the portal will display the warning:

   “LLM integration is required to create a bot”

YAML Editing Best Practices

• Syntax Validation: Always check YAML validity before saving
• Comment Formatting: Place comments at the beginning of lines for proper highlighting
• Backup Strategy: Save complex workflows locally before editing
• Incremental Changes: Test small changes before implementing complex logic

Common Issues & Solutions

Agent shows "Error" status

Cause: Syntax error in workflow or configuration issue

Solution:

1. Open agent card → three-dot menu (⋮) → Show logs
2. Click Copy logs
3. Review for syntax errors or contact support with logs
4. Common issues: YAML indentation, missing tools, invalid state transitions

Knowledge Base not working

Cause: Missing tool declaration or base not built

Solution:

1. Verify Knowledge Base is linked to agent in Database section
2. Ensure SingleSearchFAQ tool is declared in workflow
3. Check KB status - if "Modified", click Build
4. Restart agent after changes

Agent gives repeated greetings

Cause: Model behavior or missing greeting configuration

Solution:

1. Add environment variable: START_PHRASE with custom greeting
2. Add workflow instruction: "Don't greet humans during sessions"
3. Consider switching to more stable LLM model (e.g., Llama)

Incomplete responses to long questions

Cause: Model context limits or insufficient instructions

Solution:

1. Add explicit guidance in workflow description:
   • Break responses into paragraphs or bullet points
   • Indicate when answer will be continued
   • Offer to send information in multiple parts
2. Increase model context length if available

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)

Quick Reference

Required Tools by Functionality

Functionality	Required Tools
Basic Chat	SendChatMessage, FinishSession
Knowledge Base	SingleSearchFAQ
Operator Handoff	SuggestChatMessage, TransferToTheOperatorSkill
Notifications	Custom tools for email/SMS integration

Environment Variables Quick Reference

Variable	Purpose	Example
START_PHRASE	Custom greeting message	"Hello! How can I help you today?"
WA_SESSION_TIMEOUT	WhatsApp session timeout	43200 (12 hours in seconds)
SHOW_RAG_CHUNK_NUMBERS	Display KB chunk numbers	true
REPLY_IN_USER_LANGUAGE	Auto-detect user language	true

---

Next Steps

Once your agent is working correctly:

1. Advanced Workflows: Implement multi-state conversations and complex logic
2. Integration Setup: Connect to CRM, email systems, or other business tools

3. Campaigns Initialization: Use outbound communications to send messages from agent to the client

FAQ

Which parameter sets the first message?

Use the START_PHRASE environment variable:

1. Go to agent settings → Advanced Settings → Set Environment Variables
2. Add: key: START_PHRASE, value: Your greeting phrase
3. Click Save and restart the agent

How to connect a Knowledge Base to an agent?

Three mandatory steps:

1. Create KB: Go to Knowledge Bases → Create → Add sources → Build
2. Link to agent: Agent settings → Database section → Select KB
3. Add tool: Include SingleSearchFAQ in workflow available_tools

What are the YAML indentation rules?

• Use only spaces (no tabs)
• 2 spaces per indentation level recommended
• Consistent indentation at same level required
• Space required after : in key-value pairs

How to fix "Modified" status in Knowledge Base?

Click the Build button on the Knowledge Base card. This status indicates changes haven't been applied yet. After building, restart your agent to use the updated KB.

What's the difference between Fast Access KB and regular Knowledge Base?

Feature	Fast Access KB	Regular Knowledge Base
Size Limit	~10,000 characters	No strict limit
Search Method	Embedded in prompt	Vector search (RAG)
Tool Required	No	Yes (SingleSearchFAQ)
Use Case	FAQs, quick reference	Large documents, dynamic content