AgentOS Middleware

AgentOS is built on FastAPI, so you can add any FastAPI/Starlette-compatible middleware for authentication, logging, monitoring, and security.

Agno ships with a built-in auth middleware (AuthMiddleware) that handles JWTs, service-account tokens, and the OS security key. You can write your own custom middleware for rate limiting, request logging, and security headers.

See the following guides:

Custom Middleware

Create your own middleware for logging, rate limiting, monitoring, and security.

JWT Middleware

Built-in JWT authentication with automatic parameter injection and claims extraction.

Authorization

JWT validation with role-based access control and fine-grained permission scopes.

Quick Start

This local example uses HS256 with a secret you supply. Install the dependencies, set the server keys, and start PostgreSQL on port 5532 with the shown credentials (or change db_url):

uv pip install -U "agno[os]" openai "psycopg[binary]"
export OPENAI_API_KEY="your_openai_api_key"
export JWT_VERIFICATION_KEY="replace-with-a-long-random-local-secret"

Save the code as agent_os.py and run python agent_os.py. It adds middleware to the FastAPI app returned by get_app():

agent_os.py

import os

from agno.os import AgentOS
from agno.os.middleware.jwt import AuthMiddleware
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(id="middleware-demo", agents=[agent])
app = agent_os.get_app()

# Add middleware
app.add_middleware(
    AuthMiddleware,
    verification_keys=[os.environ["JWT_VERIFICATION_KEY"]],
    algorithm="HS256",
    verify_audience=True,
    validate=True
)

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

In a second terminal with the same environment and secret, create a short-lived local token and request the configuration:

import os
import time

import httpx
import jwt

token = jwt.encode(
    {"sub": "demo-user", "aud": "middleware-demo", "exp": int(time.time()) + 300},
    os.environ["JWT_VERIFICATION_KEY"],
    algorithm="HS256",
)
response = httpx.get(
    "http://localhost:7777/config",
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.json())

Later middleware patterns assume their application-specific classes and callbacks are defined.

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

Prevent API abuse with rate limiting:

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:

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 Custom Middleware for complete rate-limiting and request-logging implementations.

Middleware Execution Order

Middleware is executed in reverse order of addition. The last middleware added runs first.

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: Aim for this execution order. Since the last middleware added runs first, add them in reverse:

Security middleware (CORS, security headers)
Authentication middleware (JWT, session validation)
Monitoring middleware (logging, metrics)
Business logic middleware (rate limiting, custom logic)

AgentOS Middleware

Custom Middleware

JWT Middleware

Authorization

Quick Start

Common Use Cases

Middleware Execution Order

Developer Resources

Examples

JWT with Headers

JWT with Cookies

Custom Middleware

Custom FastAPI + JWT

Authorization

External Resources

FastAPI Middleware

Starlette Middleware

On this page