What an agent harness is

Engine and car

Think of the model as an engine. It's the source of power, but an engine on a workbench goes nowhere. The harness is the rest of the car: wheels, brakes, fuel system, dashboard. A great engine in a bad car is a bad car.

A model call does exactly one thing: it reads a request (system prompt, messages, tool definitions) and returns a response (text, maybe tool_use blocks, and a stop_reason). Everything else is the harness:

In plain words: the model only ever writes a reply. The harness is everything that acts on that reply.

You built the smallest possible harness in Phase 1's agent loop lesson, and a host in Phase 9. This phase builds the full set.

def model(messages):
    if len(messages) == 1:
        return {"stop_reason": "tool_use", "tool": "read_file", "input": "notes.txt"}
    return {"stop_reason": "end_turn", "text": "The notes say: ship on Friday."}

FILES = {"notes.txt": "ship on Friday"}

# No harness: one call, and the request goes nowhere.
print("alone:", model(["What do my notes say?"]))

# A harness runs the tool and goes round again.
messages = ["What do my notes say?"]
while True:
    reply = model(messages)
    if reply["stop_reason"] == "end_turn":
        break
    messages.append(FILES[reply["input"]])
print("with a harness:", reply["text"])

Three meanings of "harness"

A horse's harness and a climber's harness are both gear around something, keeping it under control. The word turns up in software in three related senses:

• A test harness runs code under controlled conditions and checks the results. This academy has one: harness.py runs your exercises and their checks.
• An evaluation harness runs a model or agent across a benchmark of tasks and scores it, such as EleutherAI's lm-evaluation-harness. The eval harness lesson builds one for agents.
• An agent harness is the subject of this phase: the runtime that turns a model into an agent.

They share an idea: a harness is the controlled environment around the thing being run.

Build it, or use one

You can cook dinner from scratch, use a meal kit, heat up a ready meal or go to a restaurant. There are four common ways to get an agent running on Claude, depending on who writes the loop and who runs the machines:

The tool runner and the Agent SDK are easy to mix up. The tool runner is a thin helper in the normal API SDK that loops over your tools. The Agent SDK is a separate package with a full, opinionated harness and built-in tools.

So why build one yourself? Because every one of these is made of the parts in this phase. To configure them well, debug them when they misbehave, add what's missing, or build a harness for a domain no product covers, you need to know what's inside.

A design rule: inject the model

Pilots train in flight simulators, because they can practice an engine failure there at no risk or cost. Make the model a parameter of the harness: a function that takes messages and tools and returns a response. Production passes a function that calls the API. Tests pass a scripted model that returns prepared responses in order. Then every part of the harness can be tested quickly, cheaply and deterministically, which is how the rest of this phase works.

def run(model, tools):
    messages = [{"role": "user", "content": "go"}]
    while True:
        reply = model(messages)
        if reply["stop_reason"] == "end_turn":
            return messages
        try:
            result = {"content": tools[reply["tool"]](reply["input"])}
        except FileNotFoundError as err:
            result = {"content": str(err), "is_error": True}
        messages.append({"role": "user", "content": result})

script = iter([{"stop_reason": "tool_use", "tool": "read", "input": "missing.txt"},
               {"stop_reason": "end_turn"}])
def scripted(messages):
    return next(script)

def read(path):
    raise FileNotFoundError(f"No file {path}")

last = run(scripted, {"read": read})[-1]["content"]
print(last)
assert last["is_error"] is True
print("test passed, with no API call")

def fake_model(prompt):
    return "done"
def agent(model):
    return model("go")
print(agent(fake_model))

def scripted(replies):
    replies = list(replies)
    def model(messages, tools):
        return replies.pop(0)
    return model

def run(task, model, tools):
    messages = [{"role": "user", "content": task}]
    events = []
    while True:
        reply = model(messages, list(tools))
        messages.append({"role": "assistant", "content": reply["content"]})
        events.append(("model", reply["stop_reason"]))
        if reply["stop_reason"] != "tool_use":
            return "".join(b["text"] for b in reply["content"] if b["type"] == "text"), events
        results = []
        for block in reply["content"]:
            if block["type"] == "tool_use":
                output = tools[block["name"]](**block["input"])
                events.append(("tool", block["name"]))
                results.append({"type": "tool_result", "tool_use_id": block["id"], "content": str(output)})
        messages.append({"role": "user", "content": results})

model = scripted([
    {"stop_reason": "tool_use", "content": [{"type": "tool_use", "id": "t1", "name": "add", "input": {"a": 2, "b": 3}}]},
    {"stop_reason": "end_turn", "content": [{"type": "text", "text": "2 + 3 = 5"}]},
])
print(run("What is 2 + 3?", model, {"add": lambda a, b: a + b}))

More than a loop

The same engine feels very different in a truck and a race car. An agent's quality isn't only the model. The same model behaves very differently depending on its tools, its context and its checks. And a harness is more than its while loop, which is the easy part.

Test without a model

Most harness bugs can be found with no API call at all.