Agent Troubleshooting Guide

Quickly diagnose and resolve common issues with AI agents, from configuration problems to performance issues.

Quick Diagnosis

Agent Not Responding

Symptoms: Agent doesn't reply to messages or shows error messages

Common Causes:

• Configuration errors in system prompt
• Network connectivity issues
• API rate limits exceeded
• Invalid channel configuration

Quick Fix:

1. Check agent status in the dashboard
2. Test with a simple "Hello" message
3. Verify channel configuration
4. Review error logs for specific issues

Poor Quality Responses

Symptoms: Agent provides irrelevant, inaccurate, or generic responses

Common Causes:

• Vague or contradictory system prompts
• Insufficient context or examples
• Conflicting memory entries
• Wrong tool selection

Quick Fix:

1. Review and simplify system prompt
2. Provide specific examples of desired outputs
3. Clear conflicting memory entries
4. Specify preferred tools in system prompt

Slow Performance

Symptoms: Agent takes too long to respond or times out

Common Causes:

• Complex workflows with multiple tools
• Large memory databases
• API rate limiting
• Network latency

Quick Fix:

1. Simplify tool usage in system prompt
2. Review memory size and relevance
3. Check API usage limits
4. Test with simpler requests

Common Issues and Solutions

Configuration Problems

Issue: Agent Doesn't Understand Requests

Symptoms:

• Agent asks for clarification frequently
• Provides generic responses
• Misinterprets user intent

Root Causes:

• System prompt too vague
• Missing context or examples
• Conflicting instructions

Solutions:

❌ Poor System Prompt:
"You are a helpful business assistant. Help users with their needs."

✅ Good System Prompt:
"You are a B2B lead generation specialist. When users ask for leads, find companies matching their criteria (industry, size, location) and provide contact information with verification."

Prevention:

• Include specific examples in system prompts
• Define key terms and acronyms
• Provide context for industry-specific language
• Test with various phrasings of the same request

Issue: Inconsistent Behavior

Symptoms:

• Different responses to similar requests
• Varying quality levels
• Unpredictable tool usage

Root Causes:

• Ambiguous system prompts
• Conflicting memory entries
• Unclear success criteria

Solutions:

1. Standardize system prompts:

Add to system prompt:
"Always follow this workflow:
1. Understand user criteria
2. Search for matching companies
3. Validate contact information
4. Present results in JSON format
5. Suggest next steps"

2. Clear memory conflicts:

   • Review memory entries for contradictions
   • Update or remove outdated information
   • Prioritize current preferences over old ones

3. Define quality standards:

Quality Requirements:
- Email validation: 95% confidence minimum
- Company data: Verify through 2+ sources
- Response format: Always use structured JSON
- Confidence scores: Include for all data points

Performance Issues

Issue: Slow Response Times

Symptoms:

• Responses take longer than 30 seconds
• Frequent timeouts
• Users abandon conversations

Root Causes:

• Complex tool chains
• Large memory searches
• API rate limiting
• Network issues

Solutions:

1. Optimize tool usage:

Tool Optimization:
- Limit simultaneous tool calls to 3
- Use specific tools for specific tasks
- Avoid redundant validations
- Cache frequently used data

2. Memory optimization:

   • Limit memory searches to top 10 results
   • Prioritize recent and relevant memories
   • Clean up outdated information regularly
   • Use specific search terms

3. Workflow streamlining:

   • Combine related operations
   • Use batch processing for multiple items
   • Implement progressive disclosure
   • Provide partial results while processing

Issue: High Error Rates

Symptoms:

• Frequent "tool failed" messages
• Incomplete responses
• Data quality issues

Root Causes:

• API limits exceeded
• Invalid data formats
• Network connectivity issues
• Tool configuration problems

Solutions:

1. API management:

Rate Limit Management:
- Monitor API usage in dashboard
- Implement exponential backoff
- Use batch operations when possible
- Distribute load across time periods

2. Data validation:

Input Validation:
- Verify email format before validation
- Check company name spelling
- Validate location names
- Confirm industry categories

3. Error handling:

Error Recovery:
- Retry failed operations with delays
- Provide partial results when possible
- Fail gracefully with clear messages
- Log errors for analysis

Memory Issues

Issue: Agent Forgets Important Information

Symptoms:

• Asks for same information repeatedly
• Ignores previously stated preferences
• Doesn't learn from successful interactions

Root Causes:

• Memory not being stored properly
• Low importance scores for key information
• Memory retrieval not working correctly

Solutions:

1. Explicit memory storage:

User: "Remember that I only want companies with recent funding"
Agent: "I'll store this preference: 'User prefers companies with recent funding (Series A, B, C within 18 months)' with high importance."

2. Memory validation:

   • Regularly review stored memories
   • Confirm key preferences with users
   • Update importance scores based on usage
   • Remove conflicting information

3. Retrieval optimization:

   • Use specific keywords in memory searches
   • Test memory retrieval with sample queries
   • Ensure semantic search is working properly
   • Monitor memory usage analytics

Issue: Outdated or Conflicting Information

Symptoms:

• Agent uses old preferences
• Contradictory responses
• Incorrect assumptions about user needs

Root Causes:

• Old memories with high importance scores
• Conflicting information from different sessions
• Lack of memory maintenance

Solutions:

1. Memory cleanup:

Regular Maintenance:
- Monthly memory audits
- Remove outdated information
- Resolve conflicts between memories
- Update importance scores

2. Conflict resolution:

When conflicts arise:
- Ask user to clarify current preferences
- Show conflicting information for review
- Update memory with current requirements
- Archive old information rather than deleting

Channel-Specific Issues

Issue: Email Channel Not Working

Symptoms:

• Emails not being sent
• Responses not reaching recipients
• Formatting issues in emails

Root Causes:

• Invalid email configuration
• Authentication problems
• Spam filters blocking emails
• Email template issues

Solutions:

1. Configuration check:

Email Configuration:
{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Agent Response - {{date}}",
  "smtp": {
    "host": "smtp.yourdomain.com",
    "port": 587,
    "secure": true,
    "auth": {
      "user": "[email protected]",
      "pass": "your-app-password"
    }
  }
}

2. Deliverability optimization:
   • Use authenticated domain
   • Include proper SPF/DKIM records
   • Test with different email providers
   • Monitor bounce rates

Issue: Webhook Channel Failures

Symptoms:

• Data not reaching external systems
• HTTP errors in logs
• Incorrect data formats

Root Causes:

• Wrong webhook URLs
• Authentication issues
• Data format mismatches
• Network connectivity problems

Solutions:

1. Webhook testing:

# Test webhook endpoint
curl -X POST https://your-webhook-url.com/endpoint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{"test": "data"}'

2. Data format validation:

Expected Format:
{
  "leads": [
    {
      "company": "Example Corp",
      "email": "[email protected]",
      "industry": "SaaS",
      "size": "50-100"
    }
  ],
  "timestamp": "2024-01-01T12:00:00Z",
  "agent_id": "agent-123"
}

Issue: Slack Channel Problems

Symptoms:

• Messages not appearing in Slack
• Permission errors
• Formatting issues

Root Causes:

• Invalid Slack tokens
• Insufficient permissions
• Wrong channel names
• Rate limiting

Solutions:

1. Token validation:

   • Verify bot token is correct
   • Check token permissions
   • Test with Slack API
   • Regenerate if necessary

2. Permission setup:

Required Slack Permissions:
- channels:read
- channels:write
- chat:write
- users:read
- files:write

Diagnostic Tools

Agent Health Check

Use these steps to diagnose agent issues:

1. Basic connectivity test:

Test Message: "Hello, please respond with your current status"
Expected Response: Agent should respond within 10 seconds

2. Configuration validation:

Check List:
✅ Agent name is clear and specific
✅ Purpose statement is concise
✅ System prompt includes specific instructions
✅ Channel configurations are valid
✅ Memory is accessible and relevant

3. Performance baseline:

Performance Metrics:
- Response time: < 15 seconds for simple requests
- Tool success rate: > 95%
- Memory retrieval rate: > 90%
- User satisfaction: > 4.0/5.0

Log Analysis

Common Error Patterns:

Authentication Errors:

Error: "Invalid API key" or "Authentication failed"
Solution: Update API credentials in channel configuration

Rate Limit Errors:

Error: "Rate limit exceeded" or "Too many requests"
Solution: Implement delays between requests or upgrade API plan

Tool Failures:

Error: "Tool execution failed" or "Timeout"
Solution: Simplify tool usage or increase timeout limits

Memory Errors:

Error: "Memory not found" or "Retrieval failed"
Solution: Check memory system status and rebuild index if needed

Preventive Measures

Regular Maintenance

Weekly Tasks:

• Review agent performance metrics
• Check error logs for patterns
• Test core functionality
• Update system prompts if needed

Monthly Tasks:

• Audit memory storage and relevance
• Review channel configurations
• Analyze user feedback
• Optimize tool usage patterns

Quarterly Tasks:

• Comprehensive performance review
• Update configurations based on learnings
• Upgrade tools and integrations
• Plan new features and capabilities

Monitoring Setup

Key Metrics to Monitor:

• Response time: Average time to complete requests
• Success rate: Percentage of requests completed successfully
• Error rate: Frequency of failures or issues
• User satisfaction: Feedback scores and ratings
• Tool usage: Which tools are used most frequently
• Memory effectiveness: How often memories are retrieved and used

Alerting Rules:

Alert Conditions:
- Response time > 30 seconds
- Error rate > 5%
- Tool failure rate > 10%
- Memory retrieval rate < 70%
- User satisfaction < 3.0/5.0

Getting Help

When to Contact Support

Immediate Support Needed:

• Agent completely non-responsive
• Data security or privacy concerns
• System-wide performance issues
• Critical business impact

Standard Support:

• Configuration optimization
• Performance tuning
• Feature questions
• Best practice guidance

Information to Provide

When contacting support, include:

• Agent ID and configuration details
• Error messages and logs
• Steps to reproduce the issue
• Expected vs actual behavior
• Business impact and urgency

Self-Service Resources

• Documentation: Complete agent guides and tutorials
• Community: User forums and discussions
• Video tutorials: Step-by-step configuration guides
• Sample configurations: Proven agent setups
• API documentation: Technical integration details

Related Articles

• Agent Configuration Guide
• Getting Started with AI Agents
• Agent Tools & Capabilities Overview
• Multi-Channel Agent Communication
• Agent Memory & Persistence
• Agent Best Practices

Need Help?

If you can't resolve the issue using this guide, our support team is ready to help with personalized troubleshooting and optimization.

Contact Support | Join Community | Submit Bug Report