> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/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.

Create an agent that inventories a messy folder and proposes an organization.

## 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

<Steps>
  <Step title="Set up your virtual environment">
    Requires [uv](https://docs.astral.sh/uv/).

    <CodeGroup>
      ```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
      ```
    </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-***
      ```

      ```powershell Windows theme={null}
      $env: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, 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:

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

  <Step title="Run your service">
    ```bash theme={null}
    python workbench.py
    ```

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

  <Step title="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.
  </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 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 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:7777`), 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://mintcdn.com/agno-v2/IxxNNGmoAN3arOWS/videos/agentos-connect-and-chat.mp4?fit=max&auto=format&n=IxxNNGmoAN3arOWS&q=85&s=1c439baefbf47ec5786b27741bb103fb" type="video/mp4" data-path="videos/agentos-connect-and-chat.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>
  Session records stay 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 coding agents →](/agent-platform/overview)