> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc-agui.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 create an agent that categorizes and organizes a messy folder.

## 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", "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 your Agent

<Steps>
  <Step title="Set up your virtual environment">
    <CodeGroup>
      ```bash Mac theme={null}
      uv venv --python 3.12
      source .venv/bin/activate
      ```

      ```bash Windows theme={null}
      uv venv --python 3.12
      .venv\Scripts\activate
      ```
    </CodeGroup>
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    uv pip install -U agno openai
    ```
  </Step>

  <Step title="Export your OpenAI API key">
    Don't have one? [Get a key from platform.openai.com](https://platform.openai.com/api-keys)

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

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

  <Step title="Run your Agent">
    ```bash theme={null}
    python sorting_hat.py
    ```
  </Step>
</Steps>

## 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, auth, session isolation, API endpoints
agent_os = AgentOS(agents=[workbench], tracing=True)
app = agent_os.get_app()
```

Install new dependencies and run your Agent as a Service:

<Steps>
  <Step title="Install new dependencies">
    ```bash theme={null}
    uv pip install -U 'agno[os]'
    ```
  </Step>

  <Step title="Run your service using FastAPI">
    ```bash theme={null}
    fastapi dev workbench.py
    ```
  </Step>

  <Step title="Confirm server is running">
    Your AgentOS is now running at `http://localhost:8000`.

    Open [http://localhost:8000/docs](http://localhost:8000/docs) to view the API docs.
  </Step>
</Steps>

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 third-party services required.

## Give your Agent a UI

The code above runs our agent as a service using AgentOS. AgentOS is a FastAPI-based runtime that serves agents 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:8000`), name it "Local AgentOS", and click **"Connect"**.

<Frame>
  <video autoPlay muted loop controls playsInline style={{ borderRadius: "0.5rem", width: "100%", height: "auto" }}>
    <source src="https://mintlify.s3.us-west-1.amazonaws.com/phidatainc-agui/videos/agentos-connect-and-chat.mp4" type="video/mp4" />
  </video>
</Frame>

**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>
  All session data is stored in your local database, no data leaves your system.
</Tip>

## Next Steps

* [Wire up agno with your favorite coding agent. →](/coding-agents)
* [Build an agent platform managed entirely by claude code →](/agent-platform/overview)