> ## 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 (for tools that have not declared themselves unsafe to re-run β see [Retrying Non-Idempotent Tools](#retrying-non-idempotent-tools)). For tools, `max_retry_limit` / `retry_*` are **translated into the effective `RetryPolicy`** β the single tool-retry budget shared with `ToolConfig(retry_policy=...)`.
```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)`.
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
```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 |
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](/docs/features/tool-retry-policy).
***
## What Gets Retried
| Outcome | Retried? |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Tool declares `@tool(restart_safe=False)` / `.idempotent = False` β **any** retryable error (sync **and** async) | β (runs exactly once β PR #4299 restored async parity) |
| Wall-clock (outer) timeout β mutating tool (in `MUTATING_TOOLS`) or unknown tool | β (surfaced once β see [Tool Timeouts](/docs/features/tool-timeout#retry-on-timeout-is-opt-in-for-mutating-tools)) |
| Wall-clock (outer) timeout β **idempotent** tool | β
|
| Circuit breaker open | β
|
| Unexpected exceptions (not `ValueError` / `TypeError` / `AttributeError`) | β
|
| Guardrail validation failures | β
|
| Tool returns `{"error": ...}` without `timeout` / `circuit_open` | β |
| Programming errors (`ValueError`, `TypeError`, `AttributeError`) | β |
A wall-clock timeout is retried **only** when the tool is idempotent β unknown tools default to non-idempotent (safe). Opt in with `.idempotent = True`; see [Tool Timeouts β Retry-on-timeout is opt-in](/docs/features/tool-timeout#retry-on-timeout-is-opt-in-for-mutating-tools).
A tool that **explicitly** declares itself unsafe (`restart_safe=False` or `.idempotent = False`) is vetoed from **every** retryable error, not just timeouts. Merely sharing a name with an entry in `MUTATING_TOOLS` does **not** count as a declaration β undeclared tools always retry per policy. `MUTATING_TOOLS` still gates the wall-clock-timeout retry (see [Tool Timeouts](/docs/features/tool-timeout#retry-on-timeout-is-opt-in-for-mutating-tools)).
***
## Retrying Non-Idempotent Tools
**Fixed in PR [#4283](https://github.com/MervinPraison/PraisonAI/pull/4283).** Between PRs #4257 and #4283, an undeclared tool whose name happened to match an entry in `MUTATING_TOOLS` (e.g. `write_file`, `store_memory`, `mkdir`) silently ran once instead of retrying. Only explicit `restart_safe=False` / `.idempotent = False` declarations veto the retry now.
**Async parity fixed in PR [#4299](https://github.com/MervinPraison/PraisonAI/pull/4299)** (issue [#4298](https://github.com/MervinPraison/PraisonAI/issues/4298)). Before #4299, `@tool(restart_safe=False)` / `.idempotent = False` was ignored on the async retry path β `agent.achat()` / `agent.astart()` / `agent.execute_tool_async()` re-ran the tool body up to `max_attempts` times (default: 3Γ on a card-charging tool, an email tool, a `POST`). The declaration was already honoured on the sync path. Both paths now run declared-unsafe tools exactly once.
A tool that declares itself unsafe to re-run is executed exactly once, even when the error would otherwise be retryable β the body already ran and may have completed its side effect before raising, so retrying would duplicate it.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Fail[π§ Tool fails with a retryable error] --> Q{Declared unsafe?}
Q -->|Undeclared| Retry[π Retries per policy]
Q -->|restart_safe=True / idempotent=True| Retry
Q -->|restart_safe=False / idempotent=False| Once[π Runs once β failure returned as-is]
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#10B981,stroke:#7C90A0,color:#fff
classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
class Fail agent
class Q config
class Retry process
class Once warn
```
Declare it on the decorator and the retry budget is ignored for that tool:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, tool
@tool(restart_safe=False)
def charge_card(amount: str) -> str:
"""Charge a customer's card β must never be re-driven."""
return billing.charge(amount)
agent = Agent(
name="Billing Agent",
instructions="Charge the customer for the pending invoice.",
tools=[charge_card],
max_retry_limit=3, # ignored for charge_card β it runs once
)
agent.start("Charge invoice #A-1042 for $99")
```
The declaration is discovered in this order (first match wins):
* `tool.idempotent` set to a `bool` on the tool object.
* `tool.restart_safe` β the public `@tool(restart_safe=...)` / `BaseTool.restart_safe` contract.
* When `ToolConfig(allow_global_tools=True)` is set, a matching global-registry tool's `idempotent` / `restart_safe` attribute (parity with idempotency lookup).
**What is not a declaration:** merely sharing a name with an entry in `MUTATING_TOOLS` (a 73-name registry used elsewhere for the escalation loop guard) is not an author declaration and does **not** disable retries. To opt an unsafe tool out of retries, mark it explicitly with `@tool(restart_safe=False)` or `.idempotent = False`.
This is the **same declaration** honoured by durable resume: an in-flight `restart_safe=False` tool returns `NotSafelyResumable`, and a failing one is not re-driven here. See [Durable Runs β Restart-Safety Contract](/docs/features/durable-tool-runs#restart-safety-contract-for-tools).
**Task-scoped tools inherit the veto.** A tool supplied only through the task's `tools_override` (never registered on the agent) still has its `restart_safe=False` / `idempotent=False` declaration honoured. Task-scoped tools shadow same-named agent tools, so if you attach a safer version at task time it wins over the agent-level tool. (PR #4299)
***
## 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.
A tool that sends, writes, charges, or deletes should declare `@tool(restart_safe=False)` (or set `.idempotent = False`). The tool body runs before it can raise, so retrying after a transient error would duplicate the side effect. Declared-unsafe tools run exactly once regardless of `max_retry_limit`.
Very large backoff factors cannot exceed a 60-second base delay per attempt. The cap only matters when retries actually happen β declared-unsafe tools do not retry.
Guardrail validation retries use the same `ExecutionConfig` backoff values. This is independent of tool retry β the fields still feed guardrail-retry backoff even when a `ToolConfig(retry_policy=...)` overrides the tool budget.
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.
***
## Related
Full execution configuration reference
Input and output validation
Cap tool calls per turn
LLM-level retry and error handling