A new agent lesson every week

Why weekly, and why by email

Agent-building is not a thing you learn by reading a reference in one sitting. It is a handful of ideas that only stick once you have watched each one break: a loop that never terminates, a tool description the model keeps misreading, a context window that fills up two turns before the job is done. One idea a week, with something to run, is the pace that actually gets you to a working agent.

Email because it arrives whether or not you remembered to come back, and because the lessons build on each other in order. Nothing else is sent — no drip funnel, no "we noticed you haven't", no partner offers. One lesson, once a week.

What each lesson looks like

The same three parts every time, short enough to read on a break:

• One idea, in plain terms, with the reason it matters before the mechanics.
• The code — real, runnable, and small enough to read whole. Usually a file from this repository, because the harness is the textbook.
• An exercise you do in the harness: paste a key, type a prompt, watch the loop, then break it on purpose and see what the model does.

You need nothing installed. If you would rather not spend a cent on tokens, point the harness at Ollama or vLLM and every exercise runs on your own machine.

Where it goes

Roughly the path from a bare HTTP request up to something you would trust with real work:

• One completion call, by hand — what a model actually receives and returns.
• The tool-call loop: the fifty lines that turn a chat model into an agent.
• Writing tool definitions the model reads the way you meant.
• State: a filesystem the agent can trust, and an undo stack that rewinds the files and the conversation together.
• Context: what to keep, what to drop, and how compaction works without losing the thread.
• Eyes: screenshots in, so the model can see what it built.
• Hands: driving a page — click, type, scroll — and reading the result.
• Sub-agents, planning and multi-step work that survives a wrong turn.
• Sandboxing and the failure modes nobody warns you about.

The order may shift as the lessons get written — the list is the destination, not a contract. It has since been cut down to six units in a fixed order, easiest first: read the syllabus. The rest of the list above still arrives, hanging off whichever unit it belongs to.

How to start

Drop your address in the box at the top of this page — or in the one at the top of the transcript on the harness; they are the same list. The next lesson finds you; the ones you missed stay in this archive, so signing up late costs you nothing.

And you do not have to wait for an email to begin. Open KEYS, paste a key, and ask for an agent — the first exercise is one line:

scaffold a blocks.ai research agent, then run it

Vintage charm, aggressively anti-dystopian. Emdashes welcome.

open the harness