AgentOS

Parameters

Parameter	Type	Default	Description
`id`	`Optional[str]`	Generated	Derived from `name` when supplied, otherwise a UUID
`name`	`Optional[str]`	`None`	AgentOS name
`description`	`Optional[str]`	`None`	AgentOS description
`version`	`Optional[str]`	`None`	AgentOS version
`agents`	`Optional[List[Union[Agent, RemoteAgent, AgentProtocol, AgentFactory]]]`	`None`	List of agents available in the AgentOS. Also accepts factories, remote agents, and multi-framework adapters
`teams`	`Optional[List[Union[Team, RemoteTeam, TeamFactory]]]`	`None`	List of teams available in the AgentOS. Also accepts factories and remote teams
`workflows`	`Optional[List[Union[Workflow, RemoteWorkflow, WorkflowFactory]]]`	`None`	List of workflows available in the AgentOS. Also accepts factories and remote workflows
`db`	`Optional[Union[BaseDb, AsyncBaseDb]]`	`None`	Default database for the AgentOS. Agents, teams and workflows with no db use this one
`media_storage`	`Optional[Union[MediaStorage, AsyncMediaStorage]]`	`None`	Backend the media routes read stored media from. Defaults to the first one configured on an agent, team, or workflow
`checkpoint`	`Optional[Literal["runs", "tool-batch", "tools"]]`	`None`	Default checkpoint level for agents in this AgentOS. Agents without their own `checkpoint` setting inherit this one. `None` means no OS-level default and each agent falls back to `"runs"`
`knowledge`	`Optional[List[Knowledge]]`	`None`	List of standalone knowledge instances available in the AgentOS
`interfaces`	`Optional[List[BaseInterface]]`	`None`	List of interfaces available in the AgentOS
`a2a_interface`	`bool`	`False`	Whether to expose the OS agents and teams in an A2A server
`authorization`	`bool`	`False`	Whether to enable RBAC authorization
`authorization_config`	`Optional[AuthorizationConfig]`	`None`	Configuration for JWT verification when authorization is enabled
`cors_allowed_origins`	`Optional[List[str]]`	`None`	List of allowed CORS origins (merged with default Agno domains)
`config`	`Optional[Union[str, AgentOSConfig]]`	`None`	User-provided configuration for the AgentOS. Either a path to a YAML file or an `AgentOSConfig` instance.
`settings`	`Optional[AgnoAPISettings]`	`None`	Settings for the AgentOS API
`base_app`	`Optional[FastAPI]`	`None`	Custom FastAPI APP to use for the AgentOS
`lifespan`	`Optional[Any]`	`None`	Lifespan context manager for the FastAPI app
`mcp`	`Optional[Union[bool, MCPConfig]]`	`None`	Serve the OS over MCP (Model Context Protocol) at `/mcp`. Pass `True` for the eight default tools, or an `MCPConfig` to publish components and custom tools via `tools` and scope the default tools via `default_tools`, `include_tags`, and `exclude_tags`
`mcp_server`	`Optional[Union[bool, MCPConfig]]`	`None`	Deprecated alias for `mcp`
`mcp_auth`	`Optional[AuthProvider]`	`None`	`AuthProvider` that owns authentication for the MCP endpoint (OAuth for connector clients like claude.ai and ChatGPT). Use `AgentOSBuiltinAuth.from_env()` from `agno.os` for the built-in authorization server, or an external provider such as WorkOS `AuthKitProvider`. Requires the MCP server to be enabled via `mcp`
`on_route_conflict`	`Literal["preserve_agentos", "preserve_base_app", "error"]`	`"preserve_agentos"`	What to do when a route conflict is detected in case a custom base_app is provided.
`tracing`	`bool`	`False`	Enable OpenTelemetry tracing for all agents and teams
`auto_provision_dbs`	`bool`	`True`	Whether to automatically provision databases
`run_hooks_in_background`	`bool`	`False`	Run agent/team pre/post hooks as FastAPI background tasks
`queue`	`Optional[QueueConfig]`	`None`	Background run execution: per-replica concurrency cap, Redis coordination for multi-replica deployments, and the durable job queue. `None` keeps the process defaults (cap of 32 or `AGNO_BACKGROUND_MAX_CONCURRENCY`). See Background Execution and the QueueConfig fields
`event_stream`	`Optional[BaseEventStream]`	`None`	Explicit event stream override. Takes precedence over the stream `queue.redis` would configure. Defaults to the in-memory stream
`telemetry`	`bool`	`True`	Log minimal telemetry for analytics
`registry`	`Optional[Registry]`	`None`	Registry to use for the AgentOS
`scheduler`	`bool`	`False`	Whether to enable the cron scheduler
`scheduler_poll_interval`	`int`	`15`	Seconds between scheduler poll cycles
`scheduler_base_url`	`Optional[str]`	`None`	Base URL the scheduler uses for HTTP calls to the OS. Defaults to `http://127.0.0.1:7777`
`public`	`Optional[PublicSurface]`	`None`	Select registered components for bounded public serving. See Public Surface.
`internal_service_token`	`Optional[str]`	`None`	Token for scheduler-to-OS authentication. Auto-generated when the scheduler is enabled and no token is provided

Authorization

Enable RBAC by setting authorization=True and setting the JWT_VERIFICATION_KEY environment variable to your JWT public key:

from agno.os import AgentOS

agent_os = AgentOS(
    id="my-agent-os",
    agents=[my_agent],
    authorization=True,
)

Or for more control, you can use the AuthorizationConfig class:

from agno.os import AgentOS
from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    id="my-agent-os",
    agents=[my_agent],
    authorization=True,
    authorization_config=AuthorizationConfig(
        verification_keys=["your-jwt-verification-key"],
        algorithm="RS256",
    ),
)

See AuthorizationConfig for configuration options.

Functions

`get_app`

Get the FastAPI APP configured for the AgentOS.

`get_routes`

Get the routes configured for the AgentOS.

`serve`

Run the app, effectively starting the AgentOS.

Parameters:

app (Union[str, FastAPI]): FastAPI APP instance
host (str): Host to bind. Defaults to localhost
port (int): Port to bind. Defaults to 7777
workers (Optional[int]): Number of workers to use. Defaults to None
reload (bool): Enable auto-reload for development. Defaults to False
reload_includes (Optional[List[str]]): Extra file patterns to watch when reload=True. Defaults to None
reload_excludes (Optional[List[str]]): File patterns to ignore when reload=True. Defaults to None
access_log (bool): Enable the uvicorn access log. Defaults to False

AGENT_OS_HOST and AGENT_OS_PORT environment variables override host and port.

`resync`

Resync the AgentOS to discover, initialize and configure: agents, teams, workflows, databases and knowledge bases.