What is an agent harness? The part of an AI agent that isn't the model
An agent harness is the software around a language model that gives it tools, context, permissions and a loop. Here is what goes into one, and why it decides whether an agent works in production.
George Jucan, Founder, Poligon Tech 5 min
Short answer
An agent harness is everything around the model: the loop that calls it, the tools it can use, the context it is given, the permissions that limit it, and the logs that record what it did. The model decides what to do next; the harness decides what it is allowed to do, what it can see, and when it stops. Two teams using the same model get very different results because their harnesses are different.
People talk about AI agents as if the model is the agent. It isn’t. The model is one component. The rest, the part that turns “a model that writes text” into “a system that does work”, is the harness.
If you have ever wondered why the same model is brilliant in one product and useless in another, the harness is usually the answer.
The short definition
An agent harness is the code that runs around a language model and lets it act. It has five jobs:
- Run the loop. Send the model a task, read its reply, execute any tool call it asks for, feed the result back, and repeat until the task is done or a limit is hit.
- Provide tools. Define what the model can do: read a file, query a database, call an API, send a draft for approval.
- Assemble context. Decide what the model sees on each turn: instructions, relevant documents, previous results, the state of the task.
- Enforce boundaries. Limit what the model may do without asking, and stop it when it should stop.
- Record everything. Keep a trace of every model call and tool call so a person can see what happened and why.
The model only ever produces the next message. Every one of those five jobs belongs to the harness.
Why the harness matters more than people expect
Model releases get the headlines, but most failures we see in agent projects are harness failures:
- The agent had the wrong context. It was asked to resolve an order exception but never saw the customer’s contract price.
- The agent had the wrong tools. It could read the ERP but had no way to say “I’m not sure, send this to a person”.
- The agent had no boundaries. It could write to production data on its first day.
- Nobody could tell what it did. When a result was wrong, there was no trace to debug.
A better model makes none of these go away. A better harness fixes all of them.
What goes into a harness
The loop
The simplest loop is: call the model, run the tool it asked for, append the result, call the model again. Real harnesses add a few things on top:
- Step and cost limits, so a confused agent stops instead of looping forever.
- Stop conditions that are explicit: “the order is entered”, “the case is escalated”, “three tool errors in a row”.
- Retries for tool errors, but not for judgement errors. A timeout is worth retrying. A wrong answer is not.
Tools
Tools are the agent’s hands. Good tools are narrow and named after the business action, not the underlying system:
| Weak tool | Better tool |
|---|---|
run_sql(query) | get_open_orders(customer_id) |
http_request(url, body) | create_draft_order(lines) |
send_email(to, body) | request_approval(case_id, summary) |
Narrow tools are easier for the model to use correctly, easier to permission, and easier to audit. Today, the most common way to expose tools to a harness is the Model Context Protocol (MCP), which lets one tool server work with many different agents.
Context
Context is what the model sees on each turn. Getting it right is most of the work, which is why the practice now has its own name, context engineering. A harness typically assembles:
- Standing instructions: who the agent is working for, what good looks like, what it must never do.
- Task data: the email, the order, the delivery note.
- Retrieved facts: the contract price, the stock level, the last three orders from this customer.
- Working memory: what the agent has already tried in this task.
More context is not better. Irrelevant context makes the model slower, more expensive and more likely to latch onto the wrong detail. A good harness gives the model what this step needs, and nothing more.
Boundaries
This is the part most demos skip and every production system needs:
- Least-privilege access. The agent’s credentials can do only what its tools need. A read-only database user for lookups. A separate, narrow write path for drafts.
- Approval gates. Some actions run automatically; some create a draft that a person approves. We wrote a separate guide on designing human-in-the-loop approvals.
- Hard rules in code, not in the prompt. “Never change a price by more than 5%” belongs in the tool’s validation, where the model cannot talk its way around it.
Logging and evaluation
Every model call, tool call, input and output should be stored with the case it belongs to. That trace is how you debug, how you answer an auditor, and how you build an evaluation set: a list of real past cases with known correct outcomes that you rerun every time you change a prompt, tool or model.
Harnesses you can use today
You do not have to build every harness from scratch.
- General-purpose harnesses like Claude Code and OpenAI’s Codex already handle the loop, file and shell tools, permissions and context loading for software and knowledge work. You extend them rather than rebuild them. See Claude Code skills, hooks and subagents for how that extension works in practice.
- Agent SDKs and frameworks (the Claude Agent SDK, the OpenAI Agents SDK, LangGraph and others) give you the loop and tool plumbing, so you can build a narrow harness for one business process.
- Self-hosted personal agents like Hermes Agent and OpenClaw run all the time on your own server and talk to you through chat apps, and control surfaces like T3 Code let you run several coding agents from one app. We compare them all in AI agent harnesses compared.
- Custom harnesses make sense when the process has strict approval steps, unusual systems, or audit requirements a general tool does not cover.
How we think about it at Poligon
When we build an agent for an operations team, the model is the part we spend the least time on. Most of the work is the harness: which tools the agent gets, which systems they touch and with what permissions, what a person approves, and how every step is logged. That is also why our agents run over a client’s existing ERP, email and spreadsheets instead of replacing them. The harness adapts to the systems; the systems do not have to adapt to the agent.
If you are evaluating an agent product or vendor, ask about the harness, not the model. Ask what the agent can touch, what it needs approval for, what happens when it is unsure, and how you would see what it did last Tuesday at 3pm. The answers will tell you far more than the model name.
Frequently asked questions
Is an agent harness the same as an agent framework?
Not quite. A framework (LangGraph, the OpenAI Agents SDK, the Claude Agent SDK and others) is a library you build a harness with. The harness is the finished thing: the specific loop, tools, prompts, permissions and logging for one agent doing one job.
Is Claude Code an agent harness?
Yes. Claude Code is a general-purpose harness for software work: it runs the model in a loop, gives it file, shell and search tools, loads project context from CLAUDE.md, enforces permission modes and lets you extend it with skills, hooks, subagents and MCP servers.
Do I need to build my own harness?
For coding and general knowledge work, usually not; an existing harness like Claude Code or Codex is a better starting point. For an agent that runs inside a business process, such as order entry or invoice checks, you usually need a narrow harness of your own, because the tools, permissions and approval steps are specific to that process.