Install & Setup

Set up a development environment and run an agent locally. You will:

1. Create a virtual environment
2. Install Agno
3. Export an API key
4. Run your first agent
5. Run your agent as a service

1. Create a virtual environment

Agno needs Python 3.9 or newer. We recommend uv, but pip works fine too.

uv venv --python 3.12
source .venv/bin/activate

python -m venv .venv
.venv\Scripts\Activate.ps1

2. Install Agno

Install the Agno SDK plus the OpenAI provider.

uv pip install -U agno openai

3. Export your API key

Don't have one? Get a key from platform.openai.com.

export OPENAI_API_KEY=sk-***

Agno supports Anthropic, Gemini, Groq, Mistral, Cohere, Ollama, and other providers. This example needs a model that supports tool calling. Set the provider's API key and change the model= argument. See Models.

4. Run your first agent

Save this as sorting_hat.py. The agent walks your current directory, decides how to organize it, and prints a tidy summary.

from pathlib import Path

from agno.agent import Agent
from agno.tools.workspace import Workspace

folder = Path(__file__).parent

sorting_hat = Agent(
    name="Sorting Hat",
    model="openai:gpt-5.5",
    tools=[Workspace(root=str(folder), allowed=["read", "list", "search"])],
    instructions=(
        "Walk the folder, figure out what's there, and propose a clean organization. "
        "Decide the categories yourself. Return a tidy summary, a category breakdown, "
        "and a folder tree."
    ),
    markdown=True,
)

sorting_hat.print_response(f"Inventory and organize {folder}", stream=True)

Run it:

python sorting_hat.py

The agent lists and reads files, then returns an organized summary. It combines a model, tools, and instructions.

5. Run your agent as a service

The script above is fine as a one-off. To make the agent reachable over HTTP, with session storage, memory, and tracing, run it using AgentOS.

Install the runtime extras:

uv pip install -U 'agno[os]'

Save this as workbench.py:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.os import AgentOS
from agno.tools.workspace import Workspace

workbench = Agent(
    name="Workbench",
    model="openai:gpt-5.5",
    db=SqliteDb(db_file="workbench.db"),
    tools=[Workspace(".")],
    enable_agentic_memory=True,
    add_history_to_context=True,
    num_history_runs=3,
)

agent_os = AgentOS(agents=[workbench], tracing=True)
app = agent_os.get_app()

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

Run it:

python workbench.py

The __main__ block calls agent_os.serve(), which starts a uvicorn server with hot reload. Your AgentOS is now running at http://localhost:7777. Open http://localhost:7777/docs for the OpenAPI spec, or connect the UI:

1. Open os.agno.com and sign in.
2. Click Add OS → Local.
3. Enter http://localhost:7777, name it, and connect.

You now have sessions, memory, tracing, and a chat UI.

Wire up your coding agent

Agno is designed to be used with coding agents. The docs are exposed as an MCP server so your coding agent has live access to the surface area.

For Claude Code:

claude mcp add --transport http agno-docs https://docs.agno.com/mcp

You can also drop a .mcp.json in the repo:

{
  "mcpServers": {
    "agno-docs": {
      "type": "http",
      "url": "https://docs.agno.com/mcp"
    }
  }
}

For full setup, see: Using Agno with Coding Agents

A note on Postgres

Many examples and tutorials in this documentation use Postgres + pgvector instead of SQLite. Postgres is what we recommend for production, and pgvector lets you keep relational data and embeddings on the same engine.

The fastest way to run both locally is Docker:

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

Install the driver packages with uv pip install -U sqlalchemy psycopg, then set db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai") on your agent.

You're ready to build with Agno

You have an agent running locally, a path to serving it, your coding agent wired up, and Postgres ready when you need it. From here: