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

# Bring Your Own FastAPI App

> Integrate your own FastAPI app with AgentOS.

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

```python app.py theme={null}
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.

```python theme={null}
agent_os = AgentOS(
    agents=[support_agent],
    base_app=app,
    on_route_conflict="error",
)
```

See [Override Routes](https://agno-v2.mintlify.site/agent-os/custom-fastapi/override-routes.md) 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](https://agno-v2.mintlify.site/agent-os/security/authorization/overview.md) 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()`:

```python theme={null}
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](https://agno-v2.mintlify.site/agent-os/middleware/overview.md) 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.

```python theme={null}
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](https://agno-v2.mintlify.site/agent-os/lifespan.md) for a complete example.

## Run the Combined App

Install the AgentOS and FastAPI CLI dependencies:

```bash theme={null}
uv pip install -U "agno[os]" openai "fastapi[standard]"
```

```bash Development theme={null}
fastapi dev app.py
```

```bash Production theme={null}
fastapi run app.py --host 0.0.0.0 --port 8000
```

```bash Uvicorn theme={null}
uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
```

## Next Steps

| Task | Guide |
| - | - |
| Resolve path and method conflicts | [Override Routes](https://agno-v2.mintlify.site/agent-os/custom-fastapi/override-routes.md) |
| Add authentication and request middleware | [AgentOS Middleware](https://agno-v2.mintlify.site/agent-os/middleware/overview.md) |
| Configure runtime authorization | [Authorization](https://agno-v2.mintlify.site/agent-os/security/authorization/overview.md) |
| Run startup and shutdown logic | [Custom Lifespan](https://agno-v2.mintlify.site/agent-os/lifespan.md) |
| Review `base_app` parameters | [AgentOS class reference](https://agno-v2.mintlify.site/reference/agent-os/agent-os.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.