What is an AI agent harness?

What an agent harness is

Anthropic's agent guide (December 2024) separates workflows, where models and tools follow predefined code paths, from agents, where the model directs its own process and tool use. An agent is a loop: the model picks an action, a tool runs, the result goes back into the context, and the model picks again. The harness is the code and setup that runs that loop, and it holds most of the decisions that matter: which tools exist, how they are described, what goes into the context, and when the loop ends.

In Effective harnesses for long-running agents (26 November 2025), Justin Young describes building a harness for agents that work across many sessions, each starting with an empty context. Two failures kept appearing. The agent tried to one-shot the whole job, ran out of context mid-way, and left the work broken and undocumented. Or a later session saw that some features existed and declared the job complete. The fix was in the harness: a first session sets up the environment, a feature list and a progress file; each later session reads the progress file, works on one feature, tests it, commits it, and updates the notes. The agents were told it was unacceptable to remove or edit tests.

Why a non-engineer team should care

• You already use harnesses. Claude Code, Codex, Cursor's agent and ChatGPT's agent mode are all harnesses around a model. Their settings are your harness choices.
• Automations need one written down. An agent that updates your CRM or your store at night needs a done list, limits and stop rules that a person can check.
• Failures are predictable. Drift, loops and false "done" have known causes. Writing the harness first prevents most of them.

A worked example

Illustration: a made-up business. Tidewater Tea, a six-person online shop, asks an agent to rewrite the descriptions of its 80 products in the new brand voice. The first run, with one instruction and full store access, edits 23 products, changes three prices by accident, and reports "all done".

The second run has a harness. A done list names the 80 products, one line each, which the agent may mark done or failed but not rewrite. The store tool is limited to the description field. A progress note records what was finished and what is next, and every session starts by reading it. The agent rewrites one product, reloads the page to check it, records it, then moves on. It stops after three failures on the same product, and publishing waits for the owner. The pilot of five products takes ten minutes to review, and the full run finishes with every product accounted for.

How to write a harness for your agent

1. Write the goal and a pass/fail done list the agent can update but not edit.
2. List the tools with a limit each (which field, which folder, how many per run) and remove the ones the goal doesn't need.
3. Name the memory files: the done list, a progress note, and where work is saved.
4. Set the loop and stop rules: one item per step; stop on success, on three failures, on a crossed limit, or at a time or cost cap.
5. Mark the human gates for sending, deleting, paying and publishing, and run a pilot of a few items first.

Common confusions

• "A better model fixes it." The failures above happened with a frontier model. The harness changed the outcome.
• "More tools make a more capable agent." Anthropic's guidance on tools and context is to keep them few, clear and distinct.
• "Done means the agent said so." Done means the list passes. Measure it with evals.

Questions

What is a harness in AI?

The software and setup around a model that let it act as an agent: the starting instructions, the tools it can call, the files it reads and writes to remember progress, the loop that runs it step by step, and the rules for stopping and asking a person. Anthropic calls its Claude Agent SDK a general-purpose agent harness.

Why do long-running agents fail?

Anthropic's November 2025 write-up names two patterns: the agent tries to do everything at once and runs out of context partway, leaving work half done, or a later session sees some progress and declares the job finished. Its fixes were a feature list, a progress file and one item per session.

Is a harness the same as a framework?

A framework is code you build an agent with. The harness is the running setup around a particular agent, whether it comes from a framework, an SDK, a product like Claude Code or Codex, or a spec you write for an automation.