Build Your First Agent

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

Create an agent that categorizes and organizes a messy folder.

Create your Agent

Save the following code as sorting_hat.py:

sorting_hat.py

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

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
2. Install dependencies

   uv pip install -U agno openai
   
3. Export your OpenAI API key

   Don’t have one? Get a key from platform.openai.com

   Mac

   export OPENAI_API_KEY=sk-***
   

   setx OPENAI_API_KEY sk-***
   
4. Run your Agent

   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:

workbench.py

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()

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

   uv pip install -U 'agno[os]'
   
2. Run your service

   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 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 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. 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 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”.

Click on Chat, and ask:

Categorize the files in your working dir

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

All session data is stored in your local database. No data leaves your system.

Next Steps

• Wire up Agno with your favorite coding agent →
• Build an agent platform managed entirely by Claude Code →