Foundation · 1 of 9
What an agent harness is
An LLM can suggest the next words. A working agent needs another program to decide what the model sees, turn structured suggestions into actions, preserve useful state, and keep the run inside its authority.
§1
Start with the model
A model is a learned function. At runtime, the application sends it an input sequence and asks it to produce a continuation. That runtime computation is inference.
The input is usually represented as messages: instructions, user text, earlier assistant output, and tool observations. People often call the assembled input a prompt. In an agent, “prompt” means the whole request presented to the model, not only the user’s latest sentence.
A model-provider adapter (also called a model adapter) translates the harness's internal messages, tool definitions, and model settings into the request format required by one model-inference provider. On the way back, it normalizes streamed output, usage, and errors into the harness's own vocabulary. Here, “provider” means the service or runtime performing inference—not a tool, plugin, or hosting provider.
The model does not open a file merely because it emits text that resembles read_file({"path":"app.ts"}). It has proposed a continuation in a structured vocabulary. A surrounding program must recognize that proposal, decide whether it is valid and allowed, perform the read, and return the result in a form the model can use.
§2
The harness boundary
An agent harness is the control system around model inference. It assembles the next input, publishes a tool vocabulary, validates model output, mediates real effects, records what happened, and chooses whether to call the model again.
An agent is the running whole: model plus harness plus available capabilities and current state, operating toward a goal. This primer uses “model” for the learned component, “harness” for the controlling software, and “agent” for their combined behavior. Keeping those nouns separate prevents a great deal of magical thinking.
| Actor | Owns | Does not establish by itself |
|---|---|---|
| User | Goal, constraints, approvals, credentials, and the authority delegated to the run. | That the model will interpret the goal correctly. |
| Harness | Input assembly, control flow, validation, policy checks, execution plumbing, records, and stop conditions. | That an external command will succeed or that the model’s proposed plan is wise. |
| Model | A probabilistic proposal: prose, structured calls, intermediate choices, or a final answer. | Permission, successful execution, or truth about the environment. |
| Environment | The actual outcome of reading, computing, calling an API, or changing an external system. | That the outcome was intended, authorized, or correctly interpreted. |
The compact version is: the model proposes; the harness mediates; the environment determines what happened; the user supplies authority. Real systems add services and layers, but this four-owner ledger remains a reliable first approximation.
§3
Eight terms that should stay distinct
Model
The learned component that proposes a continuation from its current input.
Inference
One runtime model computation. A multi-step agent turn can contain several inferences.
Message
A role-tagged input or output unit. Harnesses often support more message types than providers do.
Prompt
The complete model-visible input assembled for one inference.
Tool
A named, schema-described capability the harness can expose and may execute.
Environment
The external system where observations and effects occur: files, processes, browsers, APIs, or people.
State
Information retained outside the model’s transient computation: messages, events, settings, artifacts, and summaries.
Harness
The software that coordinates the other pieces and turns repeated inference into an operational loop.
A tool has at least two faces. The model sees a name, description, and argument schema. The environment sees a concrete function call with process permissions, network reach, and possible side effects. The harness connects those faces; it should never confuse a well-formed request with an authorized action.
§4
The model sees a constructed world
The model does not automatically see the repository, the terminal, the full conversation, the harness’s database, or even every available tool. It sees the model request built for this inference. A harness may include system instructions, a selected history tail, retrieved files, summaries, tool schemas, and current user text. It may omit older detail, private state, or capabilities outside the task.
“The agent knows the file exists” is often the wrong sentence. Perhaps the file path appeared in a message. Perhaps a search tool returned it. Perhaps the harness stored it but did not place it in context. Those are different information paths with different failure modes.
State also has multiple layers. The transcript is a record of conversational events. The working context is the subset and transformation sent to the model now. Durable state may include artifacts, task metadata, approvals, checkpoints, indexes, and event logs that never appear verbatim in a prompt.
§5
Where harness design begins
A chat wrapper can make one model call and display the answer. An agent harness earns its complexity when it must manage a loop across time and effects. Design choices appear immediately:
- Which messages and tools enter each model request?
- How does structured model output become typed program input?
- Which checks happen before an effect, and which evidence is collected after it?
- What remains in the model’s bounded context, and what moves to durable storage?
- How are retries, cancellation, partial output, tool failure, and user interruption represented?
- Can extensions change the loop, observe events, add tools, or replace capability providers?
Different harnesses answer those questions at different layers. The next chapter traces a single successful turn and its failure branches. Once that control flow is visible, package names and product features become much easier to place.