Agent Mentor Learn
Agent Harness Fundamentals: Loops and Control · Lesson 1 of 6

Lesson 1: What a Harness Is: The Control Code Around the Model

Learning goals:

  • Draw the line between the harness and the model, and say which side "proposing an action" falls on and which side "executing and controlling" falls on
  • Use the difference between agents and workflows to explain what earns a system the name "agent"
  • Decide whether an "our agent isn't reliable enough" problem should be fixed at the model layer or at the harness layer

Prerequisites: You've finished the first six courses in this series and understand a single tool-call round-trip (stop_reason: "tool_use" / tool_result) | Next: Lesson 2 >>

You Already Saw a Harness in That One Round-Trip

In "Agent Tool Calling: Getting Agents to Actually Do Things" you took apart a complete tool-call round-trip: the model sees your question plus a manifest of tools, and comes back with stop_reason: "tool_use" and a tool_use block that says "call this tool, with these parameters." The docs are blunt about what happens next: "The model never executes anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation."1 Opening the file, running the command, making the network call — all of that is the host code running the agent. When the host finishes, it wraps the output in a tool_result, appends it to the conversation, and fires off another request.

That chunk of host code — the part that runs tools and then decides what to do next — is the subject of this lesson. It has a name: the harness, the layer of control code wrapped around the model.

That earlier course stopped after one round-trip, though. Real agents rarely go back and forth only once. A tool call returns, the model looks at the result, and usually it wants to call another tool, and another, going around and around. Who runs that going-around-and-around? Who decides when it's time to stop? Who pulls it back when it drifts? All of that is the harness's job. This lesson draws the line between harness and model; the lessons after it pull the harness apart, one piece at a time.

What an Agent Is: an LLM Using Tools in a Loop

Anthropic's engineering team has a plain definition of agents: "They are typically just LLMs using tools based on environmental feedback in a loop."2 Three words in that sentence carry the weight — tools, environmental feedback, and loop. The model calls a tool (tools), the host runs it and feeds the result back (environmental feedback), the model reads the result and decides what to do next, possibly calling another tool, and around it goes (loop). The round-trip you learned earlier was the first turn of exactly this loop.

That same article separates two kinds of systems people constantly conflate. The first is the workflow: "Workflows are systems where LLMs and tools are orchestrated through predefined code paths."2 Do this, then that, and at this branch go left — a person settled all of it in advance. The second is the agent: "Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage"2.

Put those two definitions side by side and the difference isn't about how strong the model is. It's about who makes the control-flow decisions. In a workflow, the next step is hard-coded. In an agent, the next step is whatever the model decides in the moment, inside the loop. That's what earns the name, in the roadmap's phrasing: "An agent makes its own control-flow decisions inside a loop."3 And the thing that carries that loop, that turns the model's decisions into actual effects, is the harness.

One bit of phrasing deserves care here. Saying "the model decides the next step" means the model proposes an action on each turn. Whether the loop turns at all, whether the model gets asked again — that's still up to the harness code. The model proposes, the harness rules. That line is the foundation for everything that follows.

Same Model, Different Harness, Wildly Different Results

Now for the one sentence this lesson most wants you to keep. A community roadmap puts it flatly: "Same model, different harness, completely different result."3

That sounds backwards at first. We're used to charging an agent's reliability to the model's account — this one's strong, that one's weak. But think about what the model actually did in that round-trip: it looked at the current conversation and proposed the next action. Whether that action really runs, whether the loop keeps going afterward, whether to call a halt after twenty fruitless turns, whether to check with a person first when the proposed action would drop a database table — not one of those is the model's call. Every one of them belongs to the harness.

Here's a concrete comparison. Same model, same set of tools, same task: clean up the unused dependencies in a project.

  • Harness A executes every action the model proposes, unconditionally. No turn limit, no check for whether the agent is spinning in place. The model misjudges on some turn and proposes a wrong deletion; the harness deletes. The model then reasons forward from a state it has already broken, and one wrong step turns into ten. The trouble with systems like this comes straight from agent autonomy: "The autonomous nature of agents means higher costs, and the potential for compounding errors."2
  • Harness B runs the same model and takes the same proposals, but this control layer caps the number of turns, watches for several turns in a row with no real progress, and stops to ask a person before executing a high-impact action like a deletion. The same bad proposal hits an approval gate here instead of hitting the disk.

Identical model. Possibly identical proposals both times. One run wrecks the project, the other stays on the rails. The whole difference comes from the control code on the outside. So when your agent is unreliable, don't reach for a stronger model first — a lot of the time the problem lives in the harness layer, not the model layer.

A Harness Isn't One Thing, It's a Set of Parts

At this point you might picture the harness as "that loop" — not quite. The loop is its central piece, but a harness is a set of components working together. The roadmap describes it as a union: "the harness is the union of:" loop control, tool dispatch, context management, and more.3 Get to know their faces now; later lessons take one apart each:

  • Loop control, described in the roadmap as "loop control. The while-loop driving model→tools→model."3 It reads the stop_reason the model returns and decides whether this turn is followed by another one or by a stop. This is the heart of the harness, and Lesson 2 is devoted to it.
  • Tool dispatch: once the model proposes "call this tool with these parameters," the code that routes the request to the real function, runs it, and packs the output back into a tool_result. You met the single-step version of this earlier; what a harness does is wire it into the loop and use it over and over.
  • Context management: every turn of the loop piles more data into the conversation, because "An agent running in a loop generates more and more data that could be relevant for the next turn of inference"4. And the model's attention isn't free: "LLMs have an "attention budget" that they draw on when parsing large volumes of context"4, and "Every new token introduced depletes this budget by some amount"4. So the harness has to decide where that history goes and how much of it stays, instead of letting it balloon.

Two more pieces get full treatment later in this course. They're named here so you know they belong to the harness too:

  • Stopping conditions: beyond following stop_reason, "it's also common to include stopping conditions (such as a maximum number of iterations) to maintain control."2 When to call it quits is Lesson 3's subject.
  • Runaway backstops and human intervention: the loop may run for a long stretch, and "The LLM will potentially operate for many turns, and you must have some level of trust in its decision-making."2 Trust isn't the same as a free hand, though — "Agents can then pause for human feedback at checkpoints or when encountering blockers."2 How to catch infinite loops, spinning, and blown budgets (Lesson 4), and how a person interrupts and redirects mid-run (Lesson 5), both live at this layer.

You don't have to memorize the details of each part right now. Just hold the overall shape: a harness is the collective name for the control code around the model, assembled from several parts that together determine how steadily this agent runs. That also explains why swapping harnesses changes the outcome so much — what you swapped isn't one line of code, it's an entire strategy for controlling the loop.

When You Actually Need This Control Layer

Seeing how much a harness can manage, it's easy to slide to the opposite extreme: does every use of a model need a full setup with loop control, approval gates, and spin detection? No.

Go back to the agent-versus-workflow line. If your task follows a fixed path — a ticket comes in, gets classified, gets routed by category — and every branch can be settled in advance, that's a workflow, and orchestrating it "through predefined code paths"2 is enough. There's no reason to let a model make control-flow decisions inside a loop. Strapping an autonomous loop onto it only adds chances for it to go off course.

What genuinely needs a full harness are tasks where the number of steps and the path can't be stated in advance: how many files need changing, which one to read first, whether the result of one step sends it back to redo an earlier one. Only the model, looking at the current state, can settle those. That's when you want a harness that lets it decide for itself inside a loop while holding it firmly under control. One piece of general restraint is worth keeping: "you should consider adding complexity only when it demonstrably improves outcomes."2 Every piece of control logic in your harness should be there because you hit a real loss-of-control problem, not because everyone else builds it that way.

The rest of this course focuses on the part that matters most in that second kind of task, and breaks most often — the loop itself. Since the harness decides whether an agent is dependable, and loop control is the harness's heart, the next lesson starts with how that loop grows from a single round-trip into something that keeps running.

Recap

  • A harness is the collective name for the control code around the model — running tools, driving the loop, deciding when to stop and when to wait for a person. The model only proposes the next action; the harness rules on whether that action executes and whether the loop continues.1
  • An agent is an LLM using tools in a loop based on environmental feedback.2 What separates it from a workflow isn't model strength but who makes the control-flow decisions: a workflow follows predefined code paths, while an agent's next step is set by the model inside the loop,2 and the thing carrying that loop is the harness — an agent makes its own control-flow decisions inside a loop.3
  • Same model, different harness, completely different result.3 So when an agent is unreliable, check the harness layer first: turn limits, no-progress detection, and approval for high-impact actions usually fix more than a stronger model does.
  • A harness is a set of parts, not a single object: loop control, tool dispatch, and context management each have their own job.3 Context in particular needs managing, because every turn of the loop piles more data into the conversation and draws down a finite attention budget.4
  • Not every situation needs a full harness. Tasks with a fixed path are fine as workflows;2 reach for a harness only when the steps and the path can't be stated in advance and the model genuinely has to decide for itself, and add complexity only when it demonstrably improves outcomes.2

>> Lesson 2: The Core Loop: From One Round-Trip to Continuous Operation

Footnotes

  1. How tool use works — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works ↩ ↩2

  2. Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13

  3. The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) — https://github.com/codejunkie99/agent-roadmap-2026 ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7

  4. Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents ↩ ↩2 ↩3 ↩4

Exercises

01

Below is a scenario where an agent automatically fixes failing unit tests. Five things happen along the way. For each one, decide whether it's the model doing it or the harness (the control code around the model), and give a short reason.

Level 1: Sort Out Who Owns Each Step
  1. The model reads the test failure, replies with a message saying it wants to call read_file on the file that failed, and stop_reason is "tool_use".
  2. The program actually goes to disk and reads that file.
  3. The program wraps the file contents in a tool_result, appends it to the conversation, and sends another request.
  4. The loop has gone twenty turns without a fix, and the program decides not to continue, stopping and reporting "turn limit reached."
  5. On some turn the model proposes calling delete_file on the entire test directory. The program blocks it and pops up "this operation deletes files, confirm?" to wait for a person to say yes.
Done criteria · checked locally
02

Your team has an agent whose job is to make the corresponding inserts, updates, and deletes in a database based on a user's plain-language description. Two problems showed up after launch. For each one, decide whether it should be fixed mainly at the model layer (swap the model, change the prompt) or the harness layer (change the control code on the outside), and explain why.

Level 2: Decide Which Layer to Fix It In
  • Problem A: The agent occasionally turns a vague "clean up those old records" into a statement that deletes thousands of rows, and runs it immediately, which caused one real data-loss incident.
  • Problem B: The SQL the agent generates often has syntax errors and misspelled column names, so many calls fail outright.
Done criteria · checked locally