Bring Your Own FastAPI App

AgentOS is built on FastAPI, which means you can integrate your existing FastAPI application, routes, middleware, dependencies, and deployment entrypoints with AgentOS.

app.py

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from fastapi import FastAPI

app = FastAPI(title="Product API")


@app.get("/account/{account_id}")
async def get_account(account_id: str):
    return {"account_id": account_id, "status": "active"}


support_agent = Agent(
    id="support-agent",
    model=OpenAIResponses(id="gpt-5.4"),
)

agent_os = AgentOS(
    agents=[support_agent],
    base_app=app,
)

app = agent_os.get_app()

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

The returned app serves both routes:

Route	Owner
`GET /account/{account_id}`	Product API
`POST /agents/support-agent/runs`	AgentOS

Handle Route Conflicts

Set on_route_conflict when the base application already defines a path and method used by AgentOS.

Value	Behavior	Use when
`"preserve_agentos"`	AgentOS replaces the conflicting base-app route	AgentOS should own its standard API paths
`"preserve_base_app"`	AgentOS skips the conflicting route	The product route must keep its existing behavior
`"error"`	Application construction raises a `ValueError`	Every conflict should block deployment

"preserve_agentos" is the default.

agent_os = AgentOS(
    agents=[support_agent],
    base_app=app,
    on_route_conflict="error",
)

See Override Routes for conflict examples and matching behavior.

Keep Existing Application Behavior

AgentOS prepares the supplied FastAPI app in place:

Existing behavior	AgentOS behavior
Routes and routers	Preserved unless they conflict with an AgentOS route
Middleware	Retained on the combined application
FastAPI dependencies	Continue to apply to the routes that declare them
Lifespan	Combined with the lifespan passed to AgentOS
CORS	Existing CORS middleware is updated with AgentOS origins, or AgentOS adds CORS middleware

Use AgentOS authorization for runtime access control. Keep product-specific FastAPI dependencies on the custom routes that need them.

Add Middleware

Add FastAPI or Starlette middleware to the base app before calling get_app():

from starlette.middleware import Middleware
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI(
    middleware=[
        Middleware(
            TrustedHostMiddleware,
            allowed_hosts=["api.example.com"],
        )
    ]
)

agent_os = AgentOS(
    agents=[support_agent],
    base_app=app,
)
app = agent_os.get_app()

See AgentOS Middleware for JWT validation, request context, logging, and custom middleware.

Combine Lifespans

Pass a lifespan to AgentOS when the runtime needs its own startup and shutdown work. AgentOS wraps the lifespan already configured on the base app.

from contextlib import asynccontextmanager


@asynccontextmanager
async def agent_os_lifespan(app):
    app.state.runtime_status = "ready"
    yield
    app.state.runtime_status = "stopped"


agent_os = AgentOS(
    agents=[support_agent],
    base_app=app,
    lifespan=agent_os_lifespan,
)

app = agent_os.get_app()

See Custom Lifespan for a complete example.

Run the Combined App

Install the AgentOS and FastAPI CLI dependencies:

uv pip install -U "agno[os]" openai "fastapi[standard]"

fastapi dev app.py

fastapi run app.py --host 0.0.0.0 --port 8000

uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4

Next Steps

Task	Guide
Resolve path and method conflicts	Override Routes
Add authentication and request middleware	AgentOS Middleware
Configure runtime authorization	Authorization
Run startup and shutdown logic	Custom Lifespan
Review `base_app` parameters	AgentOS class reference

Get Started

AgentOS

Example Usage

Bring Your Own FastAPI App

Handle Route Conflicts

Keep Existing Application Behavior

Add Middleware

Combine Lifespans

Run the Combined App

Next Steps

​Handle Route Conflicts

​Keep Existing Application Behavior

​Add Middleware

​Combine Lifespans

​Run the Combined App

​Next Steps

Handle Route Conflicts

Keep Existing Application Behavior

Add Middleware

Combine Lifespans

Run the Combined App

Next Steps