Harness Engineering 101
The LLM is the brain. The harness is the body.
By Isuru Wijesiri. Version 1.1, October 2026.
AI usage disclosure: I drafted every chapter myself, from what I learned building the projects described below. I used Claude Code and One Code to reorder each chapter so it leads with the answer (the Minto pyramid), to polish the English, to generate the diagrams, and to write the code that draws the charts.
Everyone talks about AI agents like they’re a new kind of software: tool calls, memory, planning, RAG, MCP, multi-agent orchestration. Put enough of those words together and it sounds like there is a complicated system underneath that you were supposed to already understand.
It isn’t that complicated. Here is the whole idea:
An LLM API is stateless. Every turn, you send the entire conversation as a JSON array and get text back. A harness is the program that builds, maintains, and protects that array using a simple loop. Everything the field calls “agents” is a set of patches to that one loop, and each patch exists because something concrete broke.
I learned this by building it. In October 2023 I started WSO2 MI Copilot, a coding agent for software integration, in the same family as GitHub Copilot, Cursor and Claude Code. Developers use it to build integrations in Synapse, the XML-based language of WSO2 Micro Integrator. It began as a chat assistant inside the VS Code extension. GitHub Copilot Chat had just come out, and I wanted the same thing for integration developers. The idea was mine, and I led the work until we shipped it at WSO2Con 2024. It ran on GPT-3.5 and GPT-3.5 Turbo, and later GPT-4. There were no agents and no prompt caching. Function calling existed, but hardly anyone used it. We used the plain OpenAI SDK and sent the user’s whole project with every chat message. When I wanted tool calls, I described the tools as XML schemas in the prompt and made the model answer in that format.
That chat assistant is now a full agent. I now build its sibling, WSO2 BI Copilot, which does the same job in the Ballerina programming language. I also built One Code, a from-scratch rebuild of Claude Code on the open-source pi harness. Many of the failures in this book happened to me in one of those three projects.
So every chapter has the same shape: the failure, the minimal patch, and what the patch costs you. A toy harness in plain Python (raw HTTP, no SDK) grows alongside the text. By the epilogue you’ll have a working mini coding agent in about 300 lines, and you’ll know that there’s no magic anywhere in the stack. The full source is on GitHub.
If you learn the patches in the order they appeared, each as a fix for something that broke, none of it is complicated. That is also why the book uses no frameworks: you see each patch in plain code.
Reading order
Part I — The Wire (nothing is magic)
| # | Chapter | The failure it patches |
|---|---|---|
| 1 | It’s Just a JSON Array | “How do I even talk to this thing?” |
| 2 | The Brain: A Next-Token Black Box | “Why does it behave like that?” |
| 3 | Tools: JSON Mapped to Functions | The brain can’t touch the world |
| 4 | The Agent Loop | One tool call isn’t enough |
| 5 | Caching: Why Order Matters | Resending the array gets expensive |
Part II — Running Long (the array under pressure)
| # | Chapter | The failure it patches |
|---|---|---|
| 6 | Context Is a Budget, Not a Bag | The window fills up |
| 7 | Subagents: Fork the Context | One array can’t hold all the work |
| 8 | Steering the Running Loop | The brain drifts mid-task |
| 9 | Background Work and Time | The loop is synchronous; the world isn’t |
Part III — The Ecosystem (naming what you already understand)
| # | Chapter | The failure it patches |
|---|---|---|
| 10 | Every Framework Is a Wrapper Around Chapter 1 | Abstraction anxiety |
| 11 | Extending the Body: MCP, Skills, Deferred Loading, Hooks | Capabilities don’t fit in the array |
| 12 | Debugging the Array | You can’t fix the prompt you can’t see |
Part IV — Trust, Domains, and Data
| # | Chapter | The failure it patches |
|---|---|---|
| 13 | Reflexes and Guardrails | The loop will do something dumb |
| 14 | Case Study: Coding Agents | How specialized does the body need to be? |
| 15 | RAG Was a Harness Pattern All Along | A thousand names for one idea |
Epilogue
| Chapter | ||
|---|---|---|
| E | Build Your Own | The complete toy harness, annotated |
Appendix — Advanced Topics
Standalone pieces. Read them when you need them.
- A. One Harness, Many Brains: model routing, prompt tiers, cost engineering
- B. Worktrees and Isolation: giving parallel agents separate copies of the world
- C. Modes and Plan Mode: harness-enforced operating states (coding-specific)
- D. Retries, Rate Limits, and Streaming: the unglamorous plumbing, plus how streaming works on the wire
The toy harness
The running example lives in
src/harness/
on GitHub. Each version is the previous one plus the chapter’s patch:
harness/v1_chat.py: chapter 1, the 30-line chat loopharness/v2_tools.py: chapter 3, tools bolted onharness/v3_agent.py: chapter 4, the agent loopharness/v4_subagents.py: chapter 7, forked contextsharness/harness.py: the epilogue, the complete ~300-line agent
It uses Python 3.10+ with zero dependencies (raw urllib) and calls the
Anthropic Messages API by default. Swapping the wire format for OpenAI’s is
chapter 1 homework, and the point of the whole series is that it’s only the
wire format you’d swap.
The toy is deliberately small, so a few chapters point to One Code to show how a patch looks at production scale.
Out of scope
This book does not cover training or fine-tuning models, terminal UI implementation, provider billing, or OAuth plumbing. It is about the body, not about growing a brain.
License
The prose is CC BY-NC-ND 4.0; the code is MIT. See License for the terms.