Questions people ask first
Yes—persisted requests, approvals, recovery, and inspection are first-class. Execution can stay on your current stack; the harness owns the product runtime layer.
You gain persisted requests and sessions, approvals, restart-safe recovery, inspection, and protocol-ready serving.
The smoothest path keeps upstream semantics intact—you do not need a second framework’s mental model.
Top-line comparison
Products for people using agents directly.
Frameworks that define agent execution semantics.
The runtime product layer for operating, recovering, approving, and governing multi-agent applications.
Platform SDKs can package one provider's agent runtime for their ecosystem. agent-harness
keeps a different boundary: backend-neutral workspace assembly, YAML-owned operating policy, persisted
requests and sessions, recovery, approvals, and protocol adapters over one runtime control plane.
Product boundary
agent-harness is not a third agent framework. It is the runtime layer that turns one
workspace into one operable application runtime with a small public API, YAML-defined assembly, and
stable runtime-facing records.
- Execution frameworks own agent execution semantics.
agent-harnessowns workspace assembly, runtime lifecycle, approvals, inspection, persistence, and recovery.- If upstream already has the protocol or execution primitive, the harness should pass it through directly or adapt it losslessly.
Ownership matrix
| Area | People-facing agent products | Execution frameworks | agent-harness |
|---|---|---|---|
| Owns execution semantics | No | Yes | No, reuses upstream semantics |
| Owns approvals and operator control | Sometimes as product UX | Not as the product boundary | Yes |
| Owns persisted requests, sessions, approvals, and events | Product-specific | Not by default | Yes |
| Owns recovery and resume orchestration | Product-specific | Primitive-level capability | System-managed runtime behavior |
| Owns YAML workspace assembly | No | No | Yes |
| Owns runtime.sqlite inspection records | Product-specific | No | Yes |
| Owns ACP / A2A / AG-UI / runtime MCP serving | Sometimes as app integration | No single product-owned layer | Yes |
Execution-framework mapping
These capabilities should stay upstream-owned and be passed through or adapted without semantic drift.
| Ownership | Execution-framework features | How agent-harness handles them |
|---|---|---|
| Passed through directly | Model config, prompts, schemas, middleware, stores, checkpointers, and adapter-facing extras via passthrough |
Preserve upstream shape instead of wrapping them in a second harness semantic layer. |
| Adapted but still upstream-owned | Skills, bootstrap memory, subagents, HITL tool pauses, filesystem tooling, planning behaviors | Compile YAML into upstream middleware such as createSkillsMiddleware, createMemoryMiddleware, createSubAgentMiddleware, humanInTheLoopMiddleware, and createFilesystemMiddleware. |
| Harness-operated around execution frameworks | Workspace compilation, routing, persisted projections, queueing, recovery, maintenance, MCP bridge / tool export | Operate product runtime lifecycle around upstream execution semantics. |
What stays upstream
Execution frameworks keep execution semantics. The harness should pass those concepts through or adapt them losslessly instead of inventing a second protocol.
- Model config, response format, context schema, middleware, store, and checkpointer stay upstream-shaped.
- Subagents, tool pauses, summarization, provider-native tools, and MCP tool usage remain upstream execution concerns.
- The harness operates around them: workspace assembly, routing, persistence, approvals, inspection, queueing, and recovery.
Runtime record rule
Product-facing runtime state should live in harness-persisted structured records, not in backend
checkpoints. That is why inspection centers on requests, sessions,
approvals, events, and artifacts rather than raw checkpoint state.
runtime.sqlitestores harness-persisted runtime records.checkpoints.jsonstores backend checkpoint state used for resume and recovery.- Backend replacement must not require redefining the product runtime record model.
Decision filter
Before adding a new harness abstraction, ask these questions in order:
- Does the execution framework already provide this capability?
- If yes, can the runtime pass it through directly?
- If not directly, can the runtime adapt it in YAML while preserving upstream semantics?
- Is the remaining problem truly runtime-owned rather than execution-owned?
Only if the answer to the last question is yes should the feature become harness-operated behavior.
When to use it
You need approvals, restart recovery, queueing, inspectable request records, and a stable runtime contract.
You only need one short-lived agent call with no approvals, no persistence, and no operational control surface.