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

An agent that works in your filesystem, remembers you across sessions, and runs as a production API. To go further and build an [agent platform](/tutorials/agent-platform/overview), start from the template.

## 1. Define 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.4",
    tools=[Workspace(".",
        allowed=["read", "list", "search"],
        confirm=["write", "edit", "delete", "shell"],
    )],  # read/write/edit/shell in this directory
    enable_agentic_memory=True,  # remembers across sessions
    add_history_to_context=True,  # include past runs
    num_history_runs=3,  # last 3 conversations
)

# Serve via AgentOS → streaming, auth, session isolation, API endpoints
agent_os = AgentOS(agents=[workbench], tracing=True, db=SqliteDb(db_file="agno.db"))
app = agent_os.get_app()
```

`Workspace(".")` scopes the agent to the current directory. `read`, `list`, and `search` run freely; `write`, `edit`, `delete`, and `shell` require human approval.

## 2. Run Your AgentOS

<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[os]' 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 AgentOS">
    ```bash theme={null}
    fastapi dev workbench.py
    ```

    Your AgentOS is now running at:

    `http://localhost:8000`

    API documentation is automatically available at:

    `http://localhost:8000/docs`
  </Step>
</Steps>

Now you have:

* A stateful agent served as a production API.
* Tracing and session monitoring enabled out of the box.
* Per-session storage and isolation, with JWT-based RBAC available for multi-user isolation.

No third-party services required.

## 3. Chat with your Agent

The [AgentOS UI](https://os.agno.com) connects your browser to your runtime.

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/agno-v2-docs-align-with-readme/videos/agentos-connect-and-chat.mp4" type="video/mp4" />
  </video>
</Frame>

**Click on Chat, and ask:**

> List the files here and tell me what kind of project this is.

The agent reads your workspace and answers grounded in what it actually finds.

Try a follow-up like "summarize the README" or "create a NOTES.md with three bullet takeaways". The second one will pause for your approval before the file is written, since `write` is in the confirm list.

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

<CardGroup cols={2}>
  <Card title="Build an agent platform" icon="layer-group" iconType="duotone" href="/tutorials/agent-platform/overview">
    The full template: clone, ship agents with Claude Code, deploy to Railway.
  </Card>

  <Card title="Start from a production template" icon="rocket-launch" iconType="duotone" href="/tutorials/pick-a-template">
    Scout, Dash, Coda. Pick the closest to what you're building.
  </Card>

  <Card title="Understand the runtime" icon="cubes" iconType="duotone" href="/runtime/overview">
    Why AgentOS exists and the work it handles for you.
  </Card>

  <Card title="Use Agno with your coding agent" icon="terminal" iconType="duotone" href="/coding-agents">
    Wire up agno documentation with your favorite coding agent.
  </Card>
</CardGroup>