Demystifying Agent Harnesses
What's actually inside an agent harness, how the planner-tools-executor loop runs, and where each design knob lives. Coding agents are the running example; the patterns generalize.
14 lessons74 min read
An agent harness is the runtime around the model. Strip a harness down and you find six concerns: an execution loop, a typed tool registry, a context manager, a state store, lifecycle hooks, and an evaluation interface. Each one is a separate failure mode, each one is a separate place to look first when behavior gets weird. The two in amber, State and Eval, are the ones the rest of the industry systematically underbuilds.
The harness wraps the model. The model is opaque; the six concerns around it are not. Open lesson 2 for the full breakdown →
Lessons
- 1.What is a harness, really?5 min
A harness is the code around the model that decides what it sees, what it can call, and what survives between turns. Not the model. Not the prompt. The runtime around them.
- 2.The six components: E, T, C, S, L, V7 min
Every harness implements six runtime functions: Execution loop, Tool registry, Context manager, State store, Lifecycle hooks, and Evaluation interface. Six failure modes map one-to-one.
- 3.Anatomy of one harness turn6 min
Observe → think → act → commit. The deterministic stages around the model are where almost all harness design happens.
- 4.Context: compaction, resets, and anxiety7 min
Two ways past the context limit: summarize in place, or reset and hand off via files. Choice depends on the model and what your handoff artifacts can carry.
- 5.The tool registry and what makes it trustworthy5 min
Tools are typed, validated, and gated. The registry is where hallucinated calls become impossible — or where they slip through.
- 6.State stores and lifecycle hooks5 min
State (S) is what survives turns. Lifecycle hooks (L) intercept every call for auth, logging, and policy. Both are systematically underbuilt.
- 7.The evaluation interface — and why it's underbuilt5 min
V captures structured trajectories so something downstream can score them. Most harnesses log to text and stop there. That's why traces win and summaries lose.
- 8.Six failure modes, six fixes6 min
Execution runaway, tool misuse, context blowout, state loss, unmonitored side effects, unobservable behavior. Each maps to one component, each has a known harness-level fix.
- 9.The generator–evaluator loop6 min
Self-evaluation is unreliable. Splitting the doer from the judge — and tuning the judge to be skeptical — is the first structural lever you reach for on subjective work.
- 10.The initializer + coding-agent pattern5 min
Two prompts, one harness. The initializer writes durable artifacts; the coding agent reads them at session start. This is how Claude Code stays coherent across days.
- 11.Natural-language harnesses (CLAUDE.md, skills, AGENTS.md)6 min
The control logic of a harness can live in editable text. Contracts, roles, stages, state semantics, failure taxonomy — written once, run by a shared runtime.
- 12.Meta-harness: searching the harness space6 min
If harness design matters this much, automate it. Give a coding agent grep-and-cat over prior runs and let it propose new harnesses. Raw traces beat summaries by a wide margin.
- 13.Glossary3 min
Every term-of-art used across the topic, with one-line definitions.
- 14.Sticky-note appendix2 min
The seven things that change how you read every harness paper afterward.