Build an agent harness from scratch. Learn how to tell whether it works.
A source-first Python course: 20 foundation lessons, a new Responses API lab, and three reliability design lessons. No agent framework dependencies. Each step makes a small mechanism visible before adding another.
October 2026 edition · sources checked 2026-10-26. Start with the field guide for what's changed, update notes for this revision, or the 中文更新说明.
The original course's strength is its progression from one model call to a usable coding harness. This edition keeps that progression and makes the boundaries explicit: a successful demo is not a quality evaluation, a transcript is not durable execution, and a prompt is not an access-control mechanism.
Requires Python 3.10+. From the repository root:
python3 --version
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install -e ".[test]"
python -m pytest tests/ -q
python -m ruff check .The tests use mocks and a local MCP subprocess. They need no API key. The validation record records the environment tested for this update; it does not certify live model quality or account access.
For an opt-in live foundation demo:
export ANTHROPIC_API_KEY='your-key'
python -m chapters.ch00_welcome "what is 17 * 23?"For the new Responses lab, set an available compatible model explicitly:
export OPENAI_API_KEY='your-key'
export OPENAI_MODEL='your-supported-model-id'
python -m chapters.ch17b_responsesLive calls incur provider charges. Before using the capstone, read its permission boundary: agent.py can read files and execute a shell with the access of its process. Use an inspected, disposable workspace for experiments.
# Conceptual pseudocode: see the chapters for provider-specific details.
for step in range(step_budget):
response = call_model(context, tools)
validate_completion_and_tool_calls(response)
context.append(response)
if response.is_final:
return verify_outcome(response)
context.extend(execute_authorized_tools(response.tool_calls))The shared idea is model → tools → observations → model. A useful harness also owns state, permissions, limits, recovery, and evidence of completion. Commercial coding agents contain much more than this sketch.
flowchart LR
U[Task and acceptance criteria] --> C[Build context]
C --> M[Call model]
M --> V{Validate response}
V -->|tool calls| P[Check permissions and budgets]
P --> T[Execute tools]
T --> S[Record results and state]
S --> C
V -->|final answer| E[Check outcome]
V -->|incomplete or invalid| F[Report failure or recover]
| Reader | Start here | Result |
|---|---|---|
| New to agents; comfortable with Python | 00 → 05, then 06 → 10 | Explain and debug the tool loop |
| Returning reader | Field guide → 17b → 18–20 | Understand current interfaces and reliability gaps |
| Building a product | 18 → 19 → 20, then inspect agent.py |
Write acceptance tests, authority rules, and a recovery design |
| Teaching a class | SYLLABUS.md | Seven-week core plus optional reliability extension |
Foundation lessons have paired Python and Markdown files. Historical API/protocol examples are labelled where relevant; model availability and pricing must be checked before a live run.
| # | Chapter | What you'll learn |
|---|---|---|
| 00 | welcome | A complete working agent in 30 lines. The whole shape, in 5 minutes. |
| 01 | raw_call | One HTTP POST. The Messages API. No SDK. |
| 02 | messages_array | Application-managed history for the stateless Messages API. |
| 03 | stop_reasons | Foundation termination states and explicit handling of unknown states. |
| 04 | one_tool | The tool_use → tool_result protocol. One round-trip. |
| 05 | the_loop | THE LOOP. Six lines. Decomposition, ReAct, planning. The pivot chapter. |
| 06 | parallel_tools | Multiple tool_use blocks in one turn. The single-user-message rule. |
| 07 | errors | Tool errors as content. is_error: true. Refusals. |
| 08 | system_prompts | What goes in system vs messages. Persona that survives compaction. |
| 08b | observability | Estimate per-turn usage and cost; record pricing assumptions. |
| 08c | prompt_caching | Stable prefixes, model-specific thresholds, TTL, measured savings. |
| 09 | sessions | JSONL on disk. Resume after Ctrl-C. |
| 10 | compaction | Summarize context while preserving important state and tool pairs. |
| 11 | subagents | Isolate exploration; measure total cost and handoff quality. |
| 12 | skills | Markdown loaded on demand. Progressive disclosure. |
| 13 | mcp_wire | A pinned 2024-11-05 stdio tools subset; current protocol differs. |
| 14 | mcp_agent | Wire your own MCP server into the agent loop. |
| 15 | streaming_text | SSE basics. Render text deltas as they arrive. |
| 16 | streaming_tools | input_json_delta accumulation. The hard chapter. |
| 17 | multi_provider | Original Anthropic / Chat Completions / generateContent adapters. |
| ★ | agent.py | Educational coding CLI combining core primitives; see capability map below. |
| ★ | microsite/ | The capstone. Build a working website from one prompt. |
| Chapter | Format | What you should be able to demonstrate |
|---|---|---|
| 17b — Responses | Python + offline protocol tests | Preserve continuation and call IDs; reject incomplete responses |
| 18 — Evaluation | Design lesson + exercises | Judge environment outcomes and repeatability, not fluent answers |
| 19 — Permissions | Design lesson + exercises | Separate tool descriptions, user authority, and execution policy |
| 20 — Durable execution | Design lesson + exercises | Recover from a crash without blindly repeating an external write |
The three design lessons describe extensions to build. They do not imply those production subsystems are already implemented in the CLI.
| Capability | Standalone lesson | agent.py |
|---|---|---|
| Model/tool loop, local file tools, streaming | 00–08, 15–16 | Yes, Anthropic only |
| Conversation log and compaction | 09–10 | Yes; new snapshots replay after restart |
| Confirmation before Write/Edit/Bash | 19 explains the limits | Basic gate; no OS sandbox |
| Usage meter | 08b–08c | In-process estimate; not durable billing |
| Subagents | 11 | Exercise, not integrated |
| Skills discovery/loading | 12 | Exercise, not integrated |
| MCP connection | 13–14 | Separate legacy-protocol demo |
| Multiple providers / Responses | 17 / 17b | Separate examples |
| Outcome evaluation / transactional recovery | 18 / 20 | Design exercises, not production features |
- 2026 field guide: architecture, state, interoperability, and tool economics.
- Provider adaptation: original adapter limitations and current API paths.
- MCP version boundary: the pinned lab versus today's stable specification.
- Sources: primary references, dates, status, and implications.
- FAQ, validation, remaining work, and exam key.
Costs and performance are measured properties of a configuration, not promises printed on the cover. Record model ID, SDK, task, retries, cache use, and output size when comparing runs. Original illustrations and promotional media are retained as historical course assets; their embedded counts or price slogans may predate this edition.
Written by Ke Wang. GuiGui 🐢 remains the course mascot. The course is inspired by readable educational repositories such as Karpathy's micrograd, and by public documentation and implementations across the agent ecosystem.
MIT licensed. See LICENSE. Contributions should preserve small, inspectable lessons; read CONTRIBUTING.md.
