Skip to main content

sturdytools

Retries, timeouts, rate limits and circuit breakers for the tools an AI agent calls.

PyPI tests Python 3.9+ License: MIT

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.

Demo: a plain tool crashes, the wrapped tool retries, times out, and stops calling a service that is down

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:

  1. If the circuit breaker is open, stop right away.
  2. Wait for the rate limiter.
  3. Run the tool with the time limit.
  4. If it raised a temporary error and retries are left, wait and go back to step 1.
  5. 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 ToolTimeout right 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)

Source distribution for sturdytools 0.1.0
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)

Table of built distributions (wheels) for sturdytools 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page