> ## Documentation Index
> Fetch the complete documentation index at: https://spacesail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How to add middleware to your AgentOS application

AgentOS is built on FastAPI, which means you can add any [FastAPI/Starlette compatible middleware](https://fastapi.tiangolo.com/tutorial/middleware/) to enhance your application with features like authentication, logging, monitoring, security headers, and more.

Additionally, Agno provides some built-in middleware for common use cases, including authentication.

See the following guides:

<CardGroup cols={2}>
  <Card title="Custom Middleware" icon="code" href="/agent-os/customize/middleware/custom">
    Create your own middleware for logging, rate limiting, monitoring, and security.
  </Card>

  <Card title="JWT Middleware" icon="key" href="/agent-os/customize/middleware/jwt">
    Built-in JWT authentication with automatic parameter injection and claims extraction.
  </Card>
</CardGroup>

## Quick Start

Adding middleware to your AgentOS application is straightforward:

```python agent_os_with_jwt_middleware.py theme={null}
from agno.os import AgentOS
from agno.os.middleware import JWTMiddleware
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIChat
from agno.agent import Agent

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-5-mini"),
    db=db,
)

# Create your AgentOS app
agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()

# Add middleware
app.add_middleware(
    JWTMiddleware,
    secret_key="your-secret-key",
    validate=True
)

if __name__ == "__main__":
    agent_os.serve(app="agent_os_with_jwt_middleware:app", reload=True)
```

<Note>
  Always test middleware thoroughly in staging environments before production deployment.

  A reminder that middleware adds latency to every request.
</Note>

## Common Use Cases

<Tabs>
  <Tab title="Authentication">
    **Secure your AgentOS with JWT authentication:**

    * Extract tokens from headers or cookies
    * Automatic parameter injection (user\_id, session\_id)
    * Custom claims extraction for `dependencies` and `session_state`
    * Route exclusion for public endpoints

    [Learn more about JWT Middleware](/agent-os/customize/middleware/jwt)
  </Tab>

  <Tab title="Rate Limiting">
    **Prevent API abuse with rate limiting:**

    ```python theme={null}
    class RateLimitMiddleware(BaseHTTPMiddleware):
        def __init__(self, app, requests_per_minute: int = 60):
            super().__init__(app)
            self.requests_per_minute = requests_per_minute
            # ... implementation

    app.add_middleware(RateLimitMiddleware, requests_per_minute=100)
    ```

    See the [full example](/examples/agent-os/middleware/custom-middleware) for more details.
  </Tab>

  <Tab title="Logging">
    **Monitor requests and responses:**

    ```python theme={null}
    class LoggingMiddleware(BaseHTTPMiddleware):
        async def dispatch(self, request: Request, call_next):
            start_time = time.time()
            response = await call_next(request)
            process_time = time.time() - start_time
            # Log request details...
            return response
    ```

    See the [full example](/examples/agent-os/middleware/custom-middleware) for more details.
  </Tab>
</Tabs>

## Middleware Execution Order

<Warning>
  Middleware is executed in reverse order of addition. The last middleware added runs first.
</Warning>

```python theme={null}
app.add_middleware(MiddlewareA)  # Runs third (closest to route)
app.add_middleware(MiddlewareB)  # Runs second
app.add_middleware(MiddlewareC)  # Runs first (outermost)

# Request: C -> B -> A -> Your Route
# Response: Your Route -> A -> B -> C
```

**Best Practice:** Add middleware in logical order:

1. **Security middleware first** (CORS, security headers)
2. **Authentication middleware** (JWT, session validation)
3. **Monitoring middleware** (logging, metrics)
4. **Business logic middleware** (rate limiting, custom logic)

## Examples

<CardGroup cols={2}>
  <Card title="JWT with Headers" icon="shield" href="/examples/agent-os/middleware/jwt-middleware">
    JWT authentication using Authorization headers for API clients.
  </Card>

  <Card title="JWT with Cookies" icon="cookie" href="/examples/agent-os/middleware/jwt-cookies">
    JWT authentication using HTTP-only cookies for web applications.
  </Card>

  <Card title="Custom Middleware" icon="gear" href="/examples/agent-os/middleware/custom-middleware">
    Rate limiting and request logging middleware implementation.
  </Card>

  <Card title="Custom FastAPI + JWT" icon="code" href="/examples/agent-os/middleware/custom-fastapi-jwt">
    Custom FastAPI app with JWT middleware and AgentOS integration.
  </Card>
</CardGroup>