AI Agents: Clarifying the Concepts of Harness and Scaffolding

In the ever-evolving world of artificial intelligence agents, the associated vocabulary often develops at a pace that surpasses common understanding. Terms get mixed up, reused in various contexts, or become abbreviations for ideas that are never fully explained. This situation is particularly evident in the field of AI agents, where some concepts are renamed, others are widely used for a few months before quietly disappearing.

This dynamic can be overwhelming for newcomers and even for practitioners trying to keep up with the latest developments. After the ICLR 2026 conference, a participant (@ariG23498) posed a question that aptly illustrates this confusion: "What do you mean by the terms 'harness' and 'scaffolding' in the context of agents? I heard many explanations while I was at ICLR, but I didn't understand why they didn't converge on a single explanation."

This glossary is an attempt to clarify the terms that frequently arise without clear and coherent explanations. It is not intended to be a comprehensive dictionary of every term in the field. Instead, it focuses on concepts that are often confused, reused in different ways, or assumed to be obvious when they are not.

Most of these terms appear whether you are building an agent, deploying one, or simply using tools like Claude Code, Codex, or Hermes Agent. The final section covers concepts specific to model training, which is more relevant if you work in that area.

Many of these terms do not yet have universally accepted definitions, and different frameworks use the same word in different ways. The goal here is not to impose a correct vocabulary but to provide a practical mental model that facilitates discussions.

Context Engineering

The model is the LLM: it takes text as input and produces text as output (for example, Claude, Qwen, GPT, Kimi, DeepSeek…). By itself, it has no memory between calls and no loop. The model can express the intention to call a tool, but it needs a harness to actually execute it. It responds to a prompt and stops. By wrapping it in scaffolding and a harness, it becomes an agent.

The layer defining the behavior around the model: system prompt, tool descriptions, how the model's responses are analyzed, what it remembers across steps (context management). This shapes how the model perceives the world and acts within it, whether during training or inference.

Products like Claude Code, Codex, and Antigravity CLI refer to the entire structure as a harness. The Claude Code documentation states directly: "Claude Code serves as an agentic harness around Claude." This is the broad usage: the harness means everything that is not the model. The distinction between scaffolding and harness is particularly important when you need to reason about them separately, such as in a training pipeline. You will also hear "scaffolding" used more broadly to cover any infrastructure on which the harness relies: hooks, execution configuration, even directory structure.

Some products like Claude Code and Codex are closely tied to their provider's models. Others like Antigravity CLI and Hermes Agent allow you to plug in any model.

The execution layer within the agent: it calls the model, manages its tool calls, decides when to stop. The harness is what makes the agent work. The scaffolding, defined above, is what the model works from: its instructions, its tools, its format.

Harness engineering is the discipline of designing this layer: deciding when the agent should stop, how errors are handled, and what safeguards keep it on track. This applies to both training and inference. The article by Addy Osmani and OpenAI's report on building with Codex cover this from the inference side.

At evaluation time, the same pattern appears in the form of an eval harness: instead of collecting training data, it executes a fixed set of scenarios at a model checkpoint and records metrics rather than updating weights.

Some frameworks use the term orchestrator to refer to a higher-level controller that coordinates work between multiple agents. Unlike a harness, which drives a model through its execution loop, an orchestrator manages agents as units, each executing its own harness (see sub-agents below).

The term comes from reinforcement learning, where an agent is simply a function that takes an observation and returns an action. The environment takes this action and returns a new observation, and the loop repeats. This loop is always at the heart of how LLM agents operate.

In the world of LLMs, the term has been broadened. An agent is a model plus everything surrounding it that allows it to act, not just respond. It transforms raw text generation into something that can act in a loop: taking information, deciding what to do, and acting on the results.

Take a coding agent as a concrete example. The system prompt, tool descriptions, and the output format that the model follows form the scaffolding. The loop that calls the model, manages its tool calls, and decides when to stop is the harness. During training, the harness also executes many of these loops in parallel and returns results to update the model.

In the community, this is generally formulated as Agent = Model + Harness (@Vtrivedy10 and Will Brown's tweet for reference). If you are not the model, you are the harness. The subtle distinction between harness and scaffolding that creates most of the confusion is what the two sections above address.

When people talk about products like Claude Code, Codex, or Cursor, they are referring to a specific harness built on a specific model, designed and optimized together. Two products using the same underlying model can seem completely different because their harnesses make different choices. And replacing a better model in the same harness also changes the experience. The model, the harness, and the product are three different things.

Context Engineering

Designing what goes into the agent's context window: what the model sees at each step, system prompt, tool descriptions, conversation history, retrieved knowledge. This is not a one-time decision: as the model operates, previous turns shape what goes into future calls, and the harness actively manages this throughout execution. This applies to both training and inference, but the cost of getting it wrong is very different. During training, what the model sees shapes what is learned. If you get it wrong, you need to retrain. During inference, it's just text: change a prompt and redeploy. The HF context engineering course covers this in depth.

Memory is part of this picture. Short-term memory is what remains in the context window during a single execution: conversation history, tool results, previous reasoning. Long-term memory persists between sessions, stored externally and retrieved on demand, then injected back into the context when relevant.

A policy is the behavior that an agent follows: given a certain situation, it defines the probability of taking each possible action. In LLM systems, part of this policy is learned in the model's weights, but behavior also depends on the surrounding scaffolding and harness. The same model can behave very differently depending on its prompts, tools, memory, and execution loop.

A policy is not an agent. The policy defines behavior; the agent is the complete system that acts in an environment. Wrap a checkpoint in scaffolding and a harness and deploy it, and you get an agent whose behavior is the policy.

How agents reach outside themselves: APIs, code interpreters, databases, web search, file systems. The model expresses the intention to use a tool in a structured format. Modern inference APIs present this as a first-class object: the harness receives the call directly and directs it to the appropriate function. The result is returned in context and the loop continues.

Reusable, structured knowledge packages that enable multi-step tasks. Where a tool is an action ("execute this command"), a skill encompasses everything needed to achieve a goal ("investigate this bug, formulate a hypothesis, write a fix"). They are portable between agents and loaded on demand. The line between tool, skill, and sub-agent varies across frameworks. The HF context engineering course covers skills in depth.

An agent called by another agent to handle a specific sub-task. It has its own model and scaffolding, reasons independently, and returns a result. The calling agent does not need to know how it works internally. This is what separates a sub-agent from a tool (a function call) or a skill (packaged knowledge): a sub-agent can reason itself, use tools, and call other sub-agents. The calling agent is sometimes referred to as an orchestrator.

The above terms apply whether you are training or deploying. These four are specific to training, where the agent executes tasks, is scored, and the weights of its model are updated. Every RL training system for LLMs is built around the same pipeline:

• The environment is everything you can interact with: a stateful object that takes an action as input, updates its internal state, and returns an observation. In the context of LLMs, actions are generally tool calls. A file system is a simple example: the action touch foo.txt updates the state by creating the file, and the observation could be the updated list of files. Definitions vary across frameworks.

We recently published a dedicated guide on this topic, so rather than compressing it here, check out The Ultimate Guide to RL Environments for a complete breakdown of types, frameworks, and examples.

• The trainer is what makes the agent better: it runs many episodes of agents, scores the results, and uses them to update the model's internal weights. The GRPOTrainer from TRL is a concrete example: a single class that manages episode generation, reward scoring, and weight updates.

• A rollout is a complete execution of the agent from start to finish: what the agent saw, what it did, and what reward it received at each step. It is also called a trajectory or trace, depending on the context. This is the raw data that RL algorithms use.