Tool Retry & Backoff

ExecutionConfig retry settings re-run retryable tool failures and guardrail validation errors with exponential backoff and jitter. For tools, max_retry_limit / retry_* are translated into the effective RetryPolicy — the single tool-retry budget shared with ToolConfig(retry_policy=...).

from praisonaiagents import Agent, tool

@tool
def fetch_report(query: str) -> str:
    """Fetch a report from a flaky API."""
    return f"Report for: {query}"

agent = Agent(name="Resilient Agent", tools=[fetch_report], max_retry_limit=3)
agent.start("Get me the latest report")

The user requests a report; transient tool failures retry with exponential backoff and jitter until success or the limit is reached.

Quick Start

Enable with defaults

Retries with backoff are automatic when you set max_retry_limit:

from praisonaiagents import Agent, tool

@tool
def fetch_report(query: str) -> str:
    """Fetch a report from a flaky API."""
    return f"Report for: {query}"

agent = Agent(
    name="Resilient Agent",
    instructions="Fetch data from flaky APIs",
    tools=[fetch_report],
    max_retry_limit=3,
)
agent.start("Get me the latest report")

Fine-tune backoff

Use ExecutionConfig for delay, factor, and jitter:

from praisonaiagents import Agent, ExecutionConfig, tool

@tool
def fetch_report(query: str) -> str:
    """Fetch a report from a flaky API."""
    return f"Report for: {query}"

agent = Agent(
    name="Resilient Agent",
    instructions="Fetch data from flaky APIs",
    tools=[fetch_report],
    execution=ExecutionConfig(
        max_retry_limit=3,
        retry_initial_delay=0.5,
        retry_backoff_factor=2.0,
        retry_jitter=0.2,
    ),
)

How It Works

Total attempts = 1 + max_retry_limit. Default max_retry_limit=2 → up to 3 attempts. Delay: min(initial_delay × factor^(attempt−1), 60s) + random(0, jitter × base). The translation maps max_retry_limit → max_attempts (= limit + 1), retry_initial_delay (seconds) → initial_delay_ms, retry_backoff_factor → backoff_factor, and retry_jitter (fraction) → jitter=True + jitter_factor. The translated policy sets max_delay_ms = max(60000, initial_delay_ms), so ExecutionConfig users keep the historical 60-second delay cap (a plain RetryPolicy defaults to a 30-second cap).

Choosing Your Settings

Configuration

Field	Type	Default	Description
`max_retry_limit`	`int`	`2`	Max retries after the first attempt
`retry_initial_delay`	`float`	`1.0`	First retry delay (seconds)
`retry_backoff_factor`	`float`	`2.0`	Exponential multiplier per attempt
`retry_jitter`	`float`	`0.1`	Jitter fraction of base delay

These fields are one spelling of the tool-retry budget. An explicit ToolConfig(retry_policy=...) (or per-tool @tool(retry_policy=...)) wins over the ExecutionConfig alias. See Tool Retry Policy.

What Gets Retried

Outcome	Retried?
Tool timeouts	✅
Circuit breaker open	✅
Unexpected exceptions (not `ValueError` / `TypeError` / `AttributeError`)	✅
Guardrail validation failures	✅
Tool returns `{"error": ...}` without `timeout` / `circuit_open`	❌
Programming errors (`ValueError`, `TypeError`, `AttributeError`)	❌

Common Patterns

Disable retries:

agent = Agent(name="strict", max_retry_limit=0)

Rate-limited APIs:

execution=ExecutionConfig(
    max_retry_limit=4,
    retry_initial_delay=2.0,
    retry_backoff_factor=3.0,
    retry_jitter=0.3,
)

Low-latency tools:

execution=ExecutionConfig(
    max_retry_limit=2,
    retry_initial_delay=0.1,
    retry_backoff_factor=1.5,
)

Best Practices

Set jitter for parallel agents

Jitter spreads retry timing across agents and reduces thundering-herd spikes on shared APIs.

Don't retry programming errors

ValueError, TypeError, and AttributeError are treated as code bugs and are not retried.

Backoff is capped at 60s

Very large backoff factors cannot exceed a 60-second base delay per attempt.

One budget, not two

For tools, ExecutionConfig.retry_* is an alias translated into the effective RetryPolicy — the same budget as ToolConfig(retry_policy=...). Setting an explicit retry_policy overrides the ExecutionConfig spelling.

ExecutionConfig

Full execution configuration reference

Guardrails

Input and output validation

Loop Guardrails

Cap tool calls per turn

Structured LLM Errors

LLM-level retry and error handling

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Tool Retry & Backoff

Quick Start

How It Works

Choosing Your Settings

Configuration

What Gets Retried

Common Patterns

Best Practices

ExecutionConfig

Guardrails

Loop Guardrails

Structured LLM Errors

​Quick Start

​How It Works

​Choosing Your Settings

​Configuration

​What Gets Retried

​Common Patterns

​Best Practices

​Related

ExecutionConfig

Guardrails

Loop Guardrails

Structured LLM Errors

Quick Start

How It Works

Choosing Your Settings

Configuration

What Gets Retried

Common Patterns

Best Practices

Related