Skip to main content
Let’s 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

uv venv --python 3.12
source .venv/bin/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
export 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()
Install new dependencies and run your Agent as a Service:
1

Install new dependencies

uv pip install -U 'agno[os]'
2

Run your service using FastAPI

fastapi dev workbench.py
3

Confirm server is running

Your AgentOS is now running at http://localhost:8000.Open http://localhost:8000/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:8000), 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