Install & Setup

Set up your dev environment. Install, configure, and run your first agent.

Let’s get our dev environment set up for Agno. We will:

1. Create a virtual environment
2. Install Agno
3. Export API key
4. Run our first agent
5. Run our 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

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

python3 -m venv .venv
source .venv/bin/activate

python -m venv .venv
.venv\Scripts\activate

2. Install Agno

Install the Agno SDK plus the OpenAI provider.

uv

uv pip install -U agno openai

pip install -U agno openai

3. Export your API key

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

Mac/Linux

export OPENAI_API_KEY=sk-***

setx OPENAI_API_KEY sk-***

Any model provider works: Anthropic, Gemini, Groq, Mistral, Cohere, Ollama, and 25+ others. Set the corresponding API key and swap the model= argument. See Models for the full list.

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.

sorting_hat.py

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", "shell"])],
    instructions=(
        "Walk the folder, figure out what's there, and propose a clean organization. "
        "Decide the categories yourself. Use shell commands when they help (e.g. `file`, "
        "`pdftotext`). 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

You should see the agent reason through the folder, call tools, and return a structured summary. That’s your first agent built using Agno: 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

uv pip install -U 'agno[os]'

pip install -U 'agno[os]'

Save this as workbench.py:

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:

.mcp.json

{
  "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

Set your db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

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:

Agents

Build, run and debug agents

Teams

Coordinate multiple agents.

Workflows

Build step-based pipelines.