---
title: "Python Decorators for AI Agents: Building Reusable Tool and Middleware Patterns"
description: "Learn how to build reusable decorators for AI agent tools including retry logic, caching, authentication, and rate limiting using functools.wraps and parametrized patterns."
canonical: https://callsphere.ai/blog/python-decorators-ai-agents-reusable-tool-middleware-patterns
category: "Learn Agentic AI"
tags: ["Python", "Decorators", "Design Patterns", "AI Agents", "Agentic AI"]
author: "CallSphere Team"
published: 2026-03-17T00:00:00.000Z
updated: 2026-05-06T01:02:43.675Z
---

# Python Decorators for AI Agents: Building Reusable Tool and Middleware Patterns

> Learn how to build reusable decorators for AI agent tools including retry logic, caching, authentication, and rate limiting using functools.wraps and parametrized patterns.

## Decorators as Agent Middleware

In web frameworks, middleware wraps every request with cross-cutting logic like authentication, logging, and rate limiting. AI agent frameworks need the same patterns for tool calls. Python decorators provide exactly this — they wrap functions with reusable behavior without modifying the function itself.

Every major AI framework uses decorators extensively. The OpenAI Agents SDK uses them for tool registration. LangChain uses them for chain composition. FastAPI uses them for route definition. Mastering decorators lets you build clean, composable agent architectures.

## Decorator Fundamentals

A decorator is a function that takes a function and returns a new function. The `@` syntax is syntactic sugar.

```mermaid
flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus
classify"]
    PLAN["Plan and tool
selection"]
    AGENT["Agent loop
LLM plus tools"]
    GUARD{"Guardrails
and policy"}
    EXEC["Execute and
verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus
next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff
```

```python
import functools
import time
from typing import Callable, TypeVar, ParamSpec

P = ParamSpec("P")
T = TypeVar("T")

def log_tool_call(func: Callable[P, T]) -> Callable[P, T]:
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
        print(f"[TOOL] Calling {func.__name__} with {kwargs}")
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"[TOOL] {func.__name__} completed in {elapsed:.3f}s")
        return result
    return wrapper

@log_tool_call
def web_search(query: str) -> str:
    # actual search implementation
    return f"Results for: {query}"
```

Always use `functools.wraps`. Without it, the decorated function loses its name, docstring, and type hints — which breaks tool registration in agent frameworks that inspect function metadata.

## Async Decorators for Agent Tools

Most AI agent tools are async. Your decorators must handle both sync and async functions.

```python
import asyncio
import functools
from typing import Callable, Any

def retry(max_attempts: int = 3, delay: float = 1.0):
    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        async def async_wrapper(*args, **kwargs) -> Any:
            last_error = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return await func(*args, **kwargs)
                except Exception as e:
                    last_error = e
                    if attempt  Any:
            last_error = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    last_error = e
                    if attempt  str:
    # API call that might fail
    pass
```

## Rate Limiting Decorator

When your agent calls external APIs, rate limiting prevents quota exhaustion.

```python
import asyncio
import functools
import time
from collections import deque

def rate_limit(calls_per_minute: int = 60):
    timestamps: deque = deque()

    def decorator(func):
        @functools.wraps(func)
        async def wrapper(*args, **kwargs):
            now = time.monotonic()
            # Remove timestamps older than 60 seconds
            while timestamps and now - timestamps[0] > 60:
                timestamps.popleft()

            if len(timestamps) >= calls_per_minute:
                sleep_time = 60 - (now - timestamps[0])
                await asyncio.sleep(sleep_time)

            timestamps.append(time.monotonic())
            return await func(*args, **kwargs)
        return wrapper
    return decorator

@rate_limit(calls_per_minute=20)
async def embed_text(text: str) -> list[float]:
    # call embedding API
    pass
```

## Tool Registration Decorator

Build a decorator that automatically registers functions as agent tools with metadata extracted from type hints and docstrings.

```python
import functools
import inspect
from typing import get_type_hints

TOOL_REGISTRY: dict[str, dict] = {}

def agent_tool(name: str = None, description: str = None):
    def decorator(func):
        tool_name = name or func.__name__
        tool_desc = description or func.__doc__ or "No description"
        hints = get_type_hints(func)

        params = {}
        sig = inspect.signature(func)
        for param_name, param in sig.parameters.items():
            param_type = hints.get(param_name, str).__name__
            params[param_name] = {"type": param_type}

        TOOL_REGISTRY[tool_name] = {
            "function": func,
            "description": tool_desc,
            "parameters": params,
        }

        @functools.wraps(func)
        async def wrapper(*args, **kwargs):
            return await func(*args, **kwargs)
        return wrapper
    return decorator

@agent_tool(name="search", description="Search the web")
async def web_search(query: str, max_results: int = 5) -> str:
    return f"Found {max_results} results for {query}"
```

## FAQ

### Why does functools.wraps matter for AI agent tools?

Agent frameworks like the OpenAI Agents SDK inspect function metadata — the name, docstring, and type annotations — to generate tool definitions for the LLM. Without `functools.wraps`, the decorator replaces this metadata with the wrapper's metadata, causing the LLM to see incorrect tool names and missing descriptions.

### Can I stack multiple decorators on one tool function?

Yes. Decorators apply bottom-up, so `@retry @rate_limit @log_tool_call def func` means the call passes through log_tool_call first, then rate_limit, then retry wraps the entire chain. Order matters — put retry outermost so it retries the entire decorated pipeline.

### How do I test decorated functions in isolation?

Access the original function via `func.__wrapped__` (available when you use `functools.wraps`). This lets you unit test the core logic without triggering retry delays, rate limits, or logging side effects.

---

#Python #Decorators #DesignPatterns #AIAgents #AgenticAI #LearnAI #AIEngineering

---

Source: https://callsphere.ai/blog/python-decorators-ai-agents-reusable-tool-middleware-patterns