> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AgentOS Middleware
> Add authentication, logging, monitoring, and security features to your AgentOS application using middleware
v2.1.0
AgentOS is built on FastAPI, allowing you to add any [FastAPI/Starlette compatible middleware](https://fastapi.tiangolo.com/tutorial/middleware/) for authentication, logging, monitoring, and security. Agno provides built-in JWT middleware for authentication, and you can create custom middleware for rate limiting, request logging, and security headers.
Additionally, Agno provides some built-in middleware for common use cases, including authentication.
See the following guides:
Create your own middleware for logging, rate limiting, monitoring, and security.
Built-in JWT authentication with automatic parameter injection and claims extraction.
Use the built-in JWT middleware with Role-based access control and fine-grained permission scopes.
## Quick Start
Adding middleware to your AgentOS application is straightforward:
```python agent_os.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 OpenAIResponses
from agno.agent import Agent
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")
agent = Agent(
name="Basic Agent",
model=OpenAIResponses(id="gpt-5.2"),
db=db,
)
# Create your AgentOS app
agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()
# Add middleware
app.add_middleware(
JWTMiddleware,
verification_keys=["your-jwt-verification-key"],
validate=True
)
if __name__ == "__main__":
agent_os.serve(app="agent_os:app", reload=True)
```
Test middleware thoroughly in your own staging environment before production deployment.
**Performance Impact:** Each middleware layer adds latency to requests.
## Common Use Cases
**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/middleware/jwt)
**Control access with permission scopes:**
* Validate JWT scopes against required permissions
* Per-resource access control (specific agents/teams/workflows)
* Admin scope for full access
* Customizable scope mappings
[Learn more about RBAC](/agent-os/security/rbac)
**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)
```
**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
```
## Middleware Execution Order
Middleware is executed in reverse order of addition. The last middleware added runs first.
```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)
## Developer Resources
### Examples
JWT authentication using Authorization headers for API clients.
JWT authentication using HTTP-only cookies for web applications.
Rate limiting and request logging middleware implementation.
Custom FastAPI app with JWT middleware and AgentOS integration.
Detailed RBAC scopes, permissions, and access control.
### External Resources
Official FastAPI middleware documentation and examples.
Starlette middleware reference and implementation guides.