> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-agui.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install & Setup

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

Let's get our dev environment setup 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.10 or newer. We recommend [`uv`](https://docs.astral.sh/uv/), but `pip` works fine too.

<CodeGroup>
  ```bash uv theme={null}
  uv venv --python 3.12
  source .venv/bin/activate
  ```

  ```bash pip (Mac/Linux) theme={null}
  python3 -m venv .venv
  source .venv/bin/activate
  ```

  ```bash pip (Windows) theme={null}
  python -m venv .venv
  .venv\Scripts\activate
  ```
</CodeGroup>

## 2. Install Agno

Install the agno SDK plus the OpenAI provider.

<CodeGroup>
  ```bash uv theme={null}
  uv pip install -U agno openai
  ```

  ```bash pip theme={null}
  pip install -U agno openai
  ```
</CodeGroup>

## 3. Export your API key

Don't have one? [Get a key from platform.openai.com](https://platform.openai.com/api-keys).

<CodeGroup>
  ```bash Mac/Linux theme={null}
  export OPENAI_API_KEY=sk-***
  ```

  ```bash Windows theme={null}
  setx OPENAI_API_KEY sk-***
  ```
</CodeGroup>

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](/models/overview) 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.

```python sorting_hat.py theme={null}
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:

```bash theme={null}
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:

<CodeGroup>
  ```bash uv theme={null}
  uv pip install -U 'agno[os]'
  ```

  ```bash pip theme={null}
  pip install -U 'agno[os]'
  ```
</CodeGroup>

Save this as `workbench.py`:

```python workbench.py theme={null}
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()
```

Run it:

```bash theme={null}
fastapi dev workbench.py
```

Your AgentOS is now running at `http://localhost:8000`. Open [http://localhost:8000/docs](http://localhost:8000/docs) for the OpenAPI spec, or connect the UI:

1. Open [os.agno.com](https://os.agno.com) and sign in.
2. Click **Add OS** → **Local**.
3. Enter `http://localhost:8000`, 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:

```bash theme={null}
claude mcp add agno-docs https://docs.agno.com/mcp
```

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

```json .mcp.json theme={null}
{
  "mcpServers": {
    "agno-docs": {
      "type": "http",
      "url": "https://docs.agno.com/mcp"
    }
  }
}
```

For full setup, see: **[Using Agno with Coding Agents →](/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:

```bash theme={null}
docker run -d \
  --name agno-postgres \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e POSTGRES_DB=ai \
  -p 5432:5432 \
  -v agno-pgdata:/var/lib/postgresql/data \
  agnohq/pgvector:18
```

Set your `db=PostgresDb(db_url="postgresql://ai:ai@localhost:5432/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:

<CardGroup cols={3}>
  <Card title="Agents" icon="robot" iconType="duotone" href="/agents/overview">
    Build, run and debug agents
  </Card>

  <Card title="Teams" icon="users" iconType="duotone" href="/teams/overview">
    Coordinate multiple agents.
  </Card>

  <Card title="Workflows" icon="diagram-project" iconType="duotone" href="/workflows/overview">
    Build step-based pipelines.
  </Card>
</CardGroup>