​

Troubleshooting AI Agents

​

Overview

This guide helps you diagnose and resolve common issues with AI agents. Use this systematic approach to identify problems and implement solutions.

​

Common Agent Issues

​

1. Agent Not Responding

Symptoms:

• Customers not receiving responses
• No new conversations being handled
• Agent appears inactive

Possible Causes:

1. Agent not connected to WhatsApp number
2. Agent instructions are unclear or conflicting
3. Required capabilities not enabled
4. Knowledge collections not properly connected
5. Subscription expired or payment issues

Diagnostic Steps:

1. Check Channels tab - verify WhatsApp connection
2. Review agent instructions for clarity
3. Verify capabilities are enabled in Configuration tab
4. Check Collections tab for connected knowledge bases
5. Verify subscription status and payment information

Solutions:

1. Channel Issues: Reconnect WhatsApp numbers in Channels tab
2. Instructions: Clarify and refine agent behavioral guidelines
3. Capabilities: Enable required features in Configuration
4. Collections: Connect relevant knowledge databases
5. Billing: Check subscription status in Billing settings

​

2. Poor Response Quality

Symptoms:

• Irrelevant or unhelpful responses
• Customer complaints about agent behavior
• High handover rates
• Inconsistent conversation handling

Possible Causes:

1. Insufficient or unclear agent instructions
2. Missing knowledge collections
3. Evaluator settings too strict
4. Conflicting capability configurations
5. Outdated or incorrect information

Diagnostic Steps:

1. Review recent conversations for patterns
2. Check agent instructions for specificity
3. Verify connected knowledge collections
4. Review evaluator configuration
5. Test agent responses manually

Solutions:

1. Instructions: Provide more detailed, specific guidelines with examples
2. Knowledge: Connect relevant collections and update content
3. Evaluator: Adjust target score or disable if too restrictive
4. Capabilities: Review settings for conflicts or redundancy
5. Content: Update knowledge collections with accurate information

​

3. Agent Handover Issues

Symptoms:

• Excessive handovers to humans
• Handovers not working when needed
• Customers frustrated with handover process
• Human operators not receiving transfers

Possible Causes:

1. Handover capability not enabled
2. Unclear handover instructions
3. No human operators available
4. Handover triggers too sensitive or restrictive
5. Technical issues with handover system

Diagnostic Steps:

1. Check if handover capability is enabled
2. Review handover instruction clarity
3. Verify human operator availability
4. Test handover scenarios
5. Check system logs for errors

Solutions:

1. Enable Handover: Turn on capability in Configuration tab
2. Instructions: Provide clear, specific handover guidelines
3. Staffing: Ensure human operators are available and trained
4. Triggers: Adjust sensitivity of handover conditions
5. Technical: Contact support for system-level issues

​

4. Configuration Not Saving

Symptoms:

• Changes don’t persist after saving
• Error messages when trying to save
• Configuration reverts to previous state
• Save button not responding

Possible Causes:

1. Network connectivity issues
2. Invalid configuration values
3. Missing required fields
4. Permission restrictions
5. Browser or cache issues

Diagnostic Steps:

1. Check internet connection stability
2. Validate all configuration values
3. Ensure required fields are completed
4. Verify user permissions
5. Try different browser or clear cache

Solutions:

1. Network: Check internet and retry saving
2. Validation: Correct invalid values in configuration
3. Required Fields: Complete all mandatory fields
4. Permissions: Contact administrator for access rights
5. Browser: Clear cache, try incognito mode, or different browser

​

5. Tool Integration Problems

Symptoms:

• Tools not responding or functioning
• Error messages from connected tools
• Inconsistent tool behavior
• Tool connections showing as disconnected

Possible Causes:

1. Tool not properly configured
2. Authentication issues with external services
3. Tool compatibility problems
4. Missing tool dependencies
5. Rate limits or quota exceeded

Diagnostic Steps:

1. Check tool status and configuration
2. Verify authentication credentials
3. Review tool compatibility requirements
4. Check for missing dependencies
5. Monitor usage limits and quotas

Solutions:

1. Configuration: Review and correct tool settings
2. Authentication: Verify and update API keys/credentials
3. Compatibility: Check system version compatibility
4. Dependencies: Install or update required components
5. Limits: Monitor usage and upgrade quotas if needed

​

Performance Issues

​

Slow Response Times

Possible Causes:

• Large knowledge collections
• Complex tool integrations
• Network latency
• High system load

Solutions:

• Optimize knowledge collection size
• Review tool performance
• Check network connectivity
• Contact support for system issues

​

Inconsistent Behavior

Possible Causes:

• Conflicting instructions
• Multiple overlapping capabilities
• Outdated knowledge content
• Tool conflicts

Solutions:

• Simplify and clarify instructions
• Review capability interactions
• Update knowledge collections
• Test tools individually

​

Systematic Troubleshooting Approach

​

Step 1: Identify the Problem

Questions to Ask:

• What specific behavior is occurring?
• When did the problem start?
• Is it affecting all conversations or specific ones?
• Are there error messages or logs?

​

Step 2: Gather Information

Check These Areas:

• Recent configuration changes
• System status and alerts
• Performance metrics
• User feedback and reports

​

Step 3: Test and Isolate

Testing Methods:

• Use agent sandbox for controlled testing
• Disable capabilities one by one
• Test with different scenarios
• Check individual tool functionality

​

Step 4: Implement Solutions

Best Practices:

• Make one change at a time
• Test after each modification
• Document changes made
• Monitor impact of changes

​

Step 5: Monitor and Verify

Follow-up Actions:

• Monitor performance metrics
• Collect user feedback
• Continue testing edge cases
• Document successful solutions

​

Emergency Troubleshooting

​

Agent Completely Stopped

Immediate Actions:

1. Check system status page
2. Verify subscription and billing
3. Test WhatsApp connectivity
4. Contact technical support
5. Switch to backup agent if available

​

Data Loss or Corruption

Immediate Actions:

1. Stop making changes
2. Document what happened
3. Contact support immediately
4. Preserve any backup information
5. Don’t attempt manual fixes

​

Security Concerns

Immediate Actions:

1. Disable affected agent
2. Change authentication credentials
3. Review access logs
4. Contact security team
5. Document incident details

​

Prevention Strategies

​

Regular Maintenance

Weekly Tasks:

• Review performance metrics
• Check error logs
• Test key functionalities
• Monitor conversation quality

Monthly Tasks:

• Update knowledge collections
• Review and optimize configurations
• Audit tool integrations
• Plan improvements

​

Monitoring and Alerts

Set Up Monitoring For:

• Response times
• Handover rates
• Error frequencies
• Tool performance
• Customer satisfaction

​

Documentation

Maintain Records Of:

• Configuration changes
• Known issues and solutions
• Performance baselines
• Contact information for support

​

When to Escalate

​

Contact Technical Support When**:

• Agent completely stops responding across all channels
• System-wide configuration issues affect multiple agents
• Data loss or corruption is suspected
• Security-related concerns arise
• Third-party integration failures persist after troubleshooting

​

Information to Provide**:

• Agent ID and name
• Specific error messages
• Timeline of when issues started
• Steps already taken to resolve
• Impact on business operations

​

Recovery Procedures

​

Configuration Recovery

If Settings Are Lost:

1. Check for automatic backups
2. Restore from documented configurations
3. Recreate settings systematically
4. Test functionality after restoration

​

Conversation Recovery

If Conversations Are Affected:

1. Identify affected conversations
2. Check for data integrity
3. Notify affected customers if needed
4. Implement temporary workarounds

​

Performance Recovery

After Resolving Issues:

1. Gradually restore full functionality
2. Monitor performance closely
3. Communicate with stakeholders
4. Document lessons learned