Get started with AgentOS by setting up a minimal local instance.
This guide will have you running your first agent in minutes, with optional paths to add advanced features through our examples.
AgentOS is a FastAPI app that you can run locally or in your cloud. If you want to build AgentOS using an existing FastAPI app, check out the Custom FastAPI App guide. Prerequisites
- Python 3.9+
- An LLM provider API key (e.g.,
OPENAI_API_KEY)
Installation
Create and activate a virtual environment:
# Create virtual environment
python -m venv venv
# Activate virtual environment
source venv/bin/activate
pip install -U agno "fastapi[standard]" uvicorn openai
Minimal Setup
Create my_os.py:
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.db.sqlite import AsyncSqliteDb
from agno.os import AgentOS
assistant = Agent(
name="Assistant",
model=OpenAIChat(id="gpt-5-mini"),
db=AsyncSqliteDb(db_file="my_os.db"),
instructions=["You are a helpful AI assistant."],
markdown=True,
)
agent_os = AgentOS(
id="my-first-os",
description="My first AgentOS",
agents=[assistant],
)
app = agent_os.get_app()
if __name__ == "__main__":
# Default port is 7777; change with port=...
agent_os.serve(app="my_os:app", reload=True)
It is recommended to use all of the async building blocks of Agno when building your AgentOS. For example, use async tool definitions, async database connections, async pre/post hooks, etc.This helps unlock maximum concurrency and performance when running your AgentOS.
Running Your OS
Start your AgentOS:
Access your running instance:
- App Interface:
http://localhost:7777 - Use this URL when connecting to the AgentOS control plane
- API Documentation:
http://localhost:7777/docs - Interactive API documentation and testing
- Configuration:
http://localhost:7777/config - View AgentOS configuration
- API Reference: View the AgentOS API documentation for programmatic access
Connecting to the Control Plane
With your AgentOS now running locally (http://localhost:7777), you can connect it to the AgentOS control plane for a enhanced management experience. The control plane provides a centralized interface to interact with your agents, manage knowledge bases, track sessions, and monitor performance.
Next Steps
