RetryConfig

Configuration for automatic retry behavior in agent execution

Overview

The RetryConfig class configures automatic retry behavior for agent operations, particularly useful when using structured output that may fail validation.

Class Definition

from pydantic import BaseModel, Field

class RetryConfig(BaseModel):
    """Configuration for retry behavior in agent execution."""
    
    max_retries: int = Field(default=3, ge=0)
    retry_on_validation_error: bool = Field(default=True)
    retry_on_tool_error: bool = Field(default=False)
    backoff_base_seconds: float = Field(default=1.0, ge=0)
    
    model_config = {"frozen": True}  # Immutable

Properties

max_retries · int · default: "3"

Maximum number of retry attempts for a failed operation. Set to 0 to disable retries entirely.

• Minimum value: 0
• Each retry includes the error message as feedback to the LLM

retry_on_validation_error · bool · default: "True"

When True, the agent will automatically retry if structured output validation fails.

This handles:

• JSONDecodeError when the LLM returns invalid JSON
• ValidationError when JSON doesn’t match the Pydantic schema

retry_on_tool_error · bool · default: "False"

When True, the agent will retry if a tool execution fails with an exception.

Use with caution—some tool errors are not recoverable by retry (e.g., authentication failures).

backoff_base_seconds · float · default: "1.0"

Base delay in seconds for exponential backoff between retries.

The actual delay is: backoff_base_seconds * retry_attempt

• Retry 1: 1.0s delay
• Retry 2: 2.0s delay
• Retry 3: 3.0s delay

Creating RetryConfig

from tyler import RetryConfig

# Default configuration (3 retries, validation retry enabled)
config = RetryConfig()

# Custom configuration
config = RetryConfig(
    max_retries=5,
    retry_on_validation_error=True,
    retry_on_tool_error=True,
    backoff_base_seconds=2.0
)

# Disable retries
config = RetryConfig(max_retries=0)

Usage with Agent

At Agent Creation

from tyler import Agent, RetryConfig

agent = Agent(
    name="DataExtractor",
    model_name="gpt-4o",
    purpose="To extract structured data from documents",
    retry_config=RetryConfig(
        max_retries=3,
        retry_on_validation_error=True
    )
)

At Runtime

The agent’s retry_config is used automatically when response_type is provided:

from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    items: list[str]

# Retry config is used if structured output validation fails
result = await agent.run(thread, response_type=Invoice)

Retry Flow

When a retry occurs:

1. Error Detection: The agent catches JSONDecodeError or ValidationError
2. Feedback Message: An error message is added to the thread explaining what went wrong
3. Backoff Delay: The agent waits backoff_base_seconds * attempt_number seconds
4. Retry Attempt: A new LLM call is made with the feedback in context
5. Repeat or Fail: Steps 1-4 repeat until success or max_retries is exhausted

# Example retry flow with max_retries=2
# 
# Attempt 1: LLM returns invalid JSON → JSONDecodeError
# → Add error feedback to thread
# → Wait 1.0s
# 
# Attempt 2: LLM returns JSON but wrong schema → ValidationError  
# → Add error feedback to thread
# → Wait 2.0s
# 
# Attempt 3: LLM returns valid structured output → Success!

Error Handling

When all retries are exhausted, StructuredOutputError is raised:

from tyler import Agent, RetryConfig, StructuredOutputError

agent = Agent(
    name="extractor",
    retry_config=RetryConfig(max_retries=2)
)

try:
    result = await agent.run(thread, response_type=MyModel)
except StructuredOutputError as e:
    print(f"Failed: {e.message}")
    print(f"Validation errors: {e.validation_errors}")
    print(f"Last response: {e.last_response}")

Immutability

RetryConfig instances are immutable (frozen). Create a new instance to change values:

config = RetryConfig(max_retries=3)

# ❌ This will raise an error
config.max_retries = 5

# ✅ Create a new instance instead
new_config = RetryConfig(
    max_retries=5,
    retry_on_validation_error=config.retry_on_validation_error,
    retry_on_tool_error=config.retry_on_tool_error,
    backoff_base_seconds=config.backoff_base_seconds
)

Best Practices

Choosing max_retries

# Simple schemas - fewer retries needed
RetryConfig(max_retries=2)

# Complex schemas - may need more attempts
RetryConfig(max_retries=5)

# Critical operations - more retries with longer backoff
RetryConfig(max_retries=5, backoff_base_seconds=2.0)

When to Enable tool_error Retry

# ✅ Good candidates for tool retry
# - Network timeouts
# - Rate limiting
# - Transient API errors

# ❌ Bad candidates (won't help)
# - Authentication failures
# - Invalid parameters
# - Permission denied

Production Configuration

# Development - fast iteration
dev_config = RetryConfig(
    max_retries=1,
    backoff_base_seconds=0.5
)

# Production - reliability focused
prod_config = RetryConfig(
    max_retries=3,
    retry_on_validation_error=True,
    retry_on_tool_error=False,  # Only retry known-recoverable errors
    backoff_base_seconds=1.0
)

See Also

• Agent - The main agent class
• StructuredOutputError - Exception raised when retries are exhausted
• Structured Output Guide - Complete guide to structured output