> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Request[π Request] --> Tool[π§ Tool]
Tool -->|Fail| Backoff[β±οΈ Backoff]
Backoff --> Retry[π Retry]
Retry -->|Success| Done[β
Done]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
class Request,Done agent
class Tool,Backoff,Retry tool
```
## Quick Start
Retries with backoff are automatic when you set `max_retry_limit`:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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")
```
Use `ExecutionConfig` for delay, factor, and jitter:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Agent
participant Tool
Agent->>Tool: Attempt 1
Tool-->>Agent: Retryable error
Note over Agent: delay = min(1.0 Γ 2^0, 60s) + jitter
Agent->>Tool: Attempt 2
alt Non-retryable error
Tool-->>Agent: Return error as-is
else Retryable + under limit
Tool-->>Agent: Success or retry again
end
```
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{Use case?} -->|Rate-limited API| A[Higher initial_delay + jitter]
Q -->|Flaky network| B[Higher max_retry_limit]
Q -->|Deterministic tools| C[max_retry_limit=0]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
class Q agent
class A,B,C tool
```
***
## 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](/docs/features/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:**
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(name="strict", max_retry_limit=0)
```
**Rate-limited APIs:**
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
execution=ExecutionConfig(
max_retry_limit=4,
retry_initial_delay=2.0,
retry_backoff_factor=3.0,
retry_jitter=0.3,
)
```
**Low-latency tools:**
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
execution=ExecutionConfig(
max_retry_limit=2,
retry_initial_delay=0.1,
retry_backoff_factor=1.5,
)
```
***
## Best Practices
Jitter spreads retry timing across agents and reduces thundering-herd spikes on shared APIs.
`ValueError`, `TypeError`, and `AttributeError` are treated as code bugs and are not retried.
Very large backoff factors cannot exceed a 60-second base delay per attempt.
Guardrail validation retries use the same `ExecutionConfig` backoff values.
***
## Related
Full execution configuration reference
Input and output validation
Cap tool calls per turn
LLM-level retry and error handling