Agent harness: what it is and what it consists of
The agent harness is everything that surrounds the language model in an AI agent and turns it into a working tool: instructions, tools, the execution environment, state between sessions and feedback loops. Agent = Model + Harness: the model reasons, while the harness gives it rules, hands, memory and a check of the result.
Definition
An agent harness is the software wrapper around a language model: everything that is not the model itself but affects how the agent works. The formula is Agent = Model + Harness. The model can reason and write code, while the harness decides what it sees, what actions it can take, where commands run, what is kept between sessions and how the agent learns about its mistakes.
Five parts of the harness
- Instructions — the system prompt and project files such as
CLAUDE.mdandAGENTS.md, topic documents and skills. - Tools — running shell commands, editing files, a browser, connections through MCP.
- Environment — a sandbox or container where the agent runs code without risk to production.
- State — plan and progress files, git history: memory that survives closing a session.
- Feedback — tests, linters, type checking, hooks that return an error signal to the agent.
The harness is not a single prompt file. A long AGENTS.md will not help if the agent has no access to the tests or the environment does not start. Reliability is defined by the weakest of the five parts.
Example
For the third session in a row the agent is fixing the same bug: after every restart it does not remember what it already tried. It looks as if the model is to blame. In fact the state subsystem is broken. The solution is a PROGRESS.md file, where the agent records at the end of each session the hypotheses that did not work and the next step:
## Bug: double charge on request retry
Checked and rejected:
- HTTP client timeout — no effect
- race in the webhook handler — could not reproduce
Next step: check the idempotency key in payments/service.pyA new session reads the file and immediately continues from the right place. The model has not changed — the harness has.
Summary
The agent harness is the instructions, tools, environment, state and feedback around the model. It is what determines whether the same agent works reliably or breaks. How to build each part is covered in practice in the harness engineering course.
FAQ
How is an agent harness different from an agent framework?
A framework is a library you build an agent with. A harness is a concrete setup around the model for your project: rules, access, environment, tests and state files. A ready-made agent such as Claude Code already includes a basic harness that you extend.
Are "harness" and "prompt" the same thing?
No. A prompt is only a part of the instructions subsystem. The harness also includes tools, the environment, memory between sessions and verification of the result.
Which part of the harness should I start with?
With feedback: give the agent commands it can use to check its own work. This is the fastest way to reduce the number of mistakes that reach a human.
This topic is covered in depth with practice in the course “Harness Engineering: Engineering Reliability for AI Agents”.
Go to course