How to Scaffold an AI Agent Harness Without Wasting Tokens
A cost-first guide to building an AI agent harness: loop, context, tools, verification, and guardrails, and the token cost each layer controls.
By Capital & Compute
Give two teams the same model and the same task: make a data table component sortable, keyboard-accessible, and covered by a passing test. One team’s agent finishes in four turns and a few cents. The other’s thrashes for twenty turns, re-reads the same files six times, and rings up a bill an order of magnitude larger before a human gives up and finishes by hand. Same model. The difference is everything wrapped around it.
That wrapper has a name now. The industry calls it the agent harness, and in 2026 it is where the real engineering happens. You cannot change the weights of the model you are renting. You can change every byte of context it sees, every tool it can call, and every check that runs before its work reaches a human. That is the part you control, and it is the part that decides both your token bill and whether the task actually gets done.
What is an AI agent harness?
An agent harness is the runtime around a language model that turns a single prompt-and-response into an agent that can do work: the loop that lets it act and observe, the context it reads, the tools it can call, the checks that grade its output, and the limits on what it is allowed to touch. The model supplies raw capability. The harness decides whether that capability lands.
Anthropic’s engineering team made the underlying point in its 2025 post Effective context engineering for AI agents, framing the job as finding “the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome.” The practitioner Addy Osmani put the same idea more bluntly in his 2026 essay Agent Harness Engineering: “a decent model with a great harness beats a great model with a bad harness.” Both are saying the leverage moved. It used to sit in the prompt. Then it sat in the context. Now it sits in the whole runtime.
Why the harness, not the model, sets your bill
Here is the mechanic that most pricing-page comparisons miss. An agent does not answer once. It runs a loop: read the task, take an action, observe the result, fold that result back into the context, and go again. Every turn re-sends the growing context to the model. By turn ten, you are paying to send turn one’s content for the tenth time.
That shape is why the per-token sticker price tells you so little. A 2026 Microsoft Research preprint, The Price Reversal Phenomenon: When Cheaper Reasoning Models End Up Costing More (Chen et al.), found that across eight frontier models the cheaper-per-token option cost more to finish the same job in 32% of head-to-head matchups, because it burned more tokens getting there. We pulled that study apart in our breakdown of why cheaper AI often costs more. The harness controls the two variables that decide which side of that reversal you land on: how many loops the agent runs, and how much context each loop carries.
Anthropic’s own Claude Code cost guidance puts the average developer between $150 and $250 a month, and a single misconfigured loop can move that number hard. We traced where a real bill actually goes in our look at Claude Code token-saving tools: cache writes and model output dominated, and both are downstream of harness decisions, not model choice.
The capability side of the ledger moves just as much. Osmani recounts one team whose agent jumped from outside the top 30 to the top 5 on a public coding benchmark by changing only the harness around a fixed model. Reorder that: the scaffold was worth more than a generation of model progress. We made the same argument with the benchmark data in why agent benchmark scores are really model-plus-harness scores.
The scaffold was worth more than a generation of model progress.
So the harness is not plumbing you bolt on at the end. It is the cost model and the capability model at the same time. Build it that way.
How to build an agent harness, layer by layer
Five layers, in the order they pay off. Start with the loop, end with the guardrails:
- Cap the loop. The read-act-observe cycle is the engine, so set a turn limit and break out of repeats before a stuck agent re-sends its context again.
- Budget the context. Send the smallest high-signal slice the task needs, not the whole repo, because every token is re-sent on every later turn.
- Trim the tool surface. Give the agent a few sharp tools, not fifty overlapping ones it will pick between wrongly.
- Add verification loops. Wire linters, type checks, and tests to feed failures back so the agent self-corrects before a human reviews.
- Set guardrails and observability. Limit what the agent can touch without asking, and log what each task spent.
Each layer is a knob on both axes: tokens burned and tasks finished. Walk them in order.
| Layer | What it controls |
|---|---|
| Loop | Sets the bill: tokens scale with turn count |
| Context and memory | Sets the bill: every token is re-sent each turn |
| Tool surface | Fewer, sharper tools beat many overlapping ones |
| Verification loops | Cheapest tokens: self-correct before a human reviews |
| Guardrails and observability | The reliability tax, and where you see the spend |
| The model | Rented by the token. You cannot change the weights. |
Layer 1: The loop
The loop is the engine, and loop count is the single biggest line item on your bill. A frontend example makes it concrete. You ask the agent to make a <DataTable> sortable. A thin harness lets it edit, run the type checker, read the error, edit again, and repeat with no ceiling. If the model misreads a generic type, it can spin for fifteen turns, each one re-sending a context that grows every pass.
The fix is not a smarter prompt. It is a budget. Set a hard turn cap, and watch for the agent repeating a near-identical action so you can break out instead of paying for the same mistake five more times. Cursor’s hooks run before and after each stage of its agent loop and can observe, block, or modify it, which is one documented way to catch a repeat and stop it.
Layer 2: Context and memory
Every token in the context window is a token you pay for on every subsequent turn. So the question is never “what could the model use?” It is “what is the smallest slice that gets this done?”
Take a React monorepo with 400 components. A naive harness, asked to fix a styling bug, pastes whole files into the prompt and hopes. A good one sends a file tree, lets the agent grep for the three components that actually matter, and reads only those. Anthropic’s context-engineering guidance frames this as the core discipline: high signal, low volume.
Memory is the same idea across turns. Durable state belongs on the filesystem and in git, not in the context window. The agent writes notes, plans, and intermediate output to files, then reads back only what the current step needs. Osmani calls this offloading, and pairs it with compaction: summarize the old turns rather than re-sending them verbatim. The economic payoff is direct. Context that lives on disk is read once when needed instead of re-sent every loop.
Layer 3: The tool surface
A tool is how the agent acts on the world: read a file, run a command, query a database. The instinct is to give the agent everything. Resist it. Every tool definition sits in the context, and a sprawling tool surface both inflates the bill and confuses the model about which tool to reach for.
Osmani’s rule of thumb from production: ten focused tools beat fifty overlapping ones. For a frontend agent that usually means a tight set: read a file, edit a file, run the dev server, run the test suite, and grep the codebase. Add a run_playwright or an accessibility check as a dedicated tool because those produce the structured feedback the next layer runs on. Skip the twenty niche tools the agent will pick wrong half the time.
This is also where the Model Context Protocol fits: a standard way to expose tools to an agent. Useful, but the discipline holds. Expose the few tools the task needs, not every endpoint you happen to have.
Layer 4: Verification loops
This is the layer with the best return on investment in the entire harness, and the one thin scaffolds skip.
A verification loop is an automated check the agent runs on its own work, with the result fed back as structured input. For a frontend task that is your type checker, your linter, your test runner, and an accessibility check. The agent makes the table sortable, runs the Playwright test, gets a failure that says exactly which assertion broke, and fixes it, all before a human ever looks.
The economics are lopsided in your favor. A failing test costs a few hundred tokens to surface and feed back. The human review it replaces costs a context switch, a round-trip, and minutes of expensive attention. Augment Code, in its 2026 guide Harness Engineering for AI Coding Agents, frames verification as the layer that lets an agent self-correct before its work reaches a person, and argues it is what separates a demo from something you ship.
A grounding note on how much this matters: independent leaderboard analyses report that the same model can move double digits on SWE-bench Verified depending on the scaffold around it, and verification is a large part of that gap. Treat those figures as analyses of public leaderboards rather than controlled experiments, but the direction is not in dispute.
Layer 5: Guardrails and observability
The last layer is the reliability tax, and it is worth paying. Guardrails decide what the agent may touch without asking: which files it can write, which commands it can run, whether it can push to git or delete anything. A permission model and a sandbox keep a confused agent from doing real damage to a real repo. Claude Code’s permission system and hooks, and Cursor’s rules files, are two production takes on this; both tools are covered in the agent landscape piece.
Observability is the other half: a trace of what the agent did and what it spent. You cannot manage a token bill you cannot see. Log tokens per task, loops per task, and failure rate per task, and the expensive patterns surface fast. Martin Fowler’s 2026 article Harness engineering for coding agent users makes the case that measuring agent behavior is what turns harness building from guesswork into engineering.
Build every rule to be deleted
One principle ties the layers together, and it is the one most likely to save you money over a year: build to delete.
Every hand-coded rule in your harness exists because the model got something wrong. The agent forgot to run the linter, so you added a rule that forces it. The agent imported the wrong module, so you wrote a constraint. Osmani calls this the ratchet: every line in a good rules file should trace back to a specific failure you watched happen. He notes that disciplined teams keep their rules file short on purpose, closer to a pilot’s checklist than a style guide.
The trap is that the next model is smarter, and half your rules are now scar tissue for failures that no longer occur. They still cost tokens on every turn, and they still constrain a model that has outgrown them. So write each rule to be ripped out. Date it, tie it to the failure that created it, and delete it the moment the model stops needing it. The harness that wins over time is the one you can shrink.
For where this fits in the wider picture of what agents cost to run, see our hub on AI coding agents and the coding-plan pricing rundown.
Frequently asked questions
Frequently asked questions
- What is the difference between an agent harness and scaffolding?
- Scaffolding is the initial setup: the templates, system prompt, and tool definitions that initialize an agent before it runs. The harness is the full runtime that operates continuously while the agent works: the loop, context management, verification, and guardrails. Scaffolding is where you start; the harness is what runs.
- Does a better model remove the need for a harness?
- No. A better model changes which failures you have to engineer around, but it does not remove the loop, the context budget, the tools, or the need to verify output before it ships. Stronger models tend to make the harness smaller, not unnecessary.
- Which harness layer should I build first?
- The loop, then verification. Capping loop count stops runaway bills immediately, and automated verification gives you the largest capability gain per token by letting the agent self-correct before a human reviews its work.
- Why does my agent cost so much more than the per-token price implies?
- Because an agent re-sends its growing context every turn. Loop count and context size, both harness decisions, multiply the raw token price. A model with a low sticker price can finish a job more expensively than a pricier one if its harness lets it loop more or carry more context.
Sources
Anthropic (2025). Effective context engineering for AI agents. Anthropic Engineering (vendor engineering post). https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
Anthropic. Manage costs effectively. Claude Code documentation (vendor docs). https://code.claude.com/docs/en/costs
Cursor. Hooks. Cursor documentation (vendor docs). https://cursor.com/docs/hooks
Osmani, A. (2026). Agent Harness Engineering. Practitioner essay. https://addyosmani.com/blog/agent-harness-engineering/
Augment Code (2026). Harness Engineering for AI Coding Agents. Practitioner guide. https://www.augmentcode.com/guides/harness-engineering-ai-coding-agents
Fowler, M. (2026). Harness engineering for coding agent users. martinfowler.com (practitioner article). https://martinfowler.com/articles/harness-engineering.html
Chen, L., Zhang, C., He, Y., Stoica, I., Zaharia, M., & Zou, J. (2026). The Price Reversal Phenomenon: When Cheaper Reasoning Models End Up Costing More. arXiv preprint (not peer-reviewed). https://arxiv.org/abs/2603.23971