THE AGENT PATTERN
=================
User --> messages[] --> LLM --> response
|
stop_reason == "tool_use"?
/ \
yes no
| |
execute tools return text
append results
loop back -----------------> messages[]
That's it. Every AI coding agent is this loop.
Everything else is refinement.
Learn how modern AI agents work by building one from scratch -- 11 progressive sessions, from a simple loop to full autonomous teams.
Disclaimer: This is an independent educational project. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude Code" is a trademark of Anthropic.
learn-claude-code/
|
|-- agents/ # Python reference implementations
| |-- s01_agent_loop.py # while loop + bash
| |-- s02_tool_use.py # + Read, Write, Edit
| |-- s03_todo_write.py # + TodoWrite
| |-- s04_subagent.py # + Task tool / spawn
| |-- s05_skill_loading.py # + SKILL.md injection
| |-- s06_context_compact.py # + /compact (3-layer)
| |-- s07_task_system.py # + Tasks CRUD + deps
| |-- s08_background_tasks.py # + background threads
| |-- s09_agent_teams.py # + teammates + mailboxes
| |-- s10_team_protocols.py # + shutdown + plan approval
| |-- s11_autonomous_agents.py # + idle cycle + auto-claim
| +-- s_full.py # full combined reference
|
|-- docs/ # Mental-model-first documentation
| |-- s01-the-agent-loop.md
| |-- s02-tool-use.md
| |-- ...
| +-- s11-autonomous-agents.md
|
|-- web/ # Interactive learning platform
| |-- src/components/
| | |-- simulator/ # Step-through agent execution
| | |-- architecture/ # Flow diagrams, arch diagrams
| | |-- code/ # Python source viewer
| | +-- docs/ # Documentation renderer
| +-- src/app/[locale]/(learn)/
| +-- [version]/ # Per-session learning page
|
|-- skills/ # Skill files for s05
+-- .github/workflows/ci.yml # CI: typecheck + build
Phase 1: THE LOOP Phase 2: PLANNING & KNOWLEDGE
================= ==============================
s01: The Agent Loop s03: TodoWrite
| bash is all you need | plan before you act
| "The entire agent is a loop" | "Visible plans improve completion"
| |
+-> s02: Tools s04: Subagents
| Read, Write, Edit, Bash | fresh context via Task tool
| "The loop didn't change" | "Process isolation = context isolation"
|
s05: Skills
| SKILL.md + tool_result injection
| "Load on demand, not upfront"
|
s06: Compact
three-layer context compression
"Strategic forgetting"
Phase 3: PERSISTENCE Phase 4: TEAMS
================= =====================
s07: Tasks s09: Agent Teams
| persistent CRUD + dependencies | teammates + mailboxes
| "State survives /compact" | "Append to send, drain to read"
| |
s08: Background Tasks s10: Team Protocols
fire-and-forget threads + notify | shutdown + plan approval
"Fire and forget" | "Same request_id, two protocols"
|
s11: Autonomous Agents
idle cycle + auto-claim
"Poll, claim, work, repeat"
git clone https://github.com/anthropics/anthropic-cookbook
cd anthropic-cookbook/learn-claude-code
pip install -r requirements.txt
# Configure API key
cp .env.example .env
# Edit .env with your ANTHROPIC_API_KEY
# Run any session
python agents/s01_agent_loop.py # Start here
python agents/s11_autonomous_agents.py # Full autonomous teamThe web platform provides interactive visualizations for each session:
- Step-through simulator shows each agent loop iteration
- Architecture diagrams and execution flow visualizations
- Python source code viewer with syntax highlighting
- Session documentation with ASCII diagrams
cd web
npm install
npm run dev
# Open http://localhost:3000Session Claude Code Feature Tools Core Addition Key Insight
------- -------------------- ----- ------------------------- ----------------------------
s01 The Agent Loop 1 while + stop_reason Bash is all you need
s02 Tools 4 Read/Write/Edit/Bash The loop didn't change
s03 TodoWrite 5 TodoManager + nag Plan before you act
s04 Subagents 5 Task tool + spawn Fresh context per subagent
s05 Skills 5 SKILL.md injection Load on demand, not upfront
s06 Compact 5 3-layer compression Strategic forgetting
s07 Tasks 8 CRUD + dependency graph State survives /compact
s08 Background Tasks 6 threads + notifications Fire and forget
s09 Agent Teams 9 teammates + mailboxes Persistent agents + async mail
s10 Team Protocols 12 shutdown + plan approval Same request_id, two protocols
s11 Autonomous Agents 14 idle cycle + auto-claim Poll, claim, work, repeat
# Every AI agent is this loop:
def agent_loop(messages):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM,
messages=messages, tools=TOOLS,
)
messages.append({"role": "assistant",
"content": response.content})
if response.stop_reason != "tool_use":
return
results = []
for block in response.content:
if block.type == "tool_use":
output = TOOL_HANDLERS[block.name](**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})Each session adds ONE mechanism on top of this loop.
| Claude Code Feature | Session | What It Does |
|---|---|---|
| Agent loop | s01 | while (stop_reason == "tool_use") loop |
| Tools | s02 | Map of tool name -> handler function |
| TodoWrite | s03 | Create plan before execution, track completion |
| Subagents | s04 | Fresh message list per subagent via Task tool |
| Skills | s05 | SKILL.md content injected via tool_result |
| Compact (micro) | s06 | Old tool results replaced with placeholders |
| Compact (auto) | s06 | LLM summarizes conversation when tokens > limit |
| Tasks API | s07 | File-based tasks with dependency graph |
| Background tasks | s08 | Threaded commands + notification queue |
| Agent Teams | s09 | Named persistent agents with config.json |
| Mailbox | s09 | Append-only file-based messages, per-teammate |
| Shutdown protocol | s10 | request_id based FSM for graceful shutdown |
| Plan approval | s10 | Submit/review with request_id correlation |
| Idle cycle | s11 | Poll board, auto-claim unclaimed tasks |
Each doc follows a mental-model-first structure with ASCII diagrams:
- s01: The Agent Loop
- s02: Tools
- s03: TodoWrite
- s04: Subagents
- s05: Skills
- s06: Compact
- s07: Tasks
- s08: Background Tasks
- s09: Agent Teams
- s10: Team Protocols
- s11: Autonomous Agents
MIT
The model is the agent. Our job is to give it tools and stay out of the way.