Your First Agent: A Walkthrough of What It Does

We give Claude (via Claude Code) this goal: 'Find all images larger than 2MB in my Downloads folder and move them into a folder called BigImages.' A human would do it in about five minutes. Let's watch the agent.

The trace

STEP 1 Think: I need to list files, check sizes, filter images, create a folder, move files. Act: list_files('~/Downloads') See: 42 files returned, mixed types. STEP 2 Think: I should filter to images and check sizes. I'll use a shell command. Act: shell('find ~/Downloads -type f \( -iname "*.jpg" -o -iname "*.png" -o -iname "*.heic" \) -size +2M') See: 7 files listed with paths. STEP 3 Think: Now create the destination folder. Check if it exists first. Act: shell('mkdir -p ~/Downloads/BigImages') See: Folder created (or already existed). STEP 4 Think: Move each file. I'll confirm before running if this is risky. Ask: 'I'm about to move 7 files into BigImages. Proceed? (y/n)' Human: y STEP 5 Act: shell('mv [the 7 files] ~/Downloads/BigImages/') See: Exit code 0, no errors. STEP 6 Think: Verify the move worked. Act: list_files('~/Downloads/BigImages') See: 7 images present. STOP Report: 'Done. Moved 7 files totaling 23.4 MB into ~/Downloads/BigImages.'

What you just saw

1. 1Decomposition — the agent broke the goal into sub-steps.
2. 2Tool choice — it picked the right command for each sub-step (find, mkdir, mv).
3. 3Human checkpoint — it paused before a destructive action and asked permission.
4. 4Verification — after acting, it confirmed the result instead of assuming.
5. 5Reporting — at the end, it summarized what changed.

What could go wrong

Imagine step 5 failed — 'permission denied.' A dumb agent would retry forever. A good agent would read the error, reason about it ('maybe a file is locked'), try a different approach, or stop and ask for help. Handling failure is what separates toy agents from useful ones.

In the next lesson, we look at what goes wrong when the trace doesn't go this cleanly — because most of the time, it doesn't.