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

# Build Your First Agent

> Build and run your first agent in 20 lines of code.

Let's learn by creating an agent that inventories a messy folder and proposes an new structure.

## Create your Agent

Save the following code as `sorting_hat.py`:

```python sorting_hat.py lines 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"])],
    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 your Agent

**1. Set up your virtual environment**

Requires [uv](https://docs.astral.sh/uv/).

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

```powershell Windows theme={null}
uv venv --python 3.12
.venv\Scripts\Activate.ps1
```

**2. Install dependencies**

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

**3. Export your OpenAI API key**

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

```bash Mac theme={null}
export OPENAI_API_KEY=sk-***
```

```powershell Windows theme={null}
$env:OPENAI_API_KEY="sk-***"
```

**4. Run your Agent**

```bash theme={null}
python sorting_hat.py
```

## Run your Agent as a Service

The code above is an ad-hoc Python script. If we need our agent to do anything useful, we need to run it as a service. We should also:

1. **Add session storage**, so we can have a conversation with our agent. Agno automatically manages session read, write and context injection for you.
2. **Add memory**, so our agent learns from usage patterns. Agno automatically handles memory management and exposes an `update_user_memory` tool to the agent.

Save the following code as `workbench.py`:

```python workbench.py lines 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"),  # session storage
    tools=[Workspace(".")],               # operate in this directory
    enable_agentic_memory=True,           # remembers across sessions
    add_history_to_context=True,          # add past runs to context
    num_history_runs=3,                   # last 3 runs
)

# Serve via AgentOS, get streaming, session isolation, API endpoints
agent_os = AgentOS(agents=[workbench], tracing=True)
app = agent_os.get_app()

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

Install new dependencies and run your Agent as a Service:

**1. Install new dependencies**

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

**2. Run your service**

```bash theme={null}
python workbench.py
```

The `__main__` block calls `agent_os.serve()`, which starts a uvicorn server with hot reload.

**3. Confirm server is running**

Your AgentOS is now running at `http://localhost:7777`.

Open [http://localhost:7777/docs](http://localhost:7777/docs) to view the API docs.

20 lines of code and you have:

* A stateful agent served as a production API
* Session storage and conversation history
* Tracing on every run
* Per-session isolation, with JWT-based RBAC available for multi-user isolation

No separate database or infrastructure service is required. The example requires an OpenAI API key, and the next step uses the hosted AgentOS UI.

## Give your Agent a UI

The code above serves the agent using AgentOS, a FastAPI runtime that serves the agent and related operations as REST APIs.

AgentOS also comes with a UI, available at: [os.agno.com](https://os.agno.com). It connects directly from your browser to the running API. Use it to test, monitor, and manage your agents in real time.

1. Open [os.agno.com](https://os.agno.com) and sign in.
2. Click **"Connect OS"**
3. Select **"Local"**, enter your endpoint URL (default: `http://localhost:7777`), name it "Local AgentOS", and click **"Connect"**.

<video autoPlay muted loop controls playsInline>
  <source src="https://mintcdn.com/agno-v2/IxxNNGmoAN3arOWS/videos/agentos-connect-and-chat.mp4?fit=max&auto=format&n=IxxNNGmoAN3arOWS&q=85&s=1c439baefbf47ec5786b27741bb103fb" type="video/mp4" />
</video>

**Click on Chat, and ask:**

```text theme={null}
Categorize the files in your working dir
```

Click Sessions or Traces in the sidebar to inspect stored conversations.

> [!TIP]
>
> Session records stay in your local database. No data leaves your system.

## Next Steps

* [Wire up Agno with your favorite coding agent →](https://agno-v2.mintlify.site/coding-agents.md)
* [Build an agent platform managed entirely by coding agents →](https://agno-v2.mintlify.site/agent-platform/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.