跪拜 Guibai
← Back to the summary

Agent Harness vs. Agent Runtime: The Boundary That Ends the Naming War

Understanding the Difference Between Agent Harness and Agent Runtime in One Article

Same Agent, same model — swap the Runtime and it can go live stably; swap the Harness and its entire personality gets rewritten.

This article thoroughly dissects the core terminology of Agent systems — Harness (wiring/driver) and Runtime — from definitions, responsibilities, lifecycles, interfaces, resource management, security isolation, extensibility, observability, deployment models, performance, and fault recovery to typical use cases, all in one go. It also provides a discrimination method, a layered architecture diagram, a real-world framework comparison table, and a selection checklist, helping you completely eliminate the confusion of "are these two words the same thing?"

This article references the original X Article by Smartpig (@Smartpigai) and integrates real-world implementation experience from projects like OpenClaw, Claude Code, AgentScope, QwenPaw, AWS AgentCore, and Azure Agent Service.

1. Opening: A Naming Accident That Confused Everyone

In the first half of 2026, the AI Agent field experienced a textbook-level "terminology drift."

The same developers, the same community, discussing the same question — "What exactly should we call that layer of engineering wrapped around my Agent?" — split into two camps, and neither side was talking nonsense.

Camp A: Call it Harness. In the communities of OpenClaw, Claude Code, and Hermes, this word has become synonymous with "Agent Engineering." Microsoft calls it "runtime scaffolding," used to drive model calls, manage context, and enable the agent to keep moving forward. The industry has even spawned a new discipline called Harness Engineering, specifically studying "how to build that layer of stuff around the model." The mainstream view condenses it into a formula: Agent = Model + Harness.

Camp B: Call it Runtime. Intuitionists from traditional software engineering firmly believe that anything "responsible for scheduling, executing, and managing state" should be called a runtime. Google Cloud's architecture guide clearly states: "An agent runtime is the compute environment where the agent's application logic runs." Erlang/OTP has the Erlang Runtime, Node.js has V8 + libuv Runtime, Java has the JVM — now Agents also need an Agent Runtime to manage their processes, isolated environments, resource scheduling, and lifecycle.

So you see this bizarre scene in GitHub READMEs, tech blogs, and architecture review meetings:

"Based on our self-developed Agent Runtime, we implemented a complete Harness Engineering solution, enhancing the Runtime through the Harness Framework..."

In one sentence, Runtime and Harness are freely interchanged like synonyms. The comment sections are therefore fiercely debated.

This article has only one goal: to end this confusion.

After reading, you should be able to do three things:

  1. Explain the essential difference between the two in one sentence;
  2. Pick up any open-source Agent framework and determine within 30 seconds which category it belongs to (or if it has both);
  3. When designing your own Agent system, clearly know "should this line of code be written in the Harness layer or the Runtime layer."

2. Back to the Source: The Historical Baggage of Each Word

The root of the confusion is not conceptual ambiguity, but that each word carries a completely different semantic baggage, and authors, when coining terms, default to the assumption that readers "understand my baggage."

2.1 Harness's Baggage: From Hardware and Automobiles

Harness's original English meaning is "horse tack" — the entire set of belts and metal parts that fit on a horse, connecting the reins to the carriage.

But it truly established itself in the engineering world in two scenarios: automotive wiring harness and test harness:

The commonality of these two scenarios is extremely important, please remember it:

Harness is a "connector," not an "executor." It does not generate behavior itself; its value lies in constraint, wiring, and protection.

So when the industry borrowed this word to describe the outer engineering of an Agent, it inherited exactly this layer of semantics: The model is the engine, the Harness is the wiring harness — it does not think for the model, it determines which tools the model can touch, which context it can see, which step must be approved by a human first, and where to roll back when an error occurs.

More specifically, the Harness is the application-layer logic located above the base model, providing the model with multi-step planning, tool invocation, state management, policy control, and other functions, enabling a model that originally only generates text to complete multi-step tasks. If the model is seen as the brain, the Harness is the workbench, notebook, tools, and permission system surrounding the brain.

And the complete definition of the new discipline Harness Engineering can be summarized in one sentence:

Model capabilities are probabilistic, drift-prone, and occasionally uncontrollable. What truly makes an Agent usable, controllable, and evolvable is the layer of engineered "skeleton" outside the model: structured context, constraining tool protocols, lifecycle hooks, recoverable state, and observable evaluation.

This judgment has been repeatedly verified in multiple real-world implementations. For example, an Agent in a Taobao live-streaming scenario was pushed to an extremely harsh stress test: the instructions issued by the Agent were immediately effective and public-facing, errors were irreversible, and the cost was real money, while the host in front of the camera had no capacity to verify every action of the Agent one by one. This means the Agent's safety boundary must be guaranteed by engineering, not by manual review — this is precisely the Harness's home turf.

2.2 Runtime's Baggage: From Operating Systems and Virtual Machines

Runtime's historical baggage is completely opposite; it comes from the execution environment lineage:

Technology What its "Runtime" is responsible for
JVM Bytecode interpretation/compilation, GC, class loading, thread scheduling
Erlang VM Process creation/isolation, message passing, fault-tolerant supervision tree
Node.js (V8+libuv) Event loop, non-blocking IO, asynchronous scheduling
WebAssembly Linear memory, instruction interpretation, sandbox isolation
Kubernetes Pod Container orchestration, network/storage mounting, lifecycle callbacks

Their commonality is equally clear:

Runtime is the "engine + gearbox," and its natural duty is "to make code actually run."

In the Agent context, Runtime is similar to an "Agent-specific Lambda" — an infrastructure layer that provides a secure isolated execution environment, resource scheduling and limits, network and credential management for the agent. It is responsible for creating isolated sessions (like containers or micro-VMs), managing resource quotas, controlling network ingress/egress, injecting short-term credentials, and providing persistent state and concurrent scheduling.

This is Runtime's territory; Harness does not touch it at all. You wouldn't ask a car's wiring harness "what is your gasoline combustion efficiency," and similarly, you shouldn't make the Harness responsible for thread pool size, container restart policy, or GC parameters.

2.3 The Real Reason for Confusion

So why does everyone still mix up these two words? Three real reasons:

  1. Agent is a new species with no mature paradigm. The Java ecosystem took 30 years to clearly argue out the boundaries of Runtime / Container / Framework / Library. The Agent ecosystem is still at a stage where even the word "framework" is being redefined by AgentScope, LangGraph, and CrewAI.
  2. Modern Agent frameworks are "packaged and delivered." LangGraph gives you both a loop engine (Runtime attribute) and checkpoint storage + human approval (Harness attribute). You install one package, which equals installing two layers simultaneously, so describing it inevitably mixes the two words.
  3. The word Harness is too charming. It is more vivid than Runtime and carries a stronger implication of "engineering craftsmanship," so it spreads faster in blog titles — but this creates the slippery slope of "all outer engineering is called Harness."

After recognizing these three points, confusion is no longer a knowledge problem, but a choice problem: you must actively set dead boundaries for these two words.

3. One-Sentence Definition + Three Discrimination Questions

The following definition can be directly copied into your team's Wiki.

Agent Harness

The software layer located above the base model, responsible for organizing agent behavior. It includes prompt engineering, tool interfaces, execution loops, memory, and policies, enabling a model that originally only generates text to complete multi-step tasks.

Harness is a replaceable policy layer — swapping a Harness is equivalent to swapping the Agent's personality, permission boundaries, and work methodology.

Agent Runtime

The infrastructure layer that provides the actual execution environment for the agent. Similar to a cloud function or container environment, it is responsible for scheduling and running agent logic and tool execution.

Runtime is a replaceable execution layer — swapping a Runtime, the Agent's personality and prompts can remain completely unchanged, but its stability, concurrency capability, and deployment form will change.

One-sentence comparison:

Harness defines the way the agent "thinks" and "acts"; Runtime is responsible for where and how to safely execute these actions.

A more concise version:

Harness decides what the Agent "thinks, can do, and is allowed to do"; Runtime decides "where it runs, how fast it runs, and how it recovers if it crashes."

If you understand 80% of this sentence, the rest is about landing it on discrimination criteria. Facing any Agent system, ask three questions:

Three Discrimination Questions

Q1: If this module is changed, will the Agent's "personality/behavior/knowledge" change?

Q2: Is the core output of this module "content" or "process"?

Q3: If this module is deleted, will the Agent "become dumber/more dangerous" or "fail to run"?

Looking back at QwenPaw v2.1.0's harnesses/ sub-package with these three questions, the judgment becomes immediately clear. This sub-package's docstring says "Third-party agent runtime integrations" — note that it is integrating someone else's Runtime. HarnessRuntime takes over exactly four things that QwenPaw must personally manage but do not belong to Codex's own execution core:

  1. Lifecycle Orchestration: Starting, reusing, and stopping third-party CLI processes;
  2. Envelope Protocol Normalization: Translating third-party streaming output into its own AgentResponse / Message / Content stream, making the frontend, session, and memory unaware of "who the backend is";
  3. Capability Projection: Projecting its own Skills and MCP servers into the third-party runtime, and reversely discovering the other party's own Skills / MCP in read-only mode;
  4. Security Approval: When a third-party Agent wants to modify files, execute commands, or request permissions, bridging to a unified ApprovalService for user adjudication.

None of these four items is "making code run"; all are "constraint, wiring, protection" — so it is a Harness, and the Codex / Qoder it integrates is the Runtime. Within one framework, the two words each find their proper place, and confusion naturally disappears.

4. Responsibility Breakdown: What Each Layer Does

Definitions are just the starting point. The real difference lies in the details of responsibilities.

4.1 Seven Responsibilities of Harness

As stated by Credal, Harness is responsible for the agent's execution loop and logic control, specifically including:

# Responsibility Description
1 Execution Loop (Agent Loop) Controls the interaction steps between the model and the environment (ReAct, Plan-Execute, etc.)
2 Prompt Assembly & Context Management Constructs reasonable prompts, manages conversation history and memory, effectively guides the model
3 Tool Interface Defines and exposes available tools to the model, handles tool call requests and result feedback
4 Message/State Tracking Tracks session content and task status for history persistence and task recovery
5 Output Parsing & Validation Parses model output, validates format or semantics, retries or corrects if necessary
6 Error Handling Identifies runtime errors (tool failures, timeouts, etc.), takes actions like retry, tool switching, escalation to human approval, or safe stop
7 Sub-agent Management Coordinates the creation and merging of results from multiple agents, handles collaboration and conflicts

In short, Harness is the logic layer built on top of the model, responsible for "what to think" and "how to do it." Its goal is to turn the model's reasoning ability into practical work capability useful in reality.

4.2 Six Responsibilities of Runtime

The Runtime layer focuses on infrastructure support during execution:

# Responsibility Description
1 Isolation & Sandbox Execution Each session executes in an independent isolated environment (container/micro-VM) to prevent faults or malicious behavior from propagating across sessions
2 Resource Limits Enforces limits on CPU, memory, disk, tokens (API calls), etc., to prevent infinite loops or resource abuse
3 Network & Credential Control Controls network ingress/egress, restricts accessible APIs; securely injects short-term credentials to avoid key exposure in model context
4 Persistence & Checkpointing Provides state persistence for long-running or concurrent tasks, allowing sessions to resume from checkpoints upon restart
5 Concurrency & Scalability Schedules and scales multiple sessions, manages queues and parallel execution, ensuring stable operation under high load
6 Monitoring & Audit Logging Records trace information for every model call, tool execution, and network request, supporting debugging and compliance

Simply put, Runtime is responsible for the execution environment and governance, including security, isolation, resources, and monitoring at the infrastructure level.

4.3 Responsibility Boundary: One-Sentence Summary

Infrastructure security such as "network egress control, execution sandbox, and credential management" should be left to the Runtime, while business security such as "tool call permissions and output validation" should be left to the Harness.

5. Lifecycle: From User Request to Task Completion

The lifecycle of an agent from a user request to task completion typically goes through the following steps:

  1. User initiates request → Harness receives
  2. Harness loads task instructions, context, and policies
  3. Harness calls the model to generate the next action
  4. Model requests a tool call? → Harness dispatches the call to Runtime
  5. Runtime executes the tool code or command in an isolated environment
  6. Runtime returns the result → Harness receives
  7. Harness continues the loop (may call the model again or further tools)
  8. Termination condition met? (task complete / error limit / timeout) → End
  User                    Harness                     Runtime
   |                         |                           |
   |--- Request ------------>|                           |
   |                         |--- Load context+policy   |
   |                         |--- Call model ----------->|
   |                         |<-- Model returns action --|
   |                         |                           |
   |                         |--- Need tool? ---------->|
   |                         |     Dispatch tool call   |
   |                         |                           |--- Isolated execution
   |                         |<-- Return result ---------|
   |                         |                           |
   |                         |--- Continue loop ...     |
   |                         |--- Termination met?      |
   |<-- Return final result -|                           |
   |                         |                           |

Key reading: Harness is the driver of the loop, Runtime is the contractor for tool execution. Throughout the entire lifecycle, how many times the Harness called the model and how many times the Runtime executed tools can be traced end-to-end via a trace ID.

6. Interfaces and Resource Management

6.1 Interface Form Comparison

Harness Interfaces are usually provided by specific agent frameworks or SDKs:

Runtime Interfaces are embodied in external execution entry points and management control planes:

6.2 Resource Management Division of Labor

Dimension Harness Resource Management Runtime Resource Management
Focus Resources related to model context Underlying compute resources
Token Management Tracks conversation history length and token usage, limits model call steps or cost Enforces API call token limits
CPU/Memory Not concerned Independent quota per session, e.g., AWS AgentCore allocates fixed memory and CPU in each micro-VM
Scheduling & Scaling Not concerned Scheduling and scaling across multiple sessions, distributing tasks to available nodes or newly started instances
Concern Logical correctness and context completeness Resource utilization and throughput

In short: Harness focuses on logical correctness, Runtime is the primary responsible layer for resource management.

7. Security Isolation: What Does Each Layer Manage?

7.1 Harness Security: Permissions and Guardrails at the Business Logic Level

Harness provides protection from the business logic level:

7.2 Runtime Security: Environment Isolation and System Protection

Runtime provides protection from the operating system and infrastructure level:

Protection Dimension Specific Measures
Process Isolation Each session runs in an independent sandbox (container or Firecracker micro-VM), not sharing file systems or network namespaces
Network Egress Control Only allowed domains or APIs can be accessed, preventing the agent from making arbitrary external connections
Short-Term Credential Injection Injects short-term tokens for model code use, avoiding long-term key exposure in the model context
System Hardening Regularly patches, monitors malicious behavior, provides audit logs

One-sentence summary:

Leave infrastructure security such as "network egress control, execution sandbox, and credential management" to the Runtime; leave business security such as "tool call permissions and output validation" to the Harness.

8. Extensibility and Observability

8.1 Extensibility Comparison

Harness Extension: Plugin-based Design

Modern agent platforms typically provide extensibility mechanisms, allowing developers to add new tools, skills, memory modules, and processing logic:

Runtime Extension: Environment Configuration and Images

Runtime is mainly extended through environment configuration and images:

8.2 Observability Comparison

Dimension Harness Observability Runtime Observability
Focus Upper-layer event logs Lower-layer execution and security logs
Recorded Content Each step of conversation, prompt content, model decisions, tool call requests and results Container/session startup, resource usage (CPU/memory), tool execution entry and exit, network request audits
Tracing System OpenTelemetry, e.g., OpenAI Agents SDK enables full-link tracing by default, LangSmith provides visual debugging Prometheus, CloudWatch, Azure Monitor, etc.
Correlation Method Includes user input, conversation history, memory state in logs for retrospective problem analysis Correlates Harness decisions with Runtime execution through shared trace IDs, achieving end-to-end traceability

As Credal suggests: Audit trails should correlate Harness decisions with Runtime execution, achieving end-to-end traceability through shared trace IDs.

9. Deployment Models: Three Classic Patterns

The deployment of agent systems is usually divided into a Harness layer and a Runtime layer. There are three common patterns:

Pattern 1: One Harness, One Runtime (Tight Coupling)

Application logic and execution environment are tightly coupled, with code and infrastructure managed in the same repository.

  [Harness A] <--> [Runtime A]

Pattern 2: One Harness, Multiple Runtimes (Multi-Environment)

The same application uses differently configured Runtimes in different environments (dev/test/prod).

                   --> [Runtime: Dev Sandbox]
  [Harness A] ---|--> [Runtime: Test Cluster]
                   --> [Runtime: Prod Cluster]

Pattern 3: Multiple Harnesses Sharing One Runtime (Platformization)

Multiple different business logics share a unified execution platform, facilitating unified security and monitoring management.

  [Harness A] ---<
  [Harness B] ---|--> [Unified Runtime Platform]
  [Harness C] --->

During deployment, Harness usually exists as an application service (hosted on cloud servers or in containers), communicating with the frontend via API or message queues; while Runtime may be a container cluster, a Serverless function platform, or a micro-VM managed service. For example:

10. Performance and Fault Recovery

10.1 Performance Characteristics Comparison

Dimension Harness Performance Runtime Performance
Main Influencing Factor Model inference latency and framework code complexity Underlying execution efficiency and scalability
Operation Level Application layer (Python/Node.js service) Containers, VMs, Serverless
Typical Overhead Middle layer latency (conversation management, tool call orchestration) Cold start latency, resource isolation overhead
Optimization Direction Concurrent queues, asynchronous model calls, appropriate compression for long conversations Auto-scaling, pre-warmed instances, resource utilization optimization
Bottleneck Response speed and internal logic efficiency for a single task Overall throughput and resource utilization efficiency
Scaling Method Logic optimization (better prompts, shorter tool chains) Horizontal scaling (more instances, more nodes)

In short: Harness is more concerned with the response speed and internal logic efficiency of a single task, while Runtime is more concerned with overall throughput and resource utilization efficiency.

10.2 Faults and Recovery

Harness Faults: Business-Level Failures

Common failures include: model returning format errors, tool execution errors or timeouts, policy conflicts, etc.

Fault Type Recovery Strategy
Model Output Format Error Retry with format validation failure or use a different model
Tool Call Exception Retry, switch to backup tool, request human intervention
Loop Infinite Loop/Timeout Terminate based on policy limits
Compilation Failure (Code Agent) Guide model to check errors and fix them
Network Call Failure Retry later or skip this step

A good Harness maintains business-level state snapshots and saves context upon failure for investigation and retry.

Runtime Faults: Infrastructure-Level Failures

Mainly failures at the infrastructure level, such as container crashes, host failures, network interruptions, etc.

Fault Type Recovery Strategy
Container/Micro-VM Crash Rely on persistent state to recover from the last checkpoint
Host Failure Rebuild environment on a new node, recover based on checkpoints and logs
Memory Exceeded (OOM) Terminate process within safe boundaries and report error
Network Interruption Coordinate with Harness to decide subsequent measures

Key Conclusion: Fault recovery is achieved collaboratively by both layers — Harness is responsible for business-level retries and alternative strategies, Runtime is responsible for environment-level restarts and state recovery.

11. Deep Comparison: A Panoramic Breakdown Across Seven Dimensions

Consolidate the scattered points from earlier into a seven-dimension comparison table:

Dimension Agent Harness Agent Runtime
Essential Role Constraint Layer / Policy Layer / Interface Layer Execution Layer / Platform Layer
Core Question "What should the Agent see? What can it do? Who approves? Who's accountable if wrong?" "How are tasks scheduled? How are processes started? How is state stored? How to recover if crashed?"
Key Artifacts Prompts, tool protocols, memory banks, hooks, evaluation reports, approval records Processes/threads, event loops, checkpoints, sandboxes, resource quotas
Replacement Cost Low — change personality, toolset, memory strategy, business code basically unchanged High — change scheduling model, storage engine, deployment topology, often affects the entire stack
Typical Stakeholder Agent Product Manager, Prompt Engineer, Business side SRE, Infrastructure, Platform Engineering
Change Frequency High — personality, skills, knowledge change almost daily Low — runtime is a "designed once, stable long-term" foundation
Consequence of Failure Agent becomes dumb, oversteps authority, gives irrelevant answers (Functional Error) Agent cannot run, OOM, data loss, unrecoverable (System Failure)

12. Three Places Most Prone to Error

12.1 State Management: Two Distinctly Different "States"

This is the hardest-hit area of conceptual confusion and the dimension most likely to cause mutual blame-shifting in production incidents.

Harness's state is "cognitive state," surviving across sessions. It answers "who this Agent is in the long term." Typical content: long-term memory, skill library, knowledge graph, user profile, personality settings. Its lifecycle is measured in "days/months/years," persisted in files, vector databases, Git repositories, not dependent on process survival.

Runtime's state is "execution state," surviving within a session. It answers "where this task has progressed to." Typical content: current message queue, unfinished sub-task DAG, temporary checkpoints, active sandboxes, connection pools. Its lifecycle is measured in "seconds/minutes," persisted in memory, local disk, Redis, highly dependent on process or process group survival.

The most classic accident in production happens right here: Runtime crashes, checkpoint is still there, but the Harness layer's approval records are lost — after restart, the Agent doesn't know what it just approved, so it either repeatedly applies (harassing the user) or directly executes (security incident). The reverse also happens: The Harness layer's memory bank is migrated, but the Runtime's sandbox state still points to the old path — the Agent's memory is intact but the scene is completely lost, and the user watches the Agent "amnesiac."

The root cause of such problems is never a code bug, but mixing two kinds of state in the same storage, under the same cleanup policy.

12.2 Which Layer Do Hooks Belong To?

A very error-prone point: Many people think "hooks" are Runtime things, because Runtime indeed has Pod Lifecycle Hooks, K8s init container.

The key is what event the hook is mounted on:

A counter-intuitive but extremely important example: The tool approval hook belongs to Harness, even if its implementation actually starts an asynchronous thread waiting for the user to click a button. Because the thread is just an implementation means; the hook's semantics is "is this tool call allowed" — this is a policy question, not a scheduling question.

Conclusion: To judge a hook's belonging, look at the question it answers, not how much code it uses.

12.3 Who Does the Tool Belong To?

Tools span both layers and must be disassembled to see clearly:

Tool = Tool Schema (Harness) + Tool Executor (Runtime)

Look again at QwenPaw's capabilities/ sub-package; it does bidirectional projection: projecting its own Skills and MCP servers into the third-party runtime, and reversely discovering the Provider's own Skills / MCP in read-only mode. Here, the MCP server keys are SecretStr in memory, isolated and deduplicated by fingerprint hash when projected to the third-party process, never written to disk. Governance of Schema and credentials is Harness's business; whether the third-party CLI process itself can start, and in which cwd, is Runtime's business.

13. One Diagram: Agent System Layered Panorama

Consolidate all the above dimensions into a layered view. Remember: Arrows go from bottom to top, lower layers provide services to upper layers, upper layers never modify lower layers.

+----------------------------------------------------------------+
|                    (1) Business Layer / Application Layer       |
|      Product logic, user interaction, scenario Skills,         |
|      business API orchestration                                |
+----------------------------------------------------------------+
|                    (2) Orchestration Layer / Loop              |
|   Iterative cycle of Plan -> Act -> Observe -> Evaluate -> Revise|
|   * Objective function & stop conditions * Sub-Agent delegation|
|   * Evaluator * Budget guardrails                             |
+----------------------------------------------------------------+
|                    (3) HARNESS LAYER  ** Protagonist One        |
  | Context Engineering | Tool Governance | Memory & State | Security & Evaluation |
  | * system prompt     | * Schema definition| * Long-term memory| * Permission whitelist|
  | * knowledge injection| * Selection strategy| * Workspace SoT  | * Approval hooks      |
  | * compression/trimming| * Result formatting| * Fact extraction | * Evaluation & audit  |
  | * context window    | * Capability projection| * Hybrid retrieval| * Defense in depth    |
+----------------------------------------------------------------+
|                    (4) RUNTIME LAYER  ** Protagonist Two        |
  | Process & Scheduling| Execution Sandbox| State & Checkpoint| Resources & Network  |
  | * process management| * container/micro-VM| * checkpoint    | * resource quotas     |
  | * event loop        | * credential injection| * session recovery| * retry/timeout       |
  | * concurrency isolation| * escape prevention| * persistence backend| * observability instrumentation|
  | * fault restart     | * environment image| * distributed sync| * SLO monitoring      |
+----------------------------------------------------------------+
|                    (5) Infrastructure Layer                    |
|       Compute / Storage / Network / Model Gateway /            |
|       Vector DB / Container Orchestration                      |
+----------------------------------------------------------------+

Three Key Reading Points:

  1. Loop (Orchestration Layer) is a third category; don't stuff it into the previous two. Loop decides "what to do next," which is strategy; Harness decides "what can be done in this step," which is constraint; Runtime decides "where to do this step," which is execution. The three are orthogonal.
  2. The boundary between Layer 3 and Layer 4 is the core of the entire article. A thick line, above it everything is "semantics," below it everything is "system."
  3. The boundary between the Orchestration Layer and the Harness Layer will also shift depending on the framework — some frameworks put the evaluator in Harness, some in Loop. This is not important; what is important is that you clearly draw the line in your own system.

14. Real Open-Source Framework Comparison Table

After the abstract discussion, let's land on actual projects. This table can be directly used for technology selection.

Project Primary Attribution Where It Is Strong Notes
OpenClaw / Hermes / Claude Code Harness Workspace + Skills + Long-term memory + Local Shell conventions Benchmark for personal assistant form Harness
AgentScope Java 1.1.0 Both HarnessAgent does not replace ReActAgent's reasoning loop, inserts Hooks at key loop timings Uses AbstractFilesystem to achieve "one logic, multiple deployment forms"
QwenPaw v2.1.0 harnesses/ Harness (integrating others' Runtime) Lifecycle orchestration, envelope normalization, capability projection, security approval Turns "which Agent to use for work" into configuration, not architecture
LangGraph Both State machine orchestration (Loop) + Checkpointer (Runtime) + interrupt (Harness approval) The tier with the blurriest boundaries
CrewAI / AutoGen Leaning Harness Role definition, task allocation, collaboration protocols Execution base usually handed off to external Runtime
Microsoft Agent Framework Harness create_harness_agent / AsHarnessAgent factory methods Microsoft calls Harness "runtime scaffolding"
AWS AgentCore Both InvokeHarness CLI + micro-VM managed Runtime Requires permissions on both Harness and Runtime resources
Azure Agent Service Both Prompt Agent / Hosted Agent submitted to managed environment Submits Harness logic to Runtime for execution
Google Gemini Runtime Runtime Provides environment in a managed way Google states "an agent runtime is the compute environment where the agent's application logic runs"
Devin / Codex / Trae Agent Product-level whole Harness + Runtime + UI delivered as one You don't get layers, only a black box
Erlang VM / JVM / Node.js Pure Runtime Process isolation, scheduling, GC No Harness semantics, need to build upper layers for Agent scenarios
Kubernetes Pure Runtime Orchestration, isolation, self-healing Common misconception is treating it as an Agent's Harness — it only manages "where to run," not "what to run"

Before selection, be sure to ask yourself: Do I need Harness capabilities or Runtime capabilities? If I need both, where does this project draw the boundary between the two layers?

15. Typical Use Cases

Use Case 1: Complex Multi-Step Tasks (Heavy Harness)

Tasks requiring multiple rounds of interaction, such as automated programming assistance, report generation, or data analysis, typically rely on a comprehensive Harness. Such scenarios require close coordination of conversation, context, and external tools (compilers, databases, search, etc.), emphasizing fault tolerance and long-term memory.

Typical Products: Anthropic's Claude Code, OpenAI's Codex. These are instances of code agents with powerful Harnesses. The design details of the Harness (such as fallback strategies on test failure, distributed caching, etc.) directly determine the agent's effectiveness.

Use Case 2: Lightweight Automation Tasks (Heavy Runtime)

Simple automation scenarios, such as batch customer service replies, alarm monitoring triggers, etc., may focus more on stable execution without needing too much customized conversation logic. In this case, one can mainly rely on the Runtime platform: package model calls and logic into functions or containers, and let the cloud platform handle scaling and operations.

Typical Scenario: Simple Q&A or data query agents deployed on Azure Functions or AWS Lambda, handing more tasks over to the Runtime. Here, the Harness only needs to provide the most basic prompts and exception handling, with low complexity.

Use Case 3: Enterprise Multi-Agent Scenarios (Multiple Harnesses + Shared Runtime)

Large systems that need to manage multiple agents with different purposes simultaneously usually adopt a scheme of multiple Harnesses + a shared Runtime. Different teams develop their own business logic (their respective Harnesses), while the underlying execution environment uniformly uses the same platform (shared Runtime) for unified management of security, monitoring, and resources.

This is particularly common in large enterprises, improving governance efficiency and ensuring isolation.

16. Borderlands: Five High-Frequency Confusion Scenarios

The following five scenarios are the most error-prone places in practice, with conclusions given one by one.

Scenario 1: Which Layer Does Context Compression Belong To?

Conclusion: Harness. Compression solves "which part of history the model should see." Even if the compression operation itself consumes time and CPU, requiring Runtime to provide computing resources and temporary disk space — that is borrowing Runtime capability, not changing its belonging.

Scenario 2: Which Layer Does Human-in-the-Loop Approval Belong To?

Conclusion: Cross-layer, but semantic belonging is Harness. The decision of approval is Harness's (what operations need approval, approval granularity, how to adjust after rejection), the channel of approval is Runtime's (blocking tasks, suspending coroutines, waiting for push, timeout cancellation). The correct approach is to define approval policies in the Harness layer, and only issue the atomic instruction "suspend current task until a certain event" to the Runtime.

Scenario 3: Is Checkpoint Harness or Runtime?

Conclusion: Two separate checkpoints, don't mix them. Semantic checkpoint (which step has been reached, which operations have been approved) belongs to Harness; execution checkpoint (process state, sandbox snapshot, connection pool state) belongs to Runtime. The two must be stored separately and recovered separately.

Scenario 4: Is the Agent's "Workspace Filesystem" Harness or Runtime?

Conclusion: Best practice shared by both layers. The workspace is Harness's source of truth (personality, memory, skills), but its physical implementation is infrastructure provided by Runtime. The AbstractFilesystem abstraction defines the contract: the upper Harness only programs against semantic interfaces, the lower Runtime freely chooses backend implementations. Contract is stable, implementation is replaceable.

Scenario 5: Which Layer Does MCP Server Belong To?

Conclusion: Depends on what it carries. An MCP Server that only provides tool Schema and semantic definitions is closer to Harness; an MCP Server that runs as a local resident process, holds credentials, and manages connection pools is closer to Runtime; in reality, most are hybrids. General principle: MCP does not change the layering, it just makes the layering cross process boundaries.

17. Design Practice: Five Boundary Rules That Must Be Upheld

Rule 1: Harness Does Not Touch Scheduling, Runtime Does Not Touch Semantics

The Harness layer does not write thread pools, retry policies, or container configurations. The Runtime layer does not write prompts, tool Schemas, or memory extraction logic. When Harness needs capabilities like "suspend task," it issues atomic instructions to Runtime.

Rule 2: Harness Errors Must Be "Visible"

Harness errors do not surface on their own — the Agent still returns 200, logs still look beautiful, but the result is wrong. Therefore, the Harness layer must self-build: an Evaluator (determining if the previous step moved closer to the goal), Trajectory Retention (the entire reasoning-action chain for post-hoc review), Approval and Audit Records (who approved what, based on what).

Rule 3: Separate States, Separate Lifecycles

Harness state (cognitive) and Runtime state (execution) must use different storage, different retention periods, different cleanup policies, different backup mechanisms. Checklist: Where is long-term memory stored? Where are approval records stored? Where are execution checkpoints stored? Where are sandbox snapshots stored? What are the TTL and backup strategies for each? Any cell that cannot be filled out is a rehearsal for a future accident.

Rule 4: Capabilities Should Be "Projected," Not "Copied"

When integrating third-party Agent runtimes (Codex, Qoder, Claude Code, etc.), the correct posture is projection and bridging. Capability differences must be statically declared by a Capability Registry, not caught by runtime try-catch. A matching Degradation Adapter ensures that missing optional dependencies do not break startup. "Which Agent to use for work" should become a configuration, not an architecture.

Rule 5: Loop Should Not Be Stuffed into Any Layer

Loop (orchestration cycle) is a third kind of thing. Treating Loop as Runtime will make the scheduler forever entangled in "business semantics"; treating Loop as Harness will make the cycle untestable and irreplaceable. Correct approach: Loop is an independent layer; it makes constraint requests to Harness, execution requests to Runtime, and does not implement the capabilities of either side itself.

18. A Minimal Runnable Example: Writing Layering into Code

Concepts alone are not enough; here is a minimal runnable piece of code, landing the layered structure on specific line numbers.

# ============================================================
# Layer 5: INFRASTRUCTURE  - Infrastructure (omitted here, using local resources)
# ============================================================

# ============================================================
# Layer 4: AGENT RUNTIME  ** Runtime Layer: Only cares about "running"
# ============================================================

class AgentRuntime:
    """Agent Runtime: process, scheduling, sandbox, state, resources.
    Iron rule: No prompt text, tool semantics, or memory strategies appear in this layer."""

    def __init__(self, sandbox=None, checkpoint_dir="./ckpt"):
        self.sandbox = sandbox or LocalSandbox()      # Execution sandbox
        self.checkpoint_dir = checkpoint_dir          # Execution checkpoint

    def spawn_worker(self, task_id):
        """Create an isolated execution unit. Harness is completely unaware of this method."""
        ...

    def suspend(self, task_id, reason):
        """Suspend a task, waiting for an external event to wake it up.
        Note: "Why suspend" is decided by Harness, here only responsible for "how to suspend."""
        ...

    def resume(self, task_id):
        """Resume task scene from execution checkpoint (process state, sandbox snapshot)."""
        ...

    def enforce_budget(self, task_id, tokens_used, deadline):
        """Hard constraints on resource and time budget. Semantics irrelevant."""
        ...

# ============================================================
# Layer 3: AGENT HARNESS  ** Harness Layer: Only cares about "what can be done"
# ============================================================

class AgentHarness:
    """Agent Harness: context, tool governance, memory, security, evaluation.
    Iron rule: No thread pools, retries, or process management written in this layer."""

    def __init__(self, workspace, allowed_tools, evaluator):
        self.workspace = workspace        # Single source of truth
        self.allowed_tools = allowed_tools  # Tool permission whitelist
        self.evaluator = evaluator          # Evaluator
        self.audit_log = []                 # Approval and audit records

    def build_context(self, session) -> str:
        """Context engineering: inject personality, knowledge, long-term memory, compress history if necessary."""
        system = self.workspace.read("AGENTS.md")
        memory = self.workspace.grep("MEMORY.md", session.user_id)
        history = self._compress(session.history)   # Compression is still Harness
        return system + "\n" + memory + "\n" + history

    def gate_tool_call(self, name, args) -> bool:
        """Tool governance + security approval. Semantic question, not scheduling question."""
        if name not in self.allowed_tools:
            return False
        if self._risk_level(name) == "HIGH":
            return self._request_human_approval(name, args)
        return True

    def evaluate(self, trajectory) -> str:
        """Evaluate whether this trajectory is approaching the goal. Runtime never sees semantic right or wrong."""
        return self.evaluator.score(trajectory)

    def flush_memory(self, session):
        """After run ends, extract new facts and write back to workspace. Harness's cognitive state."""
        self.workspace.append("MEMORY.md", self._extract_facts(session))

# ============================================================
# Layer 2: LOOP  ** Orchestration Layer: Only cares about "what to do next"
# ============================================================

class AgentLoop:
    """Standard loop: Plan -> Act -> Observe -> Evaluate -> Revise.
    Iron rule: Ask Harness for constraints, ask Runtime for execution, does not implement capabilities of either side itself."""

    def __init__(self, harness, runtime, goal, max_steps=8, token_budget=50_000):
        self.h, self.r = harness, runtime
        self.goal = goal
        self.max_steps = max_steps
        self.token_budget = token_budget

    def run(self, session):
        trajectory = []
        for step in range(self.max_steps):
            # (1) Context provided by Harness
            ctx = self.h.build_context(session)
            # (2) Model reasoning + tool call decision
            decision = self._think(ctx, trajectory)
            # (3) Pass through Harness gate before execution
            if not self.h.gate_tool_call(decision.tool, decision.args):
                self.r.suspend(session.task_id, "waiting_human_approval")
                self.r.resume(session.task_id)
                continue
            # (4) Real execution handed to Runtime
            observation = self.r.spawn_worker(session.task_id).execute(
                decision.tool, decision.args
            )
            # (5) Budget hard constraint enforced by Runtime
            self.r.enforce_budget(session.task_id, decision.tokens, None)
            trajectory.append(observation)
            session.history.append(observation)
            # (6) Evaluate if goal is met
            if self.h.evaluate(trajectory) == "GOAL_MET":
                break
        # (7) Wrap-up: cognitive state written back to Harness, execution state cleaned by Runtime
        self.h.flush_memory(session)
        self.h.audit_log.append({"goal": self.goal, "steps": len(trajectory)})
        return trajectory

# ============================================================
# Assembly: Two layers decoupled, independently replaceable
# ============================================================

harness = AgentHarness(workspace=Workspace("./ws"), allowed_tools={"read", "write", "grep"})
runtime = AgentRuntime(sandbox=Sandbox())                # <- Swapping to K8s is fine
loop    = AgentLoop(harness, runtime, goal="Refactor auth.py to JWT while maintaining 100% test coverage")
loop.run(session)

# Swap Harness (change personality/toolset): runtime untouched
harness2 = AgentHarness(workspace=Workspace("./ws-analyst"), allowed_tools={"read", "grep"})
# Swap Runtime (single machine -> distributed): harness untouched
runtime2 = AgentRuntime(sandbox=K8sSandbox(), checkpoint_dir="redis://ckpt")

When reading this code, pay special attention to three points:

  1. AgentRuntime contains no prompt text whatsoever, no tool semantic judgments. This is "Runtime does not touch semantics."
  2. AgentHarness.gate_tool_call internally calls self.r.suspend(...) — Harness borrows Runtime capability, but semantic belonging remains in Harness. This is the correct posture for cross-layer collaboration: borrow mechanism, do not relocate responsibility.
  3. AgentLoop is a pure glue layer. It asks Harness for context and constraints, asks Runtime for execution and budget, and does not implement the capabilities of either side itself. Loop is a third category; do not stuff it into any layer.

19. One-Sentence Closing, and a Quick Reference Card

Returning to that naming accident at the very beginning. It actually has a very elegant answer:

Harness and Runtime are not two names for the same thing, but two halves of the same thing.

Runtime enables the Agent to do things; Harness enables the Agent to do things right.

An Agent with only Runtime is a fast but chaotic robot; an Agent with only Harness is a knowledgeable but slow manual. Only when combined do they form an agent that can go live.

More precisely: Harness defines the way the agent "thinks" and "acts"; Runtime is responsible for where and how to safely execute these actions. The two complement each other and are indispensable.

Quick Reference Card (Recommended to print and post at your workstation)

  Harness = Constraint / Policy / Interface     Decides "what can be done, what is allowed to be done"
  Runtime = Execution / Platform / Environment  Decides "where to run, how fast, how to recover"
  Loop    = Orchestration / Cycle / Strategy Sequence   Decides "what to do next"

  Three Discrimination Questions:
   1. If changed, will the Agent's personality change?  -> Yes = Harness
   2. Is the output content or process?                  -> Content = Harness
   3. If deleted, will it become dumber or fail to run?  -> Dumber = Harness

  Attribution Quick Memory:
   Harness <- Context compression / Tool Schema / Long-term memory /
              Approval semantics / Evaluator / Workspace source of truth
  Runtime <- Process scheduling / Sandbox / Execution checkpoint / Resource quotas /
              Persistence backend / Monitoring & alerting
   Cross-layer <- Tool (Schema+Executor) / MCP / Workspace filesystem

  Security Division:
   Harness <- Tool call permissions / Output validation / Human approval policy
   Runtime <- Network egress control / Execution sandbox / Credential management

  Deployment Patterns:
   Pattern 1: One Harness, One Runtime (Tight coupling, startup teams)
   Pattern 2: One Harness, Multiple Runtimes (Multi-environment, dev/test/prod)
   Pattern 3: Multiple Harnesses, Shared Runtime (Platformization, large enterprises)
Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

The_Young

So 'Agent = Model + Harness' anthropomorphizes AI, implying that you just set some rules and it gets to work. Runtime, on the other hand, is saying code is still code. [lightbulb moment]