What is an agent harness?

A language model on its own can only read text and write text. It can't open a file, run a test or check a web page. When people talk about an "agent" that fixes bugs or tidies a spreadsheet, most of what makes that possible is the program around the model. That program is called the harness, by analogy with the gear that lets a horse pull a cart: the horse provides the strength, the harness makes it useful and keeps it on the road.

Anthropic, for example, describes its Claude Agent SDK as a general-purpose agent harness, and its engineers report that the design of the harness has a large effect on how well long-running agents perform. Two products using the same model can behave very differently because their harnesses differ.

The four parts of a harness

The loop is the heart of it. The README of OpenAI's Agents SDK describes the same cycle: call the model; if it produced a final answer, stop; if it asked for a tool, run the tool, add the result to the conversation and go around again; and stop anyway after a maximum number of turns.

A minimal harness, step by step

Here is a small harness in Python that shows all four parts. The call_model function stands in for whichever model API you use; it returns either a final answer or a request to use a tool. The rest is real, runnable logic.

import json, subprocess, pathlib

WORKDIR = pathlib.Path("project").resolve()
NOTES = WORKDIR / "PROGRESS.md"           # memory that survives between sessions
MAX_TURNS = 30                             # loop limit
ALLOWED_COMMANDS = {"pytest", "ls"}        # permission: commands it may run

def read_file(path):
    p = (WORKDIR / path).resolve()
    if WORKDIR not in p.parents:           # permission: stay inside the project
        return "Refused: outside the project folder."
    return p.read_text()[:20000]

def run(command):
    if command.split()[0] not in ALLOWED_COMMANDS:
        return f"Refused: '{command}' needs a person's approval."
    out = subprocess.run(command.split(), cwd=WORKDIR,
                         capture_output=True, text=True, timeout=120)
    return (out.stdout + out.stderr)[-5000:]

TOOLS = {"read_file": read_file, "run": run}

def agent(task):
    notes = NOTES.read_text() if NOTES.exists() else "No notes yet."
    messages = [{"role": "user",
                 "content": f"{task}\n\nNotes from earlier sessions:\n{notes}"}]
    for turn in range(MAX_TURNS):
        reply = call_model(messages, tools=list(TOOLS))     # the model decides
        if reply["type"] == "final":
            NOTES.write_text(notes + "\n" + reply["summary"])  # update memory
            return reply["text"]
        result = TOOLS[reply["tool"]](**reply["args"])        # the harness acts
        print(f"turn {turn}: {reply['tool']} {json.dumps(reply['args'])}")  # log
        messages.append({"role": "tool", "content": result})
    return "Stopped: turn limit reached."

Read it from the bottom up. The for loop is the loop, with a hard cap. TOOLS is the list of things the model may ask for. PROGRESS.md is the memory a new session reads first. The checks inside read_file and run are the permissions: the model can ask to run any command, but the harness decides whether it happens. The print line gives you a log of every action.

Where good harnesses earn their keep

The simple version above works for short jobs. Longer ones expose harder problems, and much of the recent engineering effort goes into them.

Memory across sessions. A model can hold only so much text at once, its context window. Anthropic found that agents working across many sessions either tried to do everything at once and ran out of room, or looked at partial work and declared the job finished. Their harness had the first session write a feature list with every item marked failing, a progress log and a first saved version of the project; later sessions read those first and worked on one feature at a time.

Checking the work. Agents asked to grade their own output tend to approve of it. A later Anthropic experiment split the job between a planner, a builder and a separate, deliberately skeptical evaluator, and found that easier to tune than asking one agent to criticize itself.

Context management. A harness can compact a long conversation, summarizing older parts in place, or reset it: start a fresh session with a written handoff. Each has trade-offs in cost and continuity, and choosing between them is a harness decision, not a model one.

Do you need to build your own?

Usually not. If you want an agent to work on code or files, existing harnesses such as Claude Code, Codex and the ChatGPT desktop app already provide the loop, tools, memory features and permission settings, tested across many users. Your effort is better spent on the instructions, the project notes and the permission choices you give them.

If you are building an agent into your own product, start from a framework instead of a blank file. The OpenAI Agents SDK and the Claude Agent SDK each run the loop and the tool calls for you, and leave you to define tools and rules.

Writing a small harness yourself is still worth doing once, the way it is worth changing a tire once even if you usually call for help. You learn exactly where the model's judgment ends and your code's responsibility begins, and that makes every ready-made agent easier to set up safely.