跪拜 Guibai
← All articles
Java · GitHub · Backend

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

By Cosolar ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Mixing Harness and Runtime responsibilities is the root cause of production agent failures — Runtime crashes that lose Harness approval records, or memory migrations that orphan sandbox state. A clean boundary between the two layers turns "which agent to use" into a configuration choice rather than an architectural rewrite.

Summary

The AI agent community is split over whether the engineering layer around a model is a Harness or a Runtime. Harness inherits from automotive wiring and test fixtures — it constrains, connects, and protects without generating behavior itself. Runtime inherits from JVMs and containers — it makes code actually execute. The distinction is not academic: mixing cognitive state with execution state is the root cause of the most common production incidents, where a Runtime crash loses Harness-layer approval records and the agent either harasses users or executes unsafe actions after restart.

A three-question test cuts through any framework: does changing this module alter the agent's personality? Is its output content or a process? Does deleting it make the agent dumber or just unable to run? QwenPaw's `harnesses/` sub-package passes this test cleanly — it orchestrates lifecycle, normalizes envelopes, projects capabilities, and gates security for third-party runtimes without ever touching process management. The article maps seven dimensions of difference, three deployment patterns, and five boundary rules, then closes with a runnable Python example where `AgentRuntime` contains zero prompt text and `AgentHarness` borrows suspension from Runtime without relocating the semantic responsibility.

Takeaways
— Harness is a replaceable policy layer that governs what an agent sees, which tools it can call, who must approve actions, and how it remembers; Runtime is a replaceable execution layer that manages processes, sandboxes, resource quotas, and checkpoint recovery.
— A three-question test discriminates any module: changing it alters personality → Harness; its output is content → Harness; deleting it makes the agent dumber or more dangerous → Harness. If it only affects performance, stability, or deployability, it is Runtime.
— Cognitive state (long-term memory, personality, skill libraries) belongs to Harness and survives across sessions; execution state (message queues, active sandboxes, connection pools) belongs to Runtime and lives only within a session. Mixing them in the same storage causes the most common production incidents.
— Tool approval hooks are Harness even when they spawn threads, because the question they answer is "is this call allowed?" — a policy question, not a scheduling question.
— Tools split cleanly: Harness owns the JSON Schema, selection strategy, result formatting, and permission whitelist; Runtime owns the actual process execution, concurrency control, sandbox isolation, and credential injection.
— The orchestration Loop (Plan → Act → Observe → Evaluate → Revise) is a third, independent layer — it requests constraints from Harness and execution from Runtime, implementing neither.
— Three deployment patterns cover most cases: one Harness per Runtime for startups, one Harness with multiple Runtimes for multi-environment setups, and multiple Harnesses sharing one Runtime platform for large enterprises.
— Five boundary rules: Harness never writes thread pools or container configs; Runtime never writes prompts or tool schemas; Harness errors must be surfaced by evaluators and audit trails; states must use separate storage and lifecycles; third-party runtime integration uses capability projection, not copying.
Conclusions

The naming war is not a knowledge gap but a packaging problem — modern frameworks like LangGraph ship both layers in one install, forcing developers to describe two things with one word.

The word Harness spread faster than Runtime in blog titles because it carries more "engineering craftsmanship" connotation, creating a semantic gravity that pulls all outer-layer engineering under its umbrella.

The most dangerous production failure pattern is asymmetric: Runtime crashes lose Harness approval records, but Harness memory migrations orphan Runtime sandbox state. Both failures look like "the agent forgot something" but have opposite root causes.

QwenPaw's `harnesses/` sub-package is misnamed by its own docstring as "runtime integrations" — it actually performs pure Harness duties (lifecycle orchestration, envelope normalization, capability projection, security approval) on top of third-party Runtimes, proving the terminology confusion exists even inside well-engineered projects.

The Loop layer is widely unrecognized as a distinct third category; stuffing it into Harness makes it untestable, stuffing it into Runtime entangles the scheduler in business semantics.

Concepts & terms
Agent Harness
The software layer above a base model that organizes agent behavior — prompt engineering, tool interfaces, execution loops, memory, and policies. It is a replaceable policy layer; swapping it changes the agent's personality, permissions, and work methodology.
Agent Runtime
The infrastructure layer providing the actual execution environment for an agent, similar to a cloud function or container. It manages process isolation, resource quotas, network egress, credential injection, checkpointing, and concurrency. Swapping it changes stability and deployability but not the agent's personality.
Harness Engineering
A new discipline studying how to build the engineering skeleton around a model — structured context, constraining tool protocols, lifecycle hooks, recoverable state, and observable evaluation — to make probabilistic, drift-prone model capabilities usable and controllable.
Capability Projection
The pattern of exposing one's own Skills and MCP servers into a third-party runtime while read-only discovering the other party's capabilities, with credential isolation via fingerprint hashing. It turns "which agent to use" into a configuration choice rather than an architectural dependency.
Agent Loop (Orchestration Layer)
A distinct third layer that runs the Plan → Act → Observe → Evaluate → Revise cycle. It requests constraints from the Harness and execution from the Runtime, implementing neither layer's capabilities itself. It is orthogonal to both Harness and Runtime.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗