sturdytools
Retries, timeouts, rate limits and circuit breakers for the tools an AI agent calls.
An agent is only as reliable as its tools. A search API that drops one request in fifty, a database that hangs, or a service that hits its rate limit can end an agent run, or put a raw stack trace in front of the user. Most of these failures are temporary, and the rest can be handled if the model gets a clear message it can act on.
sturdytools is one decorator that handles this for any Python function, sync or async, with no dependencies.
from sturdytools import sturdy
@sturdy(timeout=10, retries=3, rate_limit="5/s", on_error="message")
def search_orders(customer_id: str) -> list:
"""Find recent orders for a customer."""
return orders_api.search(customer_id)
If the API drops a connection, the call is retried with backoff. If it hangs, the attempt is abandoned after 10 seconds. If it still fails after 3 retries, the model gets a short message instead of an exception:
Error: the tool 'search_orders' failed after 4 attempts (ConnectionError: connection reset by peer).
Check the arguments, try a different approach, or tell the user it is unavailable.
Install
pip install sturdytools
Python 3.9 or newer. No other packages are needed.
What it does
| Option | What it does | Default |
|---|---|---|
timeout |
Seconds before one attempt is abandoned with ToolTimeout |
none |
retries |
Extra attempts after the first one fails | 0 |
retry_on |
Errors that count as temporary. Only these are retried | Exception |
backoff, max_backoff |
Wait before the first retry, doubling each time with jitter, up to the cap | 0.5s, 8s |
rate_limit |
"5/s", "60/min", "1000/hour", or a shared RateLimiter |
none |
breaker |
A CircuitBreaker, or True for one per tool |
none |
fallback |
Value to return when the tool gives up. If callable, it gets the tool's arguments | none |
on_error |
"raise", "message", or your own function (name, error, attempts) |
"raise" |
on_retry |
Called as (attempt, error, delay) before each retry, for logging or metrics |
none |
Each call goes through the same steps:
- If the circuit breaker is open, stop right away.
- Wait for the rate limiter.
- Run the tool with the time limit.
- If it raised a temporary error and retries are left, wait and go back to step 1.
- Otherwise use the fallback, return a message, or raise, depending on the settings.
The wrapper keeps the original function name, docstring and signature, which is what agent frameworks read to build the tool description for the model. Put @sturdy closest to the function, under your framework's tool decorator.
Works with MCP servers and LangChain
The wrapper keeps the function's name, docstring and signature, so frameworks build the same tool description as before. Put @sturdy under the framework's decorator, closest to the function:
from mcp.server.mcpserver import MCPServer
from sturdytools import sturdy
server = MCPServer("weather")
@server.tool()
@sturdy(timeout=10, retries=2, on_error="message")
async def get_weather(city: str) -> str:
"""Current weather for a city."""
...
from langchain_core.tools import tool
from sturdytools import sturdy
@tool
@sturdy(timeout=10, retries=2, rate_limit="5/s", on_error="message")
def search_orders(customer_id: str) -> list:
"""Find recent orders for a customer."""
...
Checked with mcp 2.3 and langchain-core 1.8, for sync and async tools: the tool schema and description are unchanged, retries happen inside the tool call, and a tool that gives up returns the error message to the model as its result.
Sharing limits and breakers across tools
Several tools often call the same API. Give them one rate limiter and one breaker, so they respect the same limit and stop together when the service is down.
from sturdytools import CircuitBreaker, RateLimiter, sturdy
crm_limit = RateLimiter.parse("10/s")
crm_breaker = CircuitBreaker(failure_threshold=5, reset_after=30)
@sturdy(retries=2, rate_limit=crm_limit, breaker=crm_breaker, on_error="message")
def get_account(account_id: str) -> dict:
...
@sturdy(retries=2, rate_limit=crm_limit, breaker=crm_breaker, on_error="message")
def list_contacts(account_id: str) -> list:
...
After 5 temporary failures in a row, both tools stop calling the service for 30 seconds and tell the model it is paused. Then one trial call goes through. If it works, normal calls resume.
Async tools
The same decorator works on async def functions. Timeouts cancel the task, and the rate limiter and retries wait without blocking the event loop.
@sturdy(timeout=5, retries=2, fallback=lambda city: "weather unavailable")
async def get_weather(city: str) -> str:
async with httpx.AsyncClient() as client:
response = await client.get(WEATHER_URL, params={"q": city})
response.raise_for_status()
return response.text
Choosing what to retry
Retrying everything is rarely right. If the model passed a bad argument, retrying the same call wastes time and money. Limit retries to errors that are actually temporary:
@sturdy(retries=3, retry_on=(ConnectionError, TimeoutError), on_error="message")
def lookup_invoice(invoice_id: str) -> dict:
...
Here a KeyError for an unknown invoice goes straight back to the model as a message, so it can correct itself, and it does not count against the circuit breaker.
Try it
python examples/flaky_tools_demo.py
The demo uses a fake weather service that drops connections, hangs, and then goes down, and prints what a plain tool and a wrapped tool do in each case. No API keys are needed.
How it compares
- tenacity and stamina are excellent general retry libraries. If retries are all you need, use one of them.
- sturdytools is narrower and aimed at agent tools: timeouts, retries, rate limits, a circuit breaker and a fallback in one decorator, plus an error message written for the model, so a failing tool becomes something the agent can reason about instead of a crash.
- Agent frameworks have their own retry options (LangChain's
with_retry, retry policies on LangGraph nodes). Those retry a whole step. sturdytools works on the single tool function, so it behaves the same in any framework, or in none.
Limits
- Python cannot stop a running thread. When a sync tool times out, the caller gets
ToolTimeoutright away, but the original call keeps running in a background thread until it finishes on its own. For tools that can hang for a long time, prefer async, where the task is cancelled, or set a timeout in the client library as well. - Rate limits and breakers live in memory, per process. Several workers calling the same API each keep their own count.
Development
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
Tests run on Python 3.10, 3.12 and 3.13 on every push.
License
MIT
Metadata
Release files for sturdytools 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sturdytools-0.1.0.tar.gz | 15.9 kB | With provenance | Details for sturdytools-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sturdytools-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for sturdytools-0.1.0-py3-none-any.whl |
Total release size: 27.9 kB
Release files / sturdytools-0.1.0.tar.gz
| Download URL | sturdytools-0.1.0.tar.gz |
|---|---|
| Size | 15.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3658b807a79af398e5d99dfb8f93420931caaa23495e6997a478a8e5eac91b1b
|
|
BLAKE2b-256 checksum How to use checksums |
c9d74ae716f7f73506d10482591e8d0640223b0a6ce286150b320e55b9deaab1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / sturdytools-0.1.0-py3-none-any.whl
| Download URL | sturdytools-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
724d4adbe83b54c8814ea8144decd99690336ac2e0ed64bbc55d2d79870c6af9
|
|
BLAKE2b-256 checksum How to use checksums |
0e864ac60ad32e53786f31c227283b5a914382868836d102f1057c9f8b958a6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for sturdytools 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sturdytools-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.