Workshop · Build an AI agent in one Python file
Today we build Tidy, a small agent that cleans a messy Downloads folder. One file, two tools, one loop. Then you use the same recipe for your own daily tasks.
You ask: “Clean my Downloads folder.”
Result: you still have 10 files to move yourself.
You ask: “Clean my Downloads folder.”
Result: the folder is clean. You did nothing.
Every agent, small or huge, is built from the same four parts. Tidy uses the simplest version of each.
What you want, in plain English.
GOAL = "Clean up my Downloads folder…"
The brain. It reads the goal and decides the next move.
MODEL = "claude-opus-5-5"
The hands. Normal Python functions the model is allowed to ask for.
list_files() · move_file()
Repeat think, act, see until the goal is done.
for round_number in range(1, 16):
This is a replay of a real run of the code below. Press Next step and read the line under the screens.
Keyboard: → next step · R reset
The whole agent is one Python file. Read the left column first, then the code.
File: agent.py · Python 3.10 or newer · library: anthropic
Save the code as agent.py, open a terminal in the same folder, then do these three steps.
One time only.
pip install anthropicCreate a key at platform.claude.com. Never paste it inside the code.
export ANTHROPIC_API_KEY="sk-ant-..."$env:ANTHROPIC_API_KEY="sk-ant-..."The first run creates my_downloads with 10 demo files, then sorts them.
python agent.pyEach run is paid per token on your Anthropic account. For a cheaper run, change MODEL to "claude-haiku-5-5". To start again with a messy folder, delete my_downloads and run again.
--- Round 1 --- [THINK] I need to see what is in the folder before I sort anything. [ACT] list_files({}) [SEE] beirut_sunset.jpg budget_november.xlsx cv_2026.pdf …7 more files --- Round 2 --- [THINK] Sort by extension: images, documents, audio, video, other. [ACT] move_file({'filename': 'beirut_sunset.jpg', 'folder': 'Images'}) [SEE] Moved beirut_sunset.jpg -> Images/ …9 more moves --- Round 3 --- [ACT] list_files({}) [SEE] (no loose files left) --- Round 4 --- [AGENT] Sorted 10 files into 5 folders. Images 2, Documents 4, Audio 2, Videos 1, Other 1. Nothing was deleted. Stopped after 4 rounds. Reason: end_turn
Tidy is the training example. For a real daily task you change three things: what starts the agent, its goal and its tools. The loop stays exactly the same.
A fifth part makes an agent useful every day: the trigger, the thing that starts it. A chat message is only one of four.
You send it something: a text, a photo of a receipt, a voice note.
a Telegram bot receives itIt wakes up on its own, every morning at 8 or every Sunday night.
cron (Mac, Linux) · Task Scheduler (Windows)Something happens: a new email, a new file, a form is sent.
check every 5 minutes, or a webhookYou click once or type one command, and it does the whole job.
python agent.pyThe most useful daily agents never chat. They wake up, do the job and leave the result where you already look: a sheet, your calendar, a draft, a notification. No code? n8n, Make and Zapier each have an AI agent block built from the same parts.
Not every task needs an agent. Answer four questions before you build anything. Try the examples first, then your own task.
Does it repeat?Every day, every week, every month.
Does it need judgment?Reading, understanding, choosing, writing.
Can you give it the tools?Email, calendar, files, web, a sheet, an app with an API.
Is a mistake easy to undo?A wrong label is easy. A wrong payment is not.
About Tidy: sorting by file extension is a fixed rule, so a ten-line script could do the same job. We used it because you can watch every step. An agent earns its place when the job needs reading and judgment, for example “put each PDF in the folder of its course”.
An agent acts on real things. These four choices in the code keep it under control.
Two tools are enough for this job. Every extra tool is one more way to make a mistake.
The tools only work inside my_downloads. A name with / or .. is refused.
MAX_ROUNDS = 15. If the agent gets stuck, the loop ends anyway.
Tidy has no delete tool, so it cannot delete. In general the agent prepares, and a human approves anything that sends, pays or deletes.
Pick one task from your week and fill the card. The start of your agent.py writes itself on the right. The loop is the one you already have.
Edit GOAL so spreadsheets (.xlsx) go to a folder called Spreadsheets. Delete my_downloads and run again.
Write rename_file(old, new), add it to TOOLS and run_tool. Goal: put today's date at the start of every screenshot name.
Keep the loop. Replace the tools with read_file and write_file. Goal: read every .txt note and write one summary.md.