Skip to main content

Sessions: Complete Conversation Management and Analysis

Sessions represent complete conversations between your AI agents and users, providing comprehensive tools for monitoring, analyzing, and managing these interactions from start to finish.

Prerequisites​

  • Active Flametree account with agent configuration
  • Appropriate user permissions for session access
  • Basic understanding of your AI agent setup

Understanding Sessions​

A session contains:

  • All messages exchanged between agent and user
  • Session parameters (information provided at conversation start)
  • Session results (information collected during conversation)
  • Status (active or closed)

Session Lifecycle​

  1. Session Start: User initiates conversation or agent makes outbound contact
  2. Active Phase: Ongoing conversation with message exchanges
  3. Session End: Conversation concludes (naturally or via operator action)
  4. Analysis Phase: Session data available for review and analysis

Interface Components​

The Sessions screen has three main sections:

  1. Sessions Table (left panel)
  2. Chat View (center panel)
  3. Session Information Panel (right panel)

Sessions Table Management​

The Sessions Table is your primary interface for browsing and filtering conversations. Located on the left panel, it displays all sessions in a sortable table format with powerful filtering capabilities to help you quickly find specific conversations or analyze patterns across your AI agent interactions.

Table Columns​

  • Agent: Which agent handled the conversation
  • Channel: Communication method used (WhatsApp, Email, etc.)
  • Assigned User: User who initiated or was assigned the conversation
  • Start Date: When conversation began
  • End Date: When conversation concluded (if finished)
  • Message Count: Total number of messages exchanged
  • User Location: Geographic location (if available)
  • IP Address: User's IP address (for web channels)

Session Status Indicators​

  • Yellow circle: Active session (ongoing conversation)
  • No indicator: Closed session (conversation finished)

Filtering and Search Options​

The Sessions screen provides comprehensive filtering:

  • AI Agent: Search and select a specific agent from dropdown
  • Channel: Search and select the communication channel
  • Responsible: Choose the operator or AI agent responsible
  • User Filter: Filter by the user involved in the conversation
  • Date Range: Filter by conversation dates using dropdown calendar
  • Start time filter: Select or manually enter the session start date
  • Last message filter: Filter by the date of the last message
  • Message Count: Filter sessions by the number of messages
  • Status Filter: Active vs. closed sessions
  • Location filter: Dropdown menu to select the client's country
  • IP filter: Input field to filter by a specific IP address
  • Text Search: Search within conversation content

Chat View Features​

The Chat View provides a detailed conversation interface where you can read the complete message history between your AI agent and users. This central panel recreates the conversation flow exactly as it occurred, with visual indicators to distinguish between different message types and participants.

Message Display​

  • Orange messages: From users/customers
  • Gray messages: From agents
  • Draft messages: System logs and internal notes (not visible to users)

Message Metadata​

Each message includes:

  • Timestamp: When message was sent/received
  • Message type: Text, image, file, system action
  • Processing status: Delivered, read, failed (if applicable)

Interactive Features​

  • Message threading: Related messages grouped together
  • Media preview: Images and files displayed inline
  • Link handling: Clickable links with preview

Session Information Panel​

The Session Information Panel on the right side displays comprehensive metadata about the selected conversation. This panel provides crucial context including session parameters, collected results, and performance metrics that help you understand the conversation's context and outcomes.

Session Parameters​

Purpose: Additional information provided when the session started

Common Parameters:

  • Customer ID or account number
  • Initial query or reason for contact
  • Priority level or urgency
  • Source system or referral information

Example:

Customer ID: 12345
Account Type: Premium
Initial Query: Payment issue
Priority: High

Session Results​

Purpose: Data collected according to your Conversation Results configuration

Displays:

  • All configured fields and their collected values
  • Collection timestamp for each field
  • Field status (collected, pending, failed)

Example:

Human Name: John Smith (collected)
Phone Number: +1-555-0123 (collected)
Promise to Pay: promised (collected)
Payment Date: 2024-02-15 (collected)
Debtor Verified: true (collected)

Session Metadata​

  • Session ID: Unique identifier
  • Total Duration: Conversation length
  • Agent Response Time: Average response time
  • User Response Time: Average user response time
  • Session Outcome: Final status or result

Advanced Session Analysis​

Advanced Session Analysis provides deep technical insights into your AI agent's behavior through detailed system and trace logs. This feature is essential for debugging issues, optimizing performance, and understanding exactly how your AI agent processes and responds to user requests.

Accessing: Click "Logs" button in chat view

Types of Logs​

Flametree includes two types of logs:

  1. System Logs – contain information about the session lifecycle:

    • Session opening and initialization
    • Session saving and closing
    • Tool and skill calls
    • Other events affecting AI agent behavior

    System logs help track and debug AI agent actions, preventing situations where it's impossible to reconstruct what happened.

  2. Trace Logs – capture LLM interactions:

    • User request
    • Prompt sent to the LLM
    • Generation returned by the model
    • LLM calls are separated by special markers (#######)

Trace Log Structure​

Each LLM call consists of three parts:

  1. Agent Name – indicates which LLM agent handled the request
  2. Prompt – the full prompt text sent to the LLM, including:
    • Main Task
    • Task context (Identity, Workflow, Additional Tasks)
    • Chat History
    • Available Tools
    • System Info (e.g., current date)
  3. Generation – the response generated by the LLM based on the defined Response Format

Response Format​

The response format defines the structure of data the LLM must return:

  • Action – the action the AI agent should take
  • Action Input – parameters required to perform the action

AI Agent Behavior Analysis​

During request processing, multiple LLM agents may be involved:

  • Single Stateful Outbound Agent – primary agent handling user requests
  • Form Agent – records interaction results
  • Additional Agents – may be invoked depending on scenario

Session Analysis Workflow​

  1. Identify Issue: Unusual agent behavior or user complaint
  2. Review Chat: Examine conversation flow in chat view
  3. Check Results: Verify data collection accuracy
  4. Analyze Logs: Use system and trace logs for deep analysis
  5. Identify Root Cause: System configuration vs. model behavior
  6. Implement Fix: Update agent configuration or workflow

Import Session Feature​

The Import Session Feature allows you to analyze pre-recorded audio conversations by uploading them to the platform. This powerful tool converts audio files into structured session data, enabling you to extract insights from existing conversations and compare human vs. AI performance.

Use Cases​

  • Quality Control: Analyze call center conversations for compliance
  • Training Data: Convert successful human conversations to training examples
  • Conversation Analysis: Extract insights from existing audio records
  • Performance Benchmarking: Compare human vs. AI performance

How to Import Sessions​

  1. Go to Sessions section and click "Import session"
  2. Select the AI agent responsible for analyzing the session
  3. Choose a data source (audio format only supported)
  4. Upload the file (supported formats: MP3, WAV, M4A)
  5. Start the import and wait for completion
  6. Check the uploaded data in the Sessions section

Process Flow​

  1. Upload Audio: Provide audio file (supported formats: MP3, WAV, M4A)
  2. Automatic Transcription: System converts speech to text
  3. Speaker Identification: Distinguishes between different speakers
  4. Result Generation: Applies your Session Results configuration to extract data
  5. Analysis: Review transcribed conversation and extracted results

Features​

  • Multi-speaker Support: Correctly identifies different participants
  • High Accuracy Transcription: Uses advanced speech recognition
  • Metadata Extraction: Preserves timing and speaker information
  • Result Mapping: Automatically extracts configured session results

Example Workflow​

1. Upload: customer_call_20240215.mp3
2. Processing: Transcription and speaker identification
3. Results: 
   - Customer Name: John Doe
   - Issue Type: Billing dispute
   - Resolution: Partial refund approved
   - Customer Satisfaction: Satisfied
4. Analysis: Compare with similar agent-handled calls

Operator Handover​

Operator Handover enables seamless transitions between AI agents and human operators during conversations. This feature ensures continuity of service while providing human oversight when needed, maintaining conversation context and logging all interactions for quality assurance.

When Handover Occurs​

  • Manual: Operator clicks "Handover to Operator" button
  • Automatic: Agent triggers handover based on configured conditions
  • User Request: Customer explicitly asks to speak with human
  • Escalation: Conversation reaches defined escalation criteria

Handover Process​

  1. Agent Pause: AI agent stops automatic responses
  2. Notification: Operator receives handover notification
  3. Context Transfer: Complete conversation history available
  4. Human Control: Operator takes over conversation
  5. Resume Options: Can return to AI agent if appropriate

Message Logging​

  • All messages sent by the operator after the handover are logged in the session history
  • This ensures data consistency and enables review of the interaction
  • The system logs which messages were sent by the operator and when the handover occurred
  • This helps assess operator performance and analyze reasons for escalation

Operator Interface Features​

  • Complete History: Full conversation context
  • Session Results: All collected data visible
  • Suggested Responses: AI can provide response suggestions (co-pilot mode)
  • Quick Actions: Common responses and actions readily available

Visual Indicators​

  • AI Icon: Agent is responding (visible to end users)
  • Operator Icon: Human operator responding (visible to end users)
  • Handover Status: Clear indication of who is currently handling conversation

Co-pilot Mode​

Purpose: Human operator with AI assistance

Features:

  • Response Suggestions: AI suggests responses for operator approval
  • Information Lookup: AI searches knowledge base for operator
  • Action Recommendations: AI suggests next steps
  • Quality Control: Human oversight of all communications

Monitoring and Analytics​

Monitoring and Analytics provides comprehensive insights into your AI agent's performance and conversation patterns. This section offers real-time dashboards, performance metrics, and quality analysis tools to help you optimize your conversational AI implementation.

Real-time Monitoring​

  • Active Sessions Dashboard: Overview of ongoing conversations
  • Response Time Tracking: Monitor agent performance metrics
  • Error Alerts: Immediate notification of system issues
  • Volume Monitoring: Track conversation volume and patterns

Performance Metrics​

  • Average Response Time: How quickly agents respond
  • Session Duration: Typical conversation length
  • Resolution Rate: Percentage of successfully resolved conversations
  • User Satisfaction: Extracted from conversation analysis
  • Escalation Rate: Frequency of human operator involvement

Conversation Quality Analysis​

  • Sentiment Tracking: Monitor user sentiment throughout conversations
  • Goal Achievement: Track success rate for conversation objectives
  • Common Issues: Identify frequently occurring problems
  • Agent Performance: Compare different agent configurations

Reporting Features​

  • Conversation Reports: Detailed analysis of conversation patterns
  • Result Extraction: Export collected session results
  • Performance Dashboards: Visual representation of key metrics
  • Trend Analysis: Identify patterns over time

Integration with Other Platform Features​

Knowledge Base Integration​

  • Search Analytics: Track which information is frequently requested
  • Missing Information: Identify gaps in knowledge base content
  • Usage Patterns: Understand how knowledge base is being used

Workflow Optimization​

  • State Transition Analysis: Review how users move through conversation states
  • Bottleneck Identification: Find where conversations get stuck
  • Flow Optimization: Use session data to improve workflow design

Agent Configuration Refinement​

  • Behavior Analysis: Use conversation data to refine agent personality
  • Response Optimization: Improve agent responses based on user feedback
  • Performance Tuning: Adjust configuration for better outcomes

Best Practices​

Regular Monitoring​

  • Daily: Review active sessions and immediate issues
  • Weekly: Analyze conversation patterns and agent performance
  • Monthly: Comprehensive review of metrics and trends
  • Quarterly: Strategic analysis and configuration optimization

Quality Assurance​

  • Sample Review: Regularly review random conversation samples
  • Error Analysis: Investigate and resolve conversation failures
  • User Feedback: Monitor and respond to user satisfaction indicators
  • Continuous Improvement: Use insights to refine agent configuration

Data Management​

  • Session Retention: Configure appropriate data retention policies
  • Privacy Compliance: Ensure session data handling meets regulations
  • Access Control: Limit session access to authorized personnel
  • Backup Strategy: Maintain secure backups of conversation data

Performance Optimization​

  • Response Time Monitoring: Track and optimize agent response times
  • Resource Usage: Monitor system resources and scale as needed
  • Error Rate Tracking: Identify and resolve technical issues
  • User Experience: Focus on metrics that impact user satisfaction

Analysis and Improvement​

  • Regular Log Review: Monitor logs to identify where AI agents provide incorrect answers
  • Automatic Handover Configuration: Update knowledge base if AI often hands over to humans
  • Data-Driven Training: Identify frequently asked questions the AI struggles with

Common Issues & Solutions​

Sessions Not Appearing

Causes: Filtering settings, permission issues, timing delays

Solutions:

  1. Clear all filters and refresh page
  2. Check date range settings
  3. Verify user permissions
  4. Contact support if data appears missing
Incomplete Session Results

Causes: Configuration issues, conversation flow problems

Solutions:

  1. Review Conversation Results configuration
  2. Check if conversation reached completion
  3. Analyze conversation flow for missed information
  4. Test agent configuration in Playground
Operator Handover Issues

Causes: Integration problems, notification failures

Solutions:

  1. Verify operator account setup and permissions
  2. Check notification settings and channels
  3. Test handover process in controlled environment
  4. Review integration configuration
Performance Issues

Causes: High volume, system resources, configuration complexity

Solutions:

  1. Monitor system resources and scale if needed
  2. Optimize agent configuration for performance
  3. Review conversation patterns for efficiency improvements
  4. Consider load balancing for high-volume scenarios

FAQ​

Is it possible to export sessions data?

Unfortunately, session data export functionality is not currently available. We are working on implementing this feature in a future release. For specific data needs, please contact our support team who may be able to assist with custom data extraction requests.

What's the difference between System Logs and Trace Logs?

System Logs contain information about session lifecycle events (opening, closing, tool calls), while Trace Logs capture detailed LLM interactions including prompts and responses. System Logs help debug agent actions, while Trace Logs help analyze AI model behavior.

How do I analyze why my AI agent is performing poorly?
  1. Review conversation flow in Chat View
  2. Check Session Results for data collection accuracy
  3. Analyze System and Trace Logs for technical issues
  4. Compare performance metrics across different time periods
  5. Look for patterns in escalation reasons
Can I import conversations from other platforms?

Yes, you can import audio conversations using the Import Session feature. Currently supports MP3, WAV, and M4A formats. The system will automatically transcribe, identify speakers, and extract results according to your configuration.

How does operator handover work?

Handover can be triggered manually by operators, automatically by AI agents based on conditions, or by user request. When handover occurs, the AI agent pauses, the operator receives notification, and complete conversation history is available for context.