Agent Retry

Automatically retry LLM API calls with jittered exponential backoff

Agent retry automatically re-runs failed LLM calls — across single-shot, streaming, tool-iteration and reflection turns — with jittered exponential backoff so transient rate limits, overloads, and network blips don’t break your agent.

from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Research topics on the web",
    retry=True,
)
agent.start("Find recent papers on diffusion models")

The user runs an agent; transient LLM failures retry automatically with jittered backoff.

Quick Start

1. Enable with True (simplest)

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Researcher",
       instructions="Research topics on the web",
       retry=True,
   )
   agent.start("Find recent papers on diffusion models")
   

   The user sends a research query; transient LLM failures trigger automatic retries with backoff.

   retry=True enables retry with sensible defaults: 3 retries, 5 s → 10 s → 20 s exponential schedule, capped at 120 s, with 50% additive jitter.

2. Tune with a dict (no extra import)

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Researcher",
       instructions="Research topics on the web",
       retry={
           "max_retries": 5,
           "base_delay": 2.0,
           "max_delay": 60.0,
           "jitter_ratio": 0.3,
       },
   )
   agent.start("Find recent papers on diffusion models")
   
3. Full control with RetryBackoffConfig

   from praisonaiagents import Agent, RetryBackoffConfig
   
   agent = Agent(
       name="Researcher",
       instructions="Research topics on the web",
       retry=RetryBackoffConfig(
           base_delay=2.0,
           max_delay=60.0,
           jitter_ratio=0.3,
           max_retries=5,
       ),
   )
   agent.start("Find recent papers on diffusion models")
   

---

How It Works

Aspect	Detail
What gets retried	Only LLMError where is_retryable=True (rate limits, overloads)
What does NOT get retried	Auth errors, invalid requests, non-retryable LLMError, any other exception
Total attempts	max_retries + 1 (default: 4 total)
Backoff schedule	min(base_delay × 2^attempt, max_delay) + uniform(0, jitter_ratio × delay)
Interruption	Raises RuntimeError("Agent interrupted during retry backoff") immediately

Which turn shapes retry?

retry= applies to every LLM call the agent makes, whether the model is being called for the first turn, a streaming turn, a tool-iteration turn, a reflection turn, or an async equivalent. If you can configure it, it retries.

Turn shape	Retried?
Non-streaming single-shot (agent.start(...))	✅
Streaming (agent.start(..., stream=True))	✅
Tool-iteration turns inside a multi-tool loop	✅
Reflection turns (when self_reflect=True)	✅
Async equivalents (agent.astart(...))	✅
Reasoning-steps single-shot	✅

max_retries also caps the recursive retries the LLM path performs after context compression and after backing off on a transient error. These were previously fixed at 2; they now follow the configured policy, and fall back to 2 only when retry= is not set.

Coverage across streaming and tool-iteration paths was made consistent in PraisonAI PR #2665. Before that release, streaming/tool-iter/reflection turns silently bypassed retry — a transient 429 on those paths surfaced raw. On current versions, retry= applies uniformly.

Behavioural change: RetryBackoffConfig.max_retries now also bounds the internal recursive retry loop. If you set max_retries=5, the compression / transient-backoff paths will now retry up to 5 times instead of the previous fixed 2.

---

Configuration Options

RetryBackoffConfig Fields

Option	Type	Default	Description
base_delay	float	5.0	Base delay in seconds for the first retry.
max_delay	float	120.0	Upper cap on any single backoff (after jitter).
jitter_ratio	float	0.5	Adds uniform(0, jitter_ratio × delay) on top of exponential delay. Set 0.0 to disable jitter.
max_retries	int	3	Maximum number of retries. Bounds both the outer LLMError-throwing retry loop (up to 4 total attempts by default) and the recursive _chat_completion retries after context compression / transient backoff. When retry= is not set, the internal loop caps at 2 for backwards compatibility.

Validation — the constructor raises ValueError if:

• base_delay <= 0
• max_delay < base_delay
• jitter_ratio outside [0, 1]
• max_retries < 0

Precedence

# Bool — enable with defaults
agent = Agent(name="A", instructions="...", retry=True)

# Dict — constructed from field names
agent = Agent(name="A", instructions="...", retry={"max_retries": 5, "base_delay": 2.0})

# RetryBackoffConfig — used directly
from praisonaiagents import Agent, RetryBackoffConfig

agent = Agent(
    name="A",
    instructions="...",
    retry=RetryBackoffConfig(max_retries=5, base_delay=2.0),
)

# None (default) — no retry
agent = Agent(name="A", instructions="...")

---

Common Patterns

Rate-limit friendly long jobs

from praisonaiagents import Agent, RetryBackoffConfig

agent = Agent(
    name="Batch Processor",
    instructions="Process a large batch of documents",
    retry=RetryBackoffConfig(
        base_delay=1.0,
        max_delay=300.0,
        jitter_ratio=0.5,
        max_retries=10,
    ),
)
agent.start("Summarise all 500 documents in the queue")

Strict mode — fail fast

from praisonaiagents import Agent, RetryBackoffConfig

agent = Agent(
    name="Fast Checker",
    instructions="Quick health check",
    retry=RetryBackoffConfig(max_retries=1),
)

Disable recursive retries entirely

Set max_retries=0 to disable the recursive compression / transient-backoff retries while keeping the retry policy configured.

from praisonaiagents import Agent, RetryBackoffConfig

agent = Agent(
    name="No Recursion",
    instructions="Surface transient failures immediately",
    retry=RetryBackoffConfig(max_retries=0),
)

Reproducible tests — disable jitter

from praisonaiagents import Agent, RetryBackoffConfig

agent = Agent(
    name="Test Agent",
    instructions="Deterministic for testing",
    retry=RetryBackoffConfig(jitter_ratio=0.0),
)

Observe retries with a hook

from praisonaiagents import Agent, RetryBackoffConfig
from praisonaiagents.hooks import HookRegistry, HookEvent

registry = HookRegistry()

@registry.on(HookEvent.ON_RETRY)
def on_retry(event):
    print(
        f"[retry] attempt {event.attempt + 1}/{event.max_retries} "
        f"in {event.delay_seconds:.1f}s: {event.error_message[:80]}"
    )

agent = Agent(
    name="API Caller",
    instructions="Call the API",
    retry=RetryBackoffConfig(max_retries=5),
    hooks=registry,
)
agent.start("Fetch the latest data")

The OnRetry hook receives:

Field	Type	Description
attempt	int	Current attempt number (0-based)
max_retries	int	Configured max retries
delay_seconds	float	Seconds the agent will sleep before the next attempt
error_message	str	String representation of the failing LLMError
operation	str	"llm_request" (sync) or "async_llm_request" (async)

---

Best Practices

Start with retry=True, tune later

The defaults (base_delay=5.0, max_delay=120.0, jitter_ratio=0.5, max_retries=3) are well-suited to most OpenAI and Anthropic rate-limit patterns. Start with retry=True and only tune when you observe systematic timeouts or excessive waiting.

Don't disable jitter in production

Setting jitter_ratio=0.0 creates a deterministic schedule that is useful for tests but dangerous in production. When many agents share the same API key and all retry at the same second, they hammer the endpoint simultaneously — exactly what jitter prevents. Keep jitter_ratio at 0.3 or higher in production.

Cap max_delay for user-facing flows

A 120-second wait is acceptable for background batch jobs but not when a human is waiting for a response. For interactive agents, set max_delay to something like 20.0 or 30.0, and keep max_retries low (1–2).

Use the OnRetry hook for observability, not control flow

The OnRetry hook is the right place to log metrics and send alerts. Retries are best-effort — if all attempts fail, the original LLMError propagates to your caller. Build your resilience strategy around catching that exception in your application code, not inside the hook.

---

Related

Agent retry covers the LiteLLM-backed agent loop. For the native OpenAIClient path used by AutoAgents and direct get_openai_client() callers, see OpenAI Client Retries.

OpenAI Client Retries

SDK-level Retry-After + backoff for the native OpenAI client path.

Tool Retry Policy

Retry tool calls — a different surface from LLM call retry.

Structured LLM Errors

Which LLMError categories are classified as retryable.

Hook Events

The OnRetry event and all other lifecycle hooks.

Agent Retry Strategies

Strategy guidance for production retry patterns.