Lesson 41 of 1570
Your First Agent: A Walkthrough of What It Does
Follow a real agent run step by step — from prompt to result — and see exactly what happens inside. No code yet, just the anatomy of a successful task.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1The task
- 2agent trace
- 3reasoning
- 4tool calls
Concept cluster
Terms to connect while reading
Section 1
The task
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
A real-world agent trace, condensed. Each step: think, act, observe.
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
- 1Decomposition — the agent broke the goal into sub-steps.
- 2Tool choice — it picked the right command for each sub-step (find, mkdir, mv).
- 3Human checkpoint — it paused before a destructive action and asked permission.
- 4Verification — after acting, it confirmed the result instead of assuming.
- 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.
Key terms in this lesson
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Your First Agent: A Walkthrough of What It Does”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Builders · 32 min
Tools an Agent Might Have: Filesystem, Browser, Code
Agents are only as useful as their tools. Tour the big three — filesystem, browser, code execution — plus the emerging MCP ecosystem, with examples of what each unlocks.
Builders · 40 min
Builder Capstone: Design an Agent for Your Life
No code. Just design. Pick a real task you do every week and draft a complete agent spec — goal, tools, loop, stop, approvals, and what success looks like.
Builders · 30 min
The Four Ingredients: Goal, Tools, Loop, Stop
Every agent — fancy or simple, local or cloud — boils down to four parts. Learn the recipe and you can read any agent system like a menu.