About this site

Agent Harnesses Explained takes apart the program that turns a chat model into an agent: the loop, the tool calls, the context budget, prompt caching, permissions, sub-agents, hooks and sandboxing, failure and recovery, the public harnesses compared, and the cost and latency of a task, one chapter each, each around an animation. It is the first of a family of agent sites (the second, Agent Protocols Explained, follows the same tool calls onto the wire; the third, Agent Context Explained, what goes into the window and how an agent remembers beyond it; the fourth, Agent Orchestration Explained, graphs, multi-agent patterns and durable execution), next to the LLM-systems sites (the Transformer Decoder Explainer, LLM Inference Explained, GPU Kernels Explained, Inference Trade-offs Explained and others, all in the header's switch).

The engine

Every animation is a run of Agent_Loop_Sim, vendored into this site at commit 05d7720 (VENDORED.json records each file's SHA-256). Its Python reference and the TypeScript port the site runs produce the same events, token for token and float for float; the site's CI regenerates its fixtures from the Python reference installed at that commit and requires the port to match them. It has:

• a model interface with a scripted back end (a deterministic policy for every teaching run), a replay back end (recorded traces, checked prompt by prompt) and, offline only, a local back end (llama.cpp);
• a real tokenizer: Qwen2.5's byte-level BPE, vendored, which gave the same ids as llama.cpp's on every prompt the scenarios send;
• fake tools over an in-memory world: a file system, a shell simulator whose pytest really evaluates the tiny repository's tests, search over a fixed corpus, a calculator;
• accounting: a prompt-cache model, a dated price table and a time-to-first-token plus tokens-per-second latency model;
• the harness policies: loop style, parallel calls, turn limits, permissions with a simulated human, context strategies, prompt layouts, sub-agents, hooks, retries with back-off and loop detection;
• a versioned trace format (JSON Lines, with a JSON Schema) and a seeded random-number generator (mulberry32) shared by both languages.

What is real and what is illustrative

• Real: token counts; the recorded traces (provenance); the local model's measured speed (42.7 tokens/s prefill, 16.5 tokens/s decode); the price figures as published on the date given.
• Illustrative: the hosted-model latency, tool latencies and the simulated human's answer times; the prompt-cache model (a simple prefix model of the providers' documented rules); the scripted policies and the scripted summariser; the tiny context windows of chapter 3; chapter 7's command-line sandbox; chapter 8's tool failure rate; chapter 9's harness imitations, which are a policy imitation, not the product. Every chapter marks these.
• Costs combine Qwen2.5 token counts with other providers' list prices: "this many tokens at that price", not a quote.
• Descriptions of public harnesses come from their documentation, with an access date; anything not read from a document is marked as inferred.

How it is checked

• Engine: Python tests and exact TS parity on every scenario, policy and replay (in Agent_Loop_Sim's CI).
• Site: the vendored files' hashes; the chapters' runs and animation frames against the Python reference (unit tests); key frames' captions on the page (end-to-end); every number in the prose is computed by the engine at build time; every code block is cut from the vendored engine.
• Every animation plays, pauses, steps, scrubs and resets from the keyboard, with no console errors, in light and dark mode at 1,280 and 390 px wide; nothing plays by itself with reduced motion; axe finds no accessibility violations; Lighthouse scores at least 0.9.

Go deeper

The slides behind the chapters: the Agents and Coding Agents series. Source and issues: GitHub.