AgentOS Runtime

AgentOS serves agents, teams, and workflows through a FastAPI application you own and host. The runtime provides execution APIs, persistent state, authorization, tracing, and operational endpoints.

agent_os.py

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

db = SqliteDb(db_file="tmp/agentos.db")

assistant = Agent(
    id="assistant",
    model=OpenAIResponses(id="gpt-5.4"),
)

agent_os = AgentOS(
    id="product-agent-os",
    agents=[assistant],
    db=db,
    tracing=True,
)

app = agent_os.get_app()

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

The AgentOS database becomes the default for local agents, teams, and workflows that do not define their own database. In this example it stores the agent's sessions and the runtime's traces.

Choose Runtime Capabilities

Add capabilities as the application needs them:

Requirement	AgentOS configuration	Guide
Serve agents, teams, and workflows	`agents`, `teams`, `workflows`	Using the API
Use a shared default database	`db`	Database
Require JWT authorization	`authorization=True`	Authorization
Store execution traces	`tracing=True`	Tracing
Expose an MCP server	`mcp=True`	AgentOS as MCP Server
Serve bounded public components	`public=PublicSurface(...)`	Public Surface
Persist accepted background jobs	`queue=QueueConfig(durable=True)`	Durable queue
Mount product and messaging interfaces	`interfaces=[...]`	Interfaces
Run cron schedules	`scheduler=True`	Scheduler
Extend an existing FastAPI application	`base_app=app`	Bring Your Own FastAPI App

Database Behavior

Configuration	Behavior
Set `db` on AgentOS	Components without a database inherit the AgentOS database
Set a database on a component	That component keeps its own database
Set `db` and `tracing=True`	AgentOS stores all traces in the AgentOS database
Omit `db` with `tracing=True`	AgentOS uses the first component database it discovers
Keep `auto_provision_dbs=True`	AgentOS creates the required tables when the application starts

Set an explicit AgentOS database when the runtime manages several component databases. This gives tracing, service accounts, and scheduled jobs a predictable store.

get_app() assembles the configured FastAPI routes. When the application starts, AgentOS combines your lifespan with the lifespans needed by the base app, MCP clients and server, databases, scheduler, and durable workers. Shutdown exits those managed lifespans and releases their resources.

Use an application lifespan for initialization your service owns, such as preparing a published-page Knowledge store. Durable jobs require the queue to be enabled; database persistence alone does not make an in-process background task survive a restart. See multiple replicas for shared cancellation and event delivery.

Runtime Methods

Method	Purpose
`get_app()`	Build and return the configured FastAPI application
`serve()`	Start the application with Uvicorn
`get_routes()`	Return the FastAPI routes mounted by AgentOS
`resync(app)`	Discover, initialize, and configure agents, teams, workflows, databases, and knowledge on an existing app

Host and Port

serve() reads AGENT_OS_HOST and AGENT_OS_PORT. Environment variables take precedence over method arguments.

Setting	Default
`AGENT_OS_HOST`	`localhost`
`AGENT_OS_PORT`	`7777`

export AGENT_OS_HOST=0.0.0.0
export AGENT_OS_PORT=8000
python agent_os.py

Next Steps

Task	Guide
Call the runtime from an application	Using the API
Add AgentOS to an existing backend	Bring Your Own FastAPI App
Configure the Control Plane experience	AgentOS Configuration
Review every constructor parameter	AgentOS class reference