Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

15_ERROR_HANDLING

Shared from "OpenAI Agents Python" on Inkdown

Error Handling - Comprehensive Deep Dive

Overview

Error Handling in the OpenAI Agents SDK provides a structured way to manage and respond to errors that occur during agent execution. Think of Error Handling as "safety nets" or "exception management" - they ensure that when things go wrong (network failures, API errors, invalid inputs, etc.), the system can respond gracefully, provide useful information, and recover when possible.

Core Concepts

Error Types

The SDK defines several error types:

  1. UserError - Errors due to user input or configuration
  2. ModelBehaviorError - Errors from unexpected model behavior
  3. AgentsException - Base exception for SDK errors
  4. ToolTimeoutError - Tool execution timeout
  5. MaxTurnsExceeded - Agent exceeded maximum turns
  6. Guardrail Tripwires - Guardrail violations
  7. RunErrorDetails - Detailed error information
Why Error Handling Matters
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  1. Reliability - Handle failures gracefully
  2. Debugging - Provide useful error messages
  3. Recovery - Enable recovery from errors
  4. User Experience - Provide clear feedback
  5. Monitoring - Track error rates and types
  6. Compliance - Handle errors per requirements

Exception Hierarchy

Base Exception
Python
UserError
Python

When raised:

  • Invalid agent configuration
  • Invalid tool configuration
  • Invalid input parameters
  • Missing required fields
ModelBehaviorError
Python

When raised:

  • Model returns unexpected format
  • Model refuses to respond
  • Model behavior is inconsistent
ToolTimeoutError
Python

When raised:

  • Tool execution exceeds timeout
  • Tool hangs indefinitely
  • Network timeout during tool execution
MaxTurnsExceeded
Python

When raised:

  • Agent doesn't produce final output within max_turns
  • Agent is in an infinite loop
  • Agent keeps calling tools without stopping
Guardrail Tripwires
Python

When raised:

  • Guardrail detects unsafe content
  • Guardrail validation fails
  • Guardrail tripwire is triggered

RunErrorDetails

Error Details Structure
Python
Accessing Error Details
Python

Error Handlers

RunErrorHandlers

Custom error handlers for specific error types:

Python
Error Handler Types
MaxTurns Handler
Python
Custom Error Handlers
Python

Tool Error Handling

Tool Execution Errors

Tools can raise errors during execution:

Python
Tool Error Formatting

Format tool errors for the model:

Python
Tool Timeout Handling
Python

Guardrail Error Handling

Input Guardrail Tripwires
Python
Output Guardrail Tripwires
Python
Tool Guardrail Tripwires
Python

Model Error Handling

Model API Errors

Handle model API errors:

Python
Model Behavior Errors

Handle unexpected model behavior:

Python
Model Retry

Implement model retry logic:

Python

Error Recovery Strategies

Retry Strategy

Retry failed operations:

Python
Fallback Strategy

Use fallback on error:

Python
Resume Strategy

Resume from error state:

Python
Graceful Degradation

Degrade gracefully on error:

Python

Error Logging

Logging Errors

Log errors for monitoring:

Python
Structured Error Logging

Log structured error data:

Python
Error Metrics

Track error metrics:

Python

Error User Messages

User-Friendly Error Messages

Provide clear error messages to users:

Python
Error Context in Messages

Include helpful context:

Python

Error Testing

Testing Error Handling

Test error scenarios:

Python
Error Fixtures

Use fixtures for error scenarios:

Python

Error Best Practices

1. Catch Specific Exceptions

Catch specific exceptions, not all:

Python
2. Provide Context in Errors

Include helpful context in error messages:

Python
3. Log Errors Before Raising

Log errors before re-raising:

Python
4. Use Custom Error Types

Define custom error types for your application:

Python
5. Handle Errors Gracefully

Provide graceful fallbacks:

Python

Common Error Patterns

1. Network Error Handling
Python
2. API Rate Limit Handling
Python
3. Validation Error Handling
Python
4. Timeout Error Handling
Python
5. Partial Success Handling
Python

Error and Tracing

Error Spans

Errors create trace spans:

Python
Error Metadata in Traces

Errors include metadata in traces:

Python

Error Monitoring

Error Rate Monitoring

Monitor error rates:

Python
Error Alerting

Alert on errors:

Python

Summary

Error handling ensures robust agent systems. Key takeaways:

  1. Exception hierarchy - structured error types
  2. UserError - configuration/input errors
  3. ModelBehaviorError - unexpected model behavior
  4. ToolTimeoutError - tool execution timeout
  5. MaxTurnsExceeded - exceeded turn limit
  6. Guardrail tripwires - safety violations
  7. RunErrorDetails - detailed error information
  8. Error handlers - custom error handling
  9. Tool errors - tool execution failures
  10. Guardrail errors - validation failures
  11. Model errors - API and behavior errors
  12. Retry strategy - retry failed operations
  13. Fallback strategy - use alternatives
  14. Resume strategy - recover from state
  15. Graceful degradation - degrade on error
  16. Error logging - track errors
  17. User messages - clear error feedback
  18. Error testing - test error scenarios
  19. Specific exceptions - catch specific types
  20. Monitoring - track error rates

Error handling is essential for building reliable, user-friendly, and maintainable agent systems.