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 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:

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.

RBAC

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:

agent_os.py

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

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

RBAC Authorization

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

Rate Limiting

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)

Logging

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

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: 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 with Headers

JWT authentication using Authorization headers for API clients.

JWT with Cookies

JWT authentication using HTTP-only cookies for web applications.

Custom Middleware

Rate limiting and request logging middleware implementation.

Custom FastAPI + JWT

Custom FastAPI app with JWT middleware and AgentOS integration.

RBAC Documentation

Detailed RBAC scopes, permissions, and access control.

External Resources

FastAPI Middleware

Official FastAPI middleware documentation and examples.

Starlette Middleware

Starlette middleware reference and implementation guides.