> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-docs-scavio-google-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](/agent-os/custom-fastapi/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](/agent-os/security/authorization/overview) 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](/agent-os/middleware/overview) 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](/agent-os/lifespan) 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]"
```

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Next Steps

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