Tools fail. Networks drop. APIs timeout. Great agentic AI systems handle these failures gracefully. Poor error handling breaks user trust and creates unreliable experiences. This guide explores patterns for robust error handling in agent tool execution.

Error Classification

Transient Errors

Temporary failures that may succeed on retry:

• Network timeouts
• Rate limit exceeded
• Service temporarily unavailable
• Database connection lost

Strategy: Automatic retry with exponential backoff

Permanent Errors

Failures that won't resolve with retries:

• Invalid credentials
• Missing required parameters
• Resource not found
• Permission denied

Strategy: Immediate failure with clear error message

Retry Strategies

Exponential Backoff

const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
    }
  }
};

Retry Limits

Set maximum retry attempts based on error type:

• Network errors: 3 retries
• Rate limits: Wait for reset period, 1 retry
• Server errors (500s): 2 retries
• Client errors (400s): No retries, immediate fail

Fallback Patterns

1. Alternative Tool Fallback

If primary tool fails, automatically try equivalent alternative tool. Example: If SendGrid fails, fall back to AWS SES.

2. Degraded Mode

Continue with reduced functionality rather than complete failure. Example: Use cached data if live API fails.

3. Human Escalation

For critical failures, route to human operator for manual intervention and decision-making.

User Communication

Error Message Principles

1. Be Specific: "Email sending failed: Invalid recipient address" not "Error occurred"
2. Suggest Solutions: "Check email format and try again" or "Contact support"
3. Show Progress: "Retrying... Attempt 2 of 3"
4. Maintain Context: Explain what the agent was trying to do when error occurred

Monitoring and Alerts

Track error patterns to improve reliability:

• Error rate by tool (alert if > 5%)
• Timeout frequency by endpoint
• Retry success/failure ratios
• Fallback activation frequency

Circuit Breaker Pattern

Prevent cascading failures by temporarily disabling failing tools:

class CircuitBreaker {
  constructor(threshold = 5, timeout = 60000) {
    this.failureCount = 0;
    this.threshold = threshold;
    this.timeout = timeout;
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
  }
  
  async execute(fn) {
    if (this.state === 'OPEN') {
      throw new Error('Circuit breaker is OPEN');
    }
    
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
}

Conclusion

Robust error handling is not optional for production AI agents. By implementing proper retry logic, fallback patterns, and user communication, you create reliable systems that maintain user trust even when things go wrong.

Error Handling Design for Agent Tool Execution