Skip to main content
Zubnet AI › Learn › Wiki › Agent Harness
Using AI

Agent Harness

Also known as: Scaffolding, Agent Scaffold
The software wrapped around a model that turns it into an agent, including the loop, tools, context management, permissions and memory.

Why it matters

The same model can perform very differently depending on its harness. On coding benchmarks such as SWE-bench Verified and Terminal-Bench, changing only the harness can move scores by many points, which is why leaderboards list the model and the agent system together. When an agent product feels smarter than a raw API call to the same model, the harness is the reason.

For builders, the harness is where most of the engineering goes. You usually can't change the model, but you can change what it sees, which tools it has and what happens when something goes wrong.

Deep Dive

A language model on its own only maps text to text. It can't read a file, run a command or remember what it did an hour ago. The harness is the program around the model that makes those things possible. It sends the model a prompt, runs the tool calls the model asks for, feeds the results back and repeats until the task is done.

A useful shorthand: agent = model + harness. Claude Code, OpenAI's Codex CLI, Cursor's agent mode and open-source projects like OpenHands and SWE-agent are all harnesses. So are the frameworks people use to build their own, such as the Claude Agent SDK, the OpenAI Agents SDK and LangGraph. Researchers often call the same thing scaffolding.

What a Harness Does

  • The loop: call the model, execute tool calls, return results, repeat, and decide when to stop.
  • Tools: define them, validate arguments, run them and format results so they're short and useful. The SWE-agent paper called this the agent-computer interface and showed that tool design matters as much as prompts.
  • Context management: build the system prompt, load project instructions, summarize old history (compaction) when the context window fills up, and keep the prompt cache intact.
  • Permissions and sandboxing: decide which actions run automatically, which need human approval and what the agent can touch at all.
  • Memory and state: notes, to-do lists and files that survive beyond one context window, plus checkpoints for undo.
  • Orchestration: spawning subagents, running tools in parallel, retrying after errors and enforcing budgets on steps and tokens.

A Minimal Harness

The core loop is small:

messages = [{"role": "user", "content": task}]
while True:
    reply = model(messages, tools=tools)
    messages.append(reply)
    if not reply.tool_calls:
        break
    for call in reply.tool_calls:
        messages.append(run_tool(call))

Everything else in a production harness exists to handle what this loop ignores: long tasks, failures, safety and cost.

Thinner Over Time

Early agent systems needed heavy scaffolding: rigid plans, output parsers, hand-built retrieval and many specialized prompts. As models improved at tool use and planning, much of that became unnecessary or even harmful, because it stopped the model from using its own judgment. This is the Bitter Lesson applied to agents. Many of the strongest current harnesses are deliberately simple: a good loop, a few general tools such as a shell and a file editor, and careful context management.

A practical habit follows from this: when a new model comes out, try removing parts of your harness and see if results improve.

Harness and Evaluation

Because the harness changes results, benchmark numbers are only comparable when the harness is the same. For safety evaluations, a weak harness is a real risk, because it can make a model look less capable than it is. Evaluators therefore put effort into elicitation: giving the model good tools and enough budget to show what it can actually do.

Choosing or Building One

Start with an existing harness or SDK unless you have unusual needs. Invest first in tools with clear descriptions and compact outputs, then in context management, then in permissions. Log every step of the loop. When something fails, read the transcript: most agent failures come from what the model was shown, not from the model's ability.

← All Terms
ESC