Configuration Overview

AI Agents are configured using YAML files and Python modules:

• YAML: Defines workflow, states, transitions, and tool/skill usage.
• Python: Implements custom skills or tool logic.

💡 Note: Use 2 spaces for YAML indentation. Consistent formatting prevents configuration errors.

🧐 Want to get started quickly? Check out AI Agent Setup Tutorial that walks you through building your first AI agent step-by-step.

Core Configuration Components

Understanding the key components of AI agent configuration is essential for building effective conversational agents. Each component serves a specific purpose in defining how your agent behaves, communicates, and processes information.

Identity

The Identity component establishes the fundamental character and role of your AI agent. This configuration directly influences how the agent presents itself and behaves throughout conversations.

Core Elements:

• Agent Name: Personal identifier (for example, "Pablo", "Sarah")
• Professional Role: Specific expertise or function (for example, "Collection Specialist", "Customer Support Representative")
• Organization: Company or entity the agent represents
• Context Details: Location, specialization, or other relevant background information

Configuration Impact: The identity description affects the agent's tone, approach to problems, and level of authority in conversations. A well-defined identity ensures consistent role-appropriate behavior across all interactions.

Example Configuration:

You are Pablo, a debt collection specialist at ABC Financial Services. 
You represent a New York-based company that specializes in respectful, 
soft collection methods for overdue accounts.

Speech Style and Language

This component defines the communication patterns and linguistic characteristics of your agent, controlling both what languages it speaks and how it expresses itself.

Key Configuration Areas:

• Primary Language(s): Supported languages and language detection
• Communication Style: Formal, casual, professional, friendly
• Tone and Manner: Speech patterns, vocabulary level, emotional approach
• Language Flexibility: Ability to switch languages mid-conversation

Behavioral Impact: Speech style directly affects user perception and engagement. It determines whether your agent sounds like a formal business representative, a friendly colleague, or a technical expert.

Configuration Examples:

• Professional: "Use formal business language with industry-specific terminology. Address users with appropriate titles and maintain a respectful, authoritative tone."
• Conversational: "Communicate in a friendly, approachable manner. Use clear, simple language and show genuine interest in helping users."
• Multilingual: "Detect the user's language automatically and respond accordingly. Support English and Spanish seamlessly, adapting to language switches during conversation."

Task Definition

The Task component describes the agent's primary objective and operational context. It provides the high-level purpose that guides all agent actions and decisions.

Essential Elements:

• Primary Objective: What the agent is fundamentally trying to achieve
• Operational Context: Current situation or circumstances
• Constraints and Guidelines: Limitations on agent behavior
• Success Criteria: How the agent should measure task completion

Strategic Importance: Task definition sets the scope of agent capabilities and helps prioritize actions when multiple options are available. It serves as the north star for decision-making throughout conversations.

Example Task Definition:

Your primary task is to assist customers with overdue payments through 
respectful communication. You are contacting customers via WhatsApp regarding 
30-day overdue accounts. Your methods must remain professional and non-threatening, 
focusing on finding mutually acceptable payment solutions.

Workflow Configuration

Workflow is the most complex component, defining the conversation logic through a state machine architecture. It controls how conversations flow, what actions are available at each stage, and how the agent transitions between different phases of interaction.

Core Concepts:

• States: Distinct phases of conversation (for example, greeting, information gathering, resolution)
• Transitions: Rules governing movement between states
• Available Tools: Actions the agent can perform in each state
• State Logic: Specific behaviors and responses for each conversation phase

Complexity Considerations:

• Simple Workflows (1-2 states): Suitable for straightforward interactions and rapid deployment
• Complex Workflows (3+ states): Provide precise control over conversation flow but require more setup

Integration Requirements: Workflow configuration typically requires collaboration with technical teams for initial setup, especially for complex business logic.

→ Detailed Workflow Configuration Guide

Knowledge Base Integration

AI Agents in Flametree use connected Knowledge Bases to provide accurate, context-aware responses. The platform supports two types of knowledge systems — Fast Access and Vector — each designed for a specific retrieval strategy.

Fast Access Knowledge Bases deliver instant answers from predefined data, ideal for FAQs and policies, while Vector Knowledge Bases use RAG-based search to find detailed, context-rich information in large document sets.

Example Fast Access Configuration:

## Product Information
- What services does the company offer?
- We provide personal loans, credit cards, and debt consolidation services.

## Policy Questions  
- What is your payment grace period?
- We offer a 10-day grace period before late fees are applied.

→ Learn More About Knowledge Bases

Conversation Results

This component defines the data collection framework for extracting and storing information gathered during conversations. It specifies what information should be captured, how it should be structured, and where it will be used.

Configuration Structure:

- field_name: HumanName
  kind: FormInfoField
  field_description: Customer's full legal name
  field_type: string
  field_content: none

Data Applications:

• Session Analysis: Performance tracking and conversation quality assessment
• Operator Handoffs: Providing context when transferring to human agents
• Workflow Decisions: Using collected data to guide conversation logic
• External Integration: Feeding information to CRM systems and databases

Strategic Value: Well-designed conversation results enable comprehensive analytics, improve handoff quality, and support automated business processes.

Default Value: The default Conversation Results are created during the agent creation step and can be modified for particular needs. The default values are:

- field_description: Summary of the user request. Extend when observe new needs.
  field_name: HumanNeeds
  field_type: str
  kind: FormInfoField
- field_description: date and time when user ready to discuss his needs.
  field_name: MeetingTimeslot
  field_type: str
  kind: FormInfoField
- field_content: en
  field_description: Current language witch user uses in communication with agent. As 2-letter code from available list. Default - es.
  field_name: HumanLanguage
  field_title: Language
  field_type: Literal[es, en]
  kind: FormInfoField
- field_description: The name of the user.
  field_name: HumanFullName
  field_title: Name
  field_type: str
  kind: FormInfoField
- field_description: The name of the user's company.
  field_name: HumanCompanyName
  field_title: Company
  field_type: str
  kind: FormInfoField
- field_description: The URL of the user's company web site.
  field_name: HumanCompanySiteURL
  field_title: Company Site
  field_type: str
  kind: FormInfoField
- field_description: The user's job title.
  field_name: HumanJobTitle
  field_title: Job Title
  field_type: str
  kind: FormInfoField
- field_description: The user's phone number.
  field_name: HumanPhone
  field_title: Phone
  field_type: str
  kind: FormInfoField
- field_description: The user's email.
  field_name: HumanEmail
  field_title: Email
  field_type: str
  kind: FormInfoField
- field_description: The user's Telegram ID
  field_name: HumanTelegramID
  field_title: Telegram
  field_type: str
  kind: FormInfoField
- field_description: The user's WhatsApp number.
  field_name: HumanWhatsAppID
  field_title: WhatsApp
  field_type: str
  kind: FormInfoField
- field_description: Link to the user's LinkedIN profile.
  field_name: HumanLinkedIN
  field_title: LinkedIN
  field_type: str
  kind: FormInfoField
- field_description: The user's product.
  field_name: HumanProduct
  field_title: Product
  field_type: str
  kind: FormInfoField

Skill Groups

Skill Groups represent collections of specialized capabilities and tools that extend agent functionality beyond basic conversation management.

Capability Categories:

• Integration Skills: Connecting to external systems (CRM, databases, APIs)
• Communication Skills: Advanced messaging, file handling, notification systems
• Business Logic Skills: Custom workflows, calculations, decision trees
• Analysis Skills: Data processing, reporting, pattern recognition

Implementation Approach: Most custom skills require development collaboration with technical teams. Standard skill groups are available for common business functions.

Integration Model: Skills are modular and can be combined to create sophisticated agent capabilities while maintaining clean separation of concerns.

→ Explore Skill Groups and Tools