Bug Reporting

Overview

Whispey's bug reporting system enables users to provide real-time feedback during voice conversations by flagging problematic agent responses. The system automatically captures context, collects detailed feedback, and seamlessly continues the conversation where it left off.

Quick Start

Basic Setup

from whispey import LivekitObserve

# Enable bug reporting with minimal configuration
whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True
)

session_id = whispey.start_session(session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Default Behavior

With bug_reports_enable=True, users can say:

"feedback start" to start feedback collection
"feedback over" to end feedback and resume conversation

The system automatically uses default messages:

Response: "Thanks for reporting that. Please tell me the issue?"
Collection prompt: "Anything else?"
Continuation: "So, as I was saying, [original response]"

How It Works

Workflow Example

User: "What's the weather today?"
Agent: "I can help you cook pasta recipes" [PROBLEMATIC RESPONSE]
User: "feedback start"
Agent: "Thanks for reporting that. Please tell me the issue?"
User: "You talked about cooking when I asked about weather"
Agent: "Anything else?"
User: "feedback over"
Agent: "So, as I was saying, the weather today is sunny and 75°F"

Core Mechanism

Issue Detection: User speaks configured trigger phrase
Context Capture: System immediately stores the problematic agent response
Feedback Collection: Agent prompts for details about the issue
Data Storage: All feedback is collected and tagged to the specific turn
Conversation Continuation: Agent repeats the original response and continues normally

Configuration

Custom Trigger Phrases

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True,
    bug_reports_config={
        "bug_start_command": ["report issue", "there's a problem", "feedback start"],
        "bug_end_command": ["issue resolved", "problem fixed", "feedback over"],
        "response": "Please describe the issue.",
        "collection_prompt": "Got it, anything else?",
        "continuation_prefix": "So, as I was saying, ",
        "fallback_message": "Let me continue our conversation."
    }
)

session_id = whispey.start_session(session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Complete Configuration

bug_reports_config={
    "bug_start_command": ["report issue", "there's a problem", "feedback start"],
    "bug_end_command": ["issue resolved", "problem fixed", "feedback over"],
    "response": "Please describe the issue.",
    "collection_prompt": "Got it, anything else?",
    "continuation_prefix": "So, as I was saying, ",
    "fallback_message": "Let me continue our conversation."
}

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True,
    bug_reports_config=bug_reports_config
)

session_id = whispey.start_session(session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Advanced Configurations

Multi-language Support

bug_reports_config={
    "bug_start_command": [
        # English
        "report issue", "there's a problem", "this is wrong",
        # Hindi
        "समस्या रिपोर्ट करें", "गलत जवाब", "ये ठीक नहीं है",
        # Spanish
        "reportar problema", "esto está mal", "hay un error"
    ],
    "bug_end_command": [
        # English
        "issue resolved", "problem fixed", "that's all",
        # Hindi
        "समस्या हल हो गई", "ठीक हो गया", "बस इतना ही",
        # Spanish
        "problema resuelto", "está arreglado", "eso es todo"
    ],
    "response": "मुझे समझ आ गया कि कोई समस्या है। कृपया बताएं क्या गलत हुआ। I understand there's an issue. Please tell me what went wrong.",
    "collection_prompt": "और कुछ? Anything else?",
    "continuation_prefix": "आपके सुझाव के लिए धन्यवाद। अब वापस आपके सवाल पर - Thank you for the feedback. Back to your question - "
}

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True,
    bug_reports_config=bug_reports_config
)

session_id = whispey.start_session(session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Professional Support Configuration

bug_reports_config={
    "bug_start_command": ["escalate", "I need help", "this isn't working"],
    "bug_end_command": ["thank you", "that's all", "resolved"],
    "response": "I understand you're experiencing an issue. Please tell me what's not working correctly so I can improve.",
    "collection_prompt": "Is there any other detail you'd like to share about this issue?",
    "continuation_prefix": "Thank you for that feedback. Now, returning to your question - "
}

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True,
    bug_reports_config=bug_reports_config
)

session_id = whispey.start_session(session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Regex Pattern Support

bug_reports_config={
    "bug_start_command": [
        "report issue",
        "that's wrong",
        "this (is|seems) incorrect",
        "समस्या रिपोर्ट करें"
    ],
    "bug_end_command": [
        "issue resolved",
        "done",
        "finished",
        "complete"
    ]
}

whispey = LivekitObserve(
    agent_id="your-agent-id",
    apikey="your-api-key",
    bug_reports_enable=True,
    bug_reports_config=bug_reports_config
)

session_id = whispey.start_session(session)

# Export on shutdown via callback
async def whispey_shutdown():
    await whispey.export(session_id)

ctx.add_shutdown_callback(whispey_shutdown)

Data Structure

Bug Report Storage

{
    "bug_reports": [
        {
            "timestamp": 1703123456.789,
            "details": [
                {
                    "type": "initial_report",
                    "text": "feedback start",
                    "timestamp": 1703123456.789
                },
                {
                    "type": "bug_details",
                    "text": "You talked about cooking when I asked about weather",
                    "timestamp": 1703123457.123
                },
                {
                    "type": "bug_end",
                    "text": "feedback over",
                    "timestamp": 1703123460.456
                }
            ],
            "total_messages": 3,
            "stored_problematic_message": "I can help you cook pasta recipes"
        }
    ],
    "bug_flagged_turns": [
        {
            "turn_id": "turn_3",
            "agent_message": "I can help you cook pasta recipes",
            "flagged_at": 1703123456.789
        }
    ]
}

Turn Flagging

Turns with reported issues are marked with:

{
    "turn_id": "turn_3",
    "user_transcript": "What's the weather today?",
    "agent_response": "I can help you cook pasta recipes",
    "bug_report": true,  # Flagged as problematic
    "stt_metrics": {...},
    "llm_metrics": {...},
    "tts_metrics": {...}
}

Use Cases

Customer Service

Issue Escalation: Users can flag when responses don't address their concern
Quality Assurance: Systematic collection of problematic interactions
Agent Improvement: Feedback drives training data for model improvement

Educational Agents

Learning Feedback: Students can report when explanations are unclear
Content Correction: Flag incorrect or misleading information
Personalization: Adapt teaching style based on feedback patterns

Healthcare Applications

Safety Monitoring: Users can report potentially harmful medical advice
Accuracy Verification: Flag medical information that seems incorrect
Compliance Tracking: Monitor for responses that violate healthcare guidelines

Dashboard Integration

Bug Report View

The dashboard provides a dedicated bug report analysis interface showing:

Flagged Turn Context: Complete conversation context around the reported issue
User Feedback: All collected feedback messages and details
Response Analysis: The problematic agent response that was flagged
Metadata: Timestamps, turn IDs, and session information

Visual Indicators

Red highlighting for flagged conversation turns
Bug badges on problematic responses
Timeline view of feedback collection process
Context preservation showing original conversation flow

Important Notes

Export on Shutdown: Bug report data is only exported when the session ends via the shutdown callback
Real-time Detection: Bug detection happens in real-time during the conversation
Context Preservation: The system automatically captures and stores the problematic response
Seamless Continuation: After feedback collection, the conversation continues naturally

Next Steps

Learn about Advanced Features
Check out Examples for real-world usage
Visit our GitHub Examples Repository

Overview​

Quick Start​

Basic Setup​

Default Behavior​

How It Works​

Workflow Example​

Core Mechanism​

Configuration​

Custom Trigger Phrases​

Complete Configuration​

Advanced Configurations​

Multi-language Support​

Professional Support Configuration​

Regex Pattern Support​

Data Structure​

Bug Report Storage​

Turn Flagging​

Use Cases​

Customer Service​

Educational Agents​

Healthcare Applications​

Dashboard Integration​

Bug Report View​

Visual Indicators​

Important Notes​

Next Steps​