Getting Started with AgentOS

This guide walks you through creating, configuring, and deploying an AgentOS application from scratch.

Prerequisites

Before you begin, ensure you have:

Python 3.9 or higher
PostgreSQL database (recommended for production) or SQLite (for development)
OpenAI API key or other LLM provider credentials

Installation

Install Agno with FastAPI and database dependencies:

pip install -U agno fastapi uvicorn sqlalchemy psycopg

For production deployments, use PostgreSQL. SQLite is suitable for development and testing only.

Step 1: Create Your First Agent

Create a file called basic.py:

basic.py

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIChat
from agno.os import AgentOS

# Setup database connection
db = PostgresDb(
    id="basic-db",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"
)

# Create a basic agent
agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-4o"),
    db=db,
    enable_session_summaries=True,
    update_memory_on_run=True,
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

# Setup AgentOS
agent_os = AgentOS(
    id="basic-agent-os",
    description="My first AgentOS application",
    agents=[agent],
)

# Get the FastAPI app
app = agent_os.get_app()

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

Step 2: Start Your Database

For PostgreSQL with pgvector support:

# Using the cookbook script
./cookbook/scripts/run_pgvector.sh

# Or using Docker directly
docker run -d \
  --name agno-postgres \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e POSTGRES_DB=ai \
  -p 5532:5432 \
  pgvector/pgvector:pg16

For development with SQLite:

from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="agno.db")

Step 3: Run Your AgentOS

Start the server:

python basic.py

You should see output like:

╭─────────────────────────────────────────────────╮
│ AgentOS Started                                 │
│ ID: basic-agent-os                              │
│ Server: http://localhost:7777                   │
│ Docs: http://localhost:7777/docs                │
╰─────────────────────────────────────────────────╯

Step 4: Test Your Agent

View the interactive docs

Open http://localhost:7777/docs in your browser to see the auto-generated API documentation.

Check the configuration

Visit http://localhost:7777/config to see your AgentOS configuration:

{
  "id": "basic-agent-os",
  "description": "My first AgentOS application",
  "agents": [
    {
      "id": "basic-agent",
      "name": "Basic Agent"
    }
  ]
}

List available agents

curl http://localhost:7777/agents

Run your agent

curl -X POST http://localhost:7777/agents/basic-agent/runs \
  -F "message=Hello! What can you help me with?"

Adding More Capabilities

Add Tools

Enhance your agent with tools:

from agno.tools.websearch import WebSearchTools
from agno.tools.mcp import MCPTools

agent = Agent(
    name="Research Agent",
    model=OpenAIChat(id="gpt-4o"),
    tools=[
        WebSearchTools(),
        MCPTools(url="https://docs.agno.com/mcp"),
    ],
    db=db,
)

Add Knowledge Base

Integrate a knowledge base with vector search:

from agno.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

vector_db = PgVector(
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    table_name="agno_docs",
)

knowledge = Knowledge(
    name="Agno Docs",
    contents_db=db,
    vector_db=vector_db,
)

agent = Agent(
    name="Agno Agent",
    knowledge=knowledge,
    db=db,
)

Create a Team

Combine multiple agents into a team:

from agno.team import Team

researcher = Agent(name="Researcher", tools=[WebSearchTools()])
writer = Agent(name="Writer")

team = Team(
    id="research-team",
    name="Research Team",
    model=OpenAIChat(id="gpt-4o"),
    members=[researcher, writer],
    db=db,
    update_memory_on_run=True,
)

agent_os = AgentOS(
    agents=[researcher, writer],
    teams=[team],
)

Build a Workflow

Orchestrate multi-step processes:

from agno.workflow import Workflow
from agno.workflow.step import Step

workflow = Workflow(
    id="content-workflow",
    name="Content Creation Workflow",
    db=db,
    steps=[
        Step(
            name="research",
            description="Research the topic",
            agent=researcher,
        ),
        Step(
            name="write",
            description="Write the content",
            agent=writer,
        ),
    ],
)

agent_os = AgentOS(workflows=[workflow])

Configuration Options

AgentOS provides extensive configuration options:

agent_os = AgentOS(
    agents=[agent],
    authorization=True,
    authorization_config=AuthorizationConfig(
        verification_keys=["your-public-key"],
        algorithm="RS256",
        verify_audience=True,
    ),
    cors_allowed_origins=["https://yourdomain.com"],
)

Working with Sessions

AgentOS automatically manages sessions for conversation continuity:

# First message creates a session
response = agent.run(
    "What's the weather like?",
    session_id="user-123-session",
    user_id="user-123",
)

# Follow-up message uses the same session
response = agent.run(
    "How about tomorrow?",
    session_id="user-123-session",
    user_id="user-123",
)

Retrieve session history:

curl http://localhost:7777/sessions?user_id=user-123

Using Custom FastAPI App

Integrate AgentOS with an existing FastAPI application:

from fastapi import FastAPI

# Create your custom app
app = FastAPI(title="My Custom App")

# Add custom routes
@app.get("/custom")
async def custom_endpoint():
    return {"message": "Custom endpoint"}

# Create AgentOS with base_app
agent_os = AgentOS(
    agents=[agent],
    base_app=app,
    on_route_conflict="preserve_agentos",  # or "preserve_base_app" or "error"
)

# AgentOS adds its routes to your app
app = agent_os.get_app()

Environment Variables

Configure AgentOS via environment variables:

# Security
export OS_SECURITY_KEY="your-secret-key"
export JWT_VERIFICATION_KEY="your-jwt-key"

# Database
export POSTGRES_DB_URL="postgresql+psycopg://user:pass@host/db"

# API Keys
export OPENAI_API_KEY="sk-..."

# Runtime
export AGNO_API_RUNTIME="production"  # or "stg"

Testing Your AgentOS

import requests

response = requests.post(
    "http://localhost:7777/agents/basic-agent/runs",
    files={"message": (None, "Hello, agent!")}
)

print(response.json())

Common Patterns

Multiple Databases

postgres_db = PostgresDb(db_url="postgresql://...")
sqlite_db = SqliteDb(db_file="local.db")

agent1 = Agent(name="Agent 1", db=postgres_db)
agent2 = Agent(name="Agent 2", db=sqlite_db)

# AgentOS manages both databases
agent_os = AgentOS(agents=[agent1, agent2])

Shared Database with Different Tables

db1 = PostgresDb(
    id="shared-db",
    db_url="postgresql://...",
    session_table_name="agent1_sessions",
)

db2 = PostgresDb(
    id="shared-db",
    db_url="postgresql://...",
    session_table_name="agent2_sessions",
)

agent1 = Agent(name="Agent 1", db=db1)
agent2 = Agent(name="Agent 2", db=db2)

Registry for Dynamic Components

from agno.registry import Registry

registry = Registry()
registry.agents.append(agent1)
registry.teams.append(team1)

agent_os = AgentOS(
    db=db,
    registry=registry,  # Enables dynamic loading
)

Troubleshooting

Common issues and solutions:

Database Connection Errors

Verify database is running: docker ps
Check connection string format
Ensure database user has CREATE TABLE permissions

Port Already in Use

# Find process using port 7777
lsof -i :7777

# Use a different port
agent_os.serve(app="basic:app", port=8000)

Import Errors

# Ensure all dependencies are installed
pip install -U agno[all] fastapi uvicorn

Agent Not Found

Check agent ID matches the route: /agents/{agent_id}/runs
View available agents: GET /agents

Next Steps

Deployment Guide

Learn how to deploy AgentOS to production

Authentication

Secure your AgentOS with JWT and RBAC

API Reference

Complete API endpoint documentation

Cookbook Examples

Explore advanced patterns in the cookbook

Get Started

Core Building Blocks

Production Runtime

Memory & State

Knowledge & RAG

Advanced Features

Models

Tools & Integrations

Getting Started with AgentOS

Prerequisites

Installation

Step 1: Create Your First Agent

Step 2: Start Your Database

Step 3: Run Your AgentOS

Step 4: Test Your Agent

Adding More Capabilities

Add Tools

Add Knowledge Base

Create a Team

Build a Workflow

Configuration Options

Working with Sessions

Using Custom FastAPI App

Environment Variables

Testing Your AgentOS

Common Patterns

Multiple Databases

Shared Database with Different Tables

Registry for Dynamic Components

Troubleshooting

Next Steps

Deployment Guide

Authentication

API Reference

Cookbook Examples

Build docs developers (and LLMs) love

Get Started

Core Building Blocks

Production Runtime

Memory & State

Knowledge & RAG

Advanced Features

Models

Tools & Integrations

​Prerequisites

​Installation

​Step 1: Create Your First Agent

​Step 2: Start Your Database

​Step 3: Run Your AgentOS

​Step 4: Test Your Agent

​Adding More Capabilities

​Add Tools

​Add Knowledge Base

​Create a Team

​Build a Workflow

​Configuration Options

​Working with Sessions

​Using Custom FastAPI App

​Environment Variables

​Testing Your AgentOS

​Common Patterns

​Multiple Databases

​Shared Database with Different Tables

​Registry for Dynamic Components

​Troubleshooting

​Next Steps

Deployment Guide

Authentication

API Reference

Cookbook Examples

Build docs developers (and LLMs) love

Prerequisites

Installation

Step 1: Create Your First Agent

Step 2: Start Your Database

Step 3: Run Your AgentOS

Step 4: Test Your Agent

Adding More Capabilities

Add Tools

Add Knowledge Base

Create a Team

Build a Workflow

Configuration Options

Working with Sessions

Using Custom FastAPI App

Environment Variables

Testing Your AgentOS

Common Patterns

Multiple Databases

Shared Database with Different Tables

Registry for Dynamic Components

Troubleshooting

Next Steps