Chapter Goal

Introduce one of the most important concepts in this book: the Agent Harness, a runtime framework for AI agents. Building on Chapter 2, The Fundamental Architecture of LLM Applications, and Chapter 3, The Agent Loop: The Core 100 Lines of an AI Agent, this chapter answers a critical question: What assembles the model, context, tools, and loop into a machine that can operate autonomously?

The answer is the Harness.

Understanding the definition, boundaries, and responsibilities of an Agent Harness is essential for the Claude Code source-code analysis in Part III and for building Mini Claude Code in Part IV.

4.1 Defining the Agent Harness

Before defining the Harness, let us return to the conclusion from Chapter 2.

Chapter 2 introduced seven fundamental components of an LLM application:

Model, Prompt, Context, Tool, Memory, State, and Runtime.

The first six are essentially the parts. Runtime is the pipeline that assembles those parts into an executable system.

However, the Runtime discussed in Chapter 2 is deliberately minimal. It organizes requests, calls the model, and executes tools. For a simple question-and-answer application, that may be enough.

But once an application evolves into an Agent, the requirements change dramatically.

The model must be able to operate autonomously, repeatedly interact with external systems, recover from failures, respect permissions, maintain state, and operate safely in the real world.

The Runtime therefore has to evolve.

It needs to manage the loop introduced in Chapter 3. It needs permissions, sessions, memory, observability, cost controls, and recovery mechanisms.

This expanded Runtime is what we call the Agent Harness.

The word harness originally refers to the equipment used to control and guide a horse—reins, straps, and other gear used to direct its movement.

The metaphor is surprisingly accurate:

The model is an extremely intelligent but inherently uncontrollable horse. The Harness is the complete set of reins, controls, and equipment that allows us to safely direct it.

From an engineering perspective, we can define it as follows:

An Agent Harness is a runtime framework surrounding an LLM that transforms the model’s reasoning capabilities into reliable, safe, controllable, stateful actions in the real world.

More technically, the Harness is the software system that connects the model to the real world.

It performs four fundamental functions:

1. Translate In — Transform the task and relevant state into information the model can understand, primarily through context.
2. Translate Out — Transform the model’s intentions into executable actions through tools.
3. Translate Back — Transform the results of those actions into information the model can consume.
4. Control and Record — Make the entire process reliable, secure, observable, and recoverable through loops, permissions, sessions, memory, and telemetry.

There is an important insight here that is easy to overlook:

The Harness is not an optional wrapper around the model. It is the bridge that turns “a model that can talk” into “an Agent that can act.”

Without a Harness, an LLM is essentially a highly capable text-generation system.

With a Harness, that same model can become part of a system capable of executing and completing real-world tasks.

Consider how an LLM application might evolve from answering a weather question to autonomously managing a user’s daily tasks:

Each capability upgrade is not necessarily the result of a smarter model.

Instead, the Runtime acquires another responsibility.

Once enough responsibilities accumulate, the Runtime is no longer the lightweight glue layer described in Chapter 2. It has evolved into a complete Agent Harness.

This is why the Harness is better understood as something that grows out of the Runtime rather than something invented independently from scratch.

Note: Chapter 1 introduced the formula Agent = LLM + Harness. Here, “LLM” is used as a generic term for models such as Anthropic Claude, OpenAI GPT, Google Gemini, Meta Llama, Qwen, DeepSeek, and locally deployed models. The Harness is fundamentally model-agnostic. That independence is one of its most important infrastructure characteristics.

4.2 Model vs. Agent vs. Harness

This is one of the most important conceptual distinctions in the entire book.

The three terms are often used interchangeably, but they represent three different abstraction layers.

Chapter 1 introduced the basic formula. This section provides a more precise engineering definition.

4.2.1 Model

A model can be viewed as a stateless computational function:

Input: a sequence of tokens
Output: a sequence of tokens

As discussed in Chapter 2, the model does not inherently remember previous invocations, maintain application state, or directly produce side effects.

Its primary value is reasoning:

• understanding
• planning
• decision-making
• generation

But the model cannot independently read a file, execute a shell command, modify a database, or access an external service.

Those capabilities must be provided by the surrounding system.

4.2.2 Agent

An Agent is a goal-oriented behavioral system.

Using the definition introduced in Chapter 1:

Agent = LLM + Harness

Agent = LLM + Harness

The Agent’s purpose is to achieve a goal.

Given an objective, it can iteratively determine what to do, invoke tools, observe results, adjust its strategy, and continue until the task is completed or execution must stop.

4.2.3 Harness

The Harness is the infrastructure layer that provides the environment in which an Agent operates.

It does not replace the model’s reasoning capability.

Instead, it manages everything required around the reasoning process and between individual actions:

• context
• tools
• permissions
• state
• memory
• sessions
• execution
• recovery
• observability
• extensibility

4.2.4 An Analogy for Understanding the Three Layers

This analogy will continue throughout the book. Chapter 54 will explore the idea of “Harness ≈ Operating System” in detail.

The analogy reveals an important architectural principle:

Model, Agent, and Harness are three different abstraction layers—not three names for the same thing.

Confusing these layers can lead to fundamental architectural mistakes.

For example, an organization may assume that replacing its model with a more powerful one will automatically make an Agent reliable, while the actual problem lies in permissions, context management, tool execution, state management, or recovery.

4.2.5 Evidence from Claude Code’s Source Code

The idea that the model is a resource orchestrated by the Harness is not merely a conceptual distinction.

In the analyzed Claude Code source snapshot dated March 31, 2026, the Harness’s core engine includes a QueryEngine that is initialized with a substantial set of dependencies:

// src/QueryEngine.ts: QueryEngineConfig (excerpt)

export type QueryEngineConfig = {
  cwd: string
  tools: Tools
  mcpClients: MCPServerConnection[]
  agents: AgentDefinition[]
  canUseTool: CanUseToolFn
  getAppState: () => AppState
  maxTurns?: number
  maxBudgetUsd?: number
  taskBudget?: { total: number }
  abortController?: AbortController
  userSpecifiedModel?: string
  fallbackModel?: string
  // ...
}

// src/QueryEngine.ts: QueryEngineConfig (excerpt)

export type QueryEngineConfig = {
  cwd: string
  tools: Tools
  mcpClients: MCPServerConnection[]
  agents: AgentDefinition[]
  canUseTool: CanUseToolFn
  getAppState: () => AppState
  maxTurns?: number
  maxBudgetUsd?: number
  taskBudget?: { total: number }
  abortController?: AbortController
  userSpecifiedModel?: string
  fallbackModel?: string
  // ...
}

The important point is not the exact field names.

The architectural signal is that the model is represented as a configurable model identifier, such as userSpecifiedModel or fallbackModel, rather than being hard-coded as an inseparable component of the engine itself.

The actual model client is resolved by the underlying service layer.

This suggests an architecture in which the model is a replaceable runtime dependency managed by the Harness.

That distinction is important because it means Agent capabilities can often be changed through dependency substitution rather than by modifying the core runtime:

• change the model
• change the tools
• change the permission policy
• change the execution environment

This is one of the key differences between Harness Engineering and simply optimizing prompts.

4.3 Core Responsibilities of an Agent Harness

What exactly does a Harness do?

The following architecture illustrates its major responsibilities:

                ┌───────────────┐
                │      LLM      │
                └───────┬───────┘
                        │
                Reasoning / Tool Call
                        │
              ┌─────────▼─────────┐
              │   Agent Harness  │
              ├───────────────────┤
              │ Agent Loop        │
              │ Context Manager   │
              │ Tool Runtime      │
              │ Permission        │
              │ Memory            │
              │ Session           │
              │ Hooks             │
              │ Subagents         │
              │ Observability     │
              └─────────┬─────────┘
                        │
          ┌─────────────┼──────────────┐
          ▼             ▼              ▼
        Files         Shell          Network

This architecture highlights nine major Harness responsibilities.

These responsibilities can be summarized in one sentence:

The Harness is the system of translation, control, and observability between the model and the real world.

• Translation: Context and Tools
• Control: Loop, Permission, Session
• State and recording: Memory and Observability
• Extension: Hooks and Subagents

Without these capabilities, an Agent may be unable to act, may act unsafely, or may become impossible to understand and operate.

However, these nine responsibilities should be understood as a reference architecture, not a universal specification. Different Agent frameworks may combine, rename, or omit some of these components depending on their use cases.

4.3.1 Mapping Harness Responsibilities to Source Code

Source boundary: The following mapping is based on observations from the analyzed Claude Code source snapshot dated March 31, 2026. It should be treated as a source-code observation rather than a universal definition of Agent Harness architecture.

The value of this mapping is that it takes the abstract concept of a Harness and connects it to actual software architecture.

After studying Part III, readers can return to this table and see how the conceptual responsibilities are implemented in a real Agent system.

4.4 Why the Harness Matters More Than the Prompt

One of the most common misconceptions about Agents is:

“If the prompt is good enough, the Agent will work well.”

In an Agent context, this is incomplete—and potentially dangerous.

Chapter 2 introduced an important distinction:

The Prompt influences what the model is instructed to do, while Context determines what information the model has available to make that decision.

We can take this one level further:

Prompt Engineering influences the model’s intended behavior; Harness Engineering determines the operational environment in which that behavior can actually succeed safely and reliably.

Consider a simple example.

Suppose you write an excellent prompt:

“Refactor this project and improve its performance.”

Now consider what happens if the Harness lacks key capabilities:

• No file tools → The model can discuss the code but cannot actually modify it.
• No permission controls → The Agent may perform destructive operations.
• No context management → The context may become too large halfway through the task.
• No test execution → The Agent has no reliable way to verify whether its changes work.

The distinction can therefore be expressed more precisely:

A Prompt is local to an interaction; a Harness is systemic.

A carefully designed prompt may improve the behavior of one task.

A reliable Harness determines whether an entire class of tasks can be executed consistently, safely, and repeatedly.

This is why the Harness becomes increasingly important as Agents move from demos into production environments.

There is also a deeper architectural reason.

As models become more capable, some forms of Prompt Engineering may become less important because models become better at understanding natural-language instructions.

Harness Engineering, however, addresses a different class of problems:

• security
• permissions
• execution
• state
• reliability
• observability
• recovery
• evaluation
• governance

These problems do not disappear simply because the model becomes smarter.

In fact, they often become more important as the Agent gains access to more powerful tools.

4.5 Harness Engineering

If the Harness is so important, then there should be an engineering discipline focused specifically on building and operating it.

In this book, we call that discipline:

Harness Engineering

4.5.1 The Core Problem Domains

Harness Engineering covers the major responsibilities introduced in Section 4.3, with several closely related areas grouped together.

1. Context Engineering

How do we select and organize the most valuable information within a limited context window?

This includes:

• context construction
• context selection
• compaction
• summarization
• relevance management

2. Tool Engineering

How do we design, organize, schedule, and execute tools so that models can use them efficiently and reliably?

3. Permission Engineering

How do we balance usefulness and safety?

An Agent needs enough authority to accomplish its task, but not unlimited authority to affect the environment.

4. Loop and Reliability Engineering

How do we keep an Agent making progress while handling:

• failures
• timeouts
• retries
• interruptions
• crashes
• partial completion

5. Memory and State Engineering

How do we allow an Agent to retain useful information across sessions and reliably resume interrupted work?

6. Extension Engineering

How do we customize Agent behavior through Hooks and other extension points without modifying the core runtime?

7. Multi-Agent Engineering

How do we use Subagents to decompose and execute multiple subtasks, potentially in parallel?

8. Observability and Evaluation Engineering

How do we trace, debug, measure, and evaluate Agent behavior at scale?

4.5.2 How Harness Engineering Differs from Traditional Software Engineering

Harness Engineering has deep roots in backend engineering and distributed systems, but it introduces a fundamentally different engineering object:

The core system being engineered is a non-deterministic Agent rather than deterministic application code.

This creates problems that traditional engineering patterns do not completely solve.

For example:

• How do we defend against Prompt Injection?
  Traditional input validation alone is insufficient because the system’s behavior is influenced by model interpretation.
• How do we evaluate a non-deterministic Agent?
  A simple unit-test assertion may not capture whether an Agent successfully completed a complex task.
• How do we determine whether an Agent is stuck or simply taking a longer reasoning path?
  A fixed timeout cannot always distinguish useful progress from non-convergent execution.

This changes the engineering mindset.

We are no longer engineering only deterministic software.

We are engineering software systems that contain a probabilistic decision-making component.

4.5.3 A Useful Analogy

A useful analogy runs throughout this book:

Harness Engineering is to Agents what Operating System Engineering is to computers.

Operating-system engineers do not primarily determine how fast the CPU should perform its calculations. They manage the environment around the CPU:

• memory
• processes
• files
• permissions
• scheduling
• isolation
• signals

Similarly, Harness engineers do not determine how intelligent the underlying model is.

They engineer the environment around the model:

• context
• tools
• permissions
• execution
• state
• reliability
• observability

This analogy also explains why Harness Engineering becomes more valuable as Agent complexity increases.

As software systems became more sophisticated, operating systems became increasingly important.

The same principle applies to Agent systems.

4.5.4 From “It Works” to “Production-Ready”

A common pattern in Agent development is the gap between:

“It works in a demo.”

and

“It is reliable enough for production.”

Many Agent projects can successfully demonstrate one happy-path scenario but fail when exposed to real-world conditions.

The root cause is often not model capability alone.

It is the absence of a sufficiently mature Harness.

A practical production Agent typically needs at least five capabilities:

1. Failure Recovery — It can recover from interruptions and failures.
2. Cost Governance — It cannot consume unlimited model or infrastructure resources.
3. Permission Boundaries — It cannot arbitrarily perform privileged or destructive operations.
4. Observability — Operators can understand what happened and why.
5. Evaluation — Teams can measure and compare Agent behavior systematically.

These capabilities belong primarily to the Harness layer.

This leads to a useful engineering principle:

The model helps determine whether an Agent can solve a task; the Harness determines whether the system can reliably operate in production.

When an Agent is “sometimes brilliant and sometimes completely unreliable,” the instinct is often to replace the model.

Before doing that, inspect the Harness.

• No permission system? The Agent may cause damage.
• No cost controls? The Agent may consume the budget.
• No observability? Failures become impossible to diagnose.
• No recovery? A transient failure can destroy hours of work.

A surprisingly large number of Agent reliability problems are therefore system-engineering problems rather than model-intelligence problems.

4.6 Will the Harness Disappear as Models Become More Capable?

This is one of the most frequently asked questions in the Agent ecosystem:

“If models keep getting smarter, will we eventually no longer need a Harness? Could the model simply handle everything itself?”

Scope of this section: The following is the author’s perspective rather than a proven fact or quantitative prediction. The argument is based on the responsibilities and architecture observed in modern Agent systems.

My conclusion is straightforward:

The Harness will not disappear. Its form will evolve.

There are three primary reasons.

4.6.1 Model Capability Does Not Eliminate the Need for an Execution Environment

Regardless of how capable a model becomes, the model itself does not automatically gain direct ownership of the surrounding execution environment.

A model may generate an intention such as:

“Read this file, modify the configuration, run the tests, and deploy the change.”

But some external system still has to:

• access the filesystem
• execute commands
• connect to services
• enforce permissions
• record side effects
• manage state

The fundamental architectural relationship remains:

The model generates decisions or intentions; the surrounding system executes and controls those intentions.

This is similar to the relationship between a CPU and an operating system.

A faster CPU does not eliminate the operating system because computation and system management are different responsibilities.

Likewise, a more capable model does not eliminate the need for the execution environment surrounding it.

4.6.2 Security Responsibility Cannot Simply Be Delegated to the Model

A model cannot be treated as the final authority for security decisions.

When an Agent interacts with the real world, the system still needs:

• authorization
• policy enforcement
• isolation
• auditability
• human approval for sensitive operations

Consider Prompt Injection.

A highly capable model may still be influenced by malicious or untrusted instructions embedded in data it processes.

The solution is not simply to make the model “smarter.”

The surrounding system needs independent controls capable of preventing unauthorized actions.

This leads to a fundamental security principle:

Security should not depend solely on model intelligence.

The Harness therefore remains responsible for enforcing boundaries around what the Agent is allowed to do.

4.6.3 Harness Complexity Does Not Automatically Shrink as Models Improve

Source observation: If increasing model capability automatically eliminated the need for Harness functionality, we would expect the surrounding runtime architecture to become dramatically smaller.

However, modern Agent systems contain substantial infrastructure around the model itself.

In the analyzed Claude Code source snapshot dated March 31, 2026, the Harness-related architecture includes components such as:

An important clarification is necessary here:

The size of query.ts should not be interpreted as the size of the Agent Loop itself. The file contains substantially more functionality than the core loop.

The broader architectural observation is what matters:

The surrounding Harness infrastructure is substantially larger than the code required to invoke a model.

This strongly supports the idea that Agent engineering is not simply about calling increasingly powerful models.

4.6.4 But the “Weight” of the Harness Will Shift

Although the Harness will not disappear, its internal emphasis may change as models improve.

When models are relatively weak:

• the Harness spends more effort guiding model behavior
• prompts may need to be highly explicit
• outputs may require strict validation
• additional correction mechanisms may be necessary

As models become more capable:

• more tactical decisions can be delegated to the model
• less rigid instruction may be required
• the Harness can focus increasingly on execution, security, isolation, reliability, and governance

In other words:

The Harness can evolve from “teaching the model how to work” toward “providing the model with a safe and reliable workspace in which to work.”

The former may become less important as model capabilities improve.

The latter remains essential—and may become more important as Agents gain more powerful capabilities.

4.7 The Boundaries of an Agent Harness

Finally, we need to understand the boundaries of the Harness.

Understanding what the Harness cannot do is just as important as understanding what it can do.

1. The Harness Cannot Replace Model Reasoning

The Harness provides an environment, not intelligence.

If the underlying model cannot reason adequately about a task, a sophisticated Harness cannot magically solve that fundamental limitation.

A world-class runtime cannot turn a fundamentally incapable model into a capable reasoning system.

2. The Harness Is Not a Silver Bullet

A Harness cannot transform a poor model into an excellent Agent.

Nor can it turn an ambiguous or fundamentally impossible requirement into a well-defined, solvable task.

3. Harness Complexity Has a Cost

Every additional mechanism introduces:

• implementation complexity
• operational overhead
• maintenance cost
• additional failure modes

Adding permissions, context management, Subagents, telemetry, recovery logic, and other infrastructure can improve reliability—but it also makes the system more complex.

4. The Harness Should Be “Just Enough”

The best Harness is not necessarily the one with the most features.

It is the one that provides the right capabilities for the problem being solved.

A practical engineering principle is:

Start with the simplest Harness possible. Add mechanisms when real problems justify them.

This is exactly the methodology followed in Part IV, Building Mini Claude Code from Scratch.

Start with a simple Agent Loop.

Then evolve it incrementally as real problems appear:

Simple Agent
     ↓
Tool Execution
     ↓
Error Handling
     ↓
Context Management
     ↓
Permission Control
     ↓
State & Session
     ↓
Observability
     ↓
Recovery & Governance

Simple Agent
     ↓
Tool Execution
     ↓
Error Handling
     ↓
Context Management
     ↓
Permission Control
     ↓
State & Session
     ↓
Observability
     ↓
Recovery & Governance

This approach is preferable to starting with a massive architecture before understanding the actual requirements.

The opposite approach is over-engineering.

Some teams begin an Agent project with:

• microservices
• multi-agent orchestration
• distributed tracing
• complex memory systems
• elaborate evaluation infrastructure

while the Agent still cannot reliably read a file or execute a simple task.

Harness complexity should be driven by real requirements—not by architectural fashion.

This “just enough” principle is one of the most important engineering lessons in this book.

Chapter Summary

This chapter introduced one of the central concepts of the book: the Agent Harness.

The key ideas are:

1. What Is a Harness?

An Agent Harness is the runtime framework surrounding an LLM that transforms model capabilities into reliable, safe, controllable, stateful real-world actions.

The metaphor is simple:

The model is the intelligent horse; the Harness provides the reins, controls, and environment needed to safely direct it.

2. Model, Agent, and Harness Have Different Responsibilities

• Model — provides reasoning and generation.
• Agent — provides goal-oriented behavior.
• Harness — provides the runtime environment, execution, control, state, and safety mechanisms.

They represent different abstraction layers.

3. The Nine Core Harness Responsibilities

A practical Harness architecture includes:

Agent Loop, Context Manager, Tool Runtime, Permission, Memory, Session, Hooks, Subagents, and Observability.

Together, these responsibilities form a system of:

Translation + Control + State + Observability + Extension

between the model and the real world.

4. Harness Engineering Matters More Than Prompt Engineering Alone

Prompt Engineering influences how a model is instructed.

Harness Engineering determines whether an Agent can reliably execute, recover, operate safely, and scale in production.

The important distinction is not that prompts are unimportant.

It is that prompts solve a fundamentally different class of problems from runtime engineering.

5. The Harness Will Not Disappear

As models become more capable, some forms of model guidance may become less important.

But execution, security, permissions, state management, observability, recovery, and governance remain system-level responsibilities.

The Harness will therefore evolve rather than disappear.

6. Build the Harness Incrementally

The right Harness is not necessarily the most sophisticated one.

Start simple.

Observe real failure modes.

Then introduce the mechanisms required to solve those problems.

Avoid building an elaborate Agent infrastructure before the basic Agent Loop is reliable.

The Core Formula

Agent = LLM + Harness

The LLM provides understanding, reasoning, and generation.

The Harness transforms those capabilities into an Agent system that can execute, control, observe, evaluate, recover, and ultimately deliver real-world outcomes.

Model capability influences the potential of an Agent.

Harness capability determines whether that potential can be turned into a reliable production system.

With a clear understanding of what a Harness is, what it contains, and where its boundaries lie, the next chapter will compare several mainstream Agent architectures—including Claude Code, OpenAI Agents, LangGraph, and Cline.

By comparing their architectural choices, we can develop a deeper understanding of how different Agent systems implement the same fundamental idea: building a reliable runtime around a capable model.

Please follow and like us:

Related posts:

Chapter 3 — The Agent Loop: The Core Execution Cycle of an AI Agent Chapter 1: Rethinking AI Agents Chapter 2 — LLM Application Architecture: Core Components and Engineering Foundations AI Agent Architecture and Engineering Practice Guide The Key Milestones in the History of Artificial Intelligence (2026.08) Building a Python-based AI Agent with LangGraph and OpenRouter: A Hands-On Guide A Comprehensive Guide to AI Agents: Definition, Role, Examples, and Future Prospects Artificial Intelligence (AI) Learning Roadmap for Beginners in 2025