Tool Retry & Backoff

Automatically retry failing tool calls with exponential backoff and jitter

ExecutionConfig retry settings re-run retryable tool failures and guardrail validation errors with exponential backoff and jitter.

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

1. 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")
   
2. 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).

---

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

For per-tool RetryPolicy overrides, 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.

Guardrails share these settings

Guardrail validation retries use the same ExecutionConfig backoff values.

---

Related

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