Skip to content
UHPUHPDeveloper Guide
Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

What is the Unified Harness Protocol (UHP)?

UHP is an open execution protocol for products that want to run complete agent harnesses through a consistent interface rather than integrate every harness separately.

Page reviewed 4 Oct 2026 Source and review policy

Protocol: 2026-09-28Static SSG

Direct definition

Section titled “Direct definition”

The Unified Harness Protocol (UHP) defines how a client drives a complete agent harness through a UHP server. It standardizes the execution boundary: select a configured harness, submit work, observe progress, continue related work, exchange files, cancel or delete lifecycle state, receive structured failures and collect final output.

A harness is the complete runtime around a model: agent loop, tools, skills, session state and working environment. UHP intentionally does not prescribe how that runtime is implemented internally.

The integration problem

Section titled “The integration problem”

Decide whether the execution boundary solves your problem

Section titled “Decide whether the execution boundary solves your problem”

Start from the product behavior rather than the list of supported harness names.

You need to…Boundary to evaluateWhy it matters
Submit work to interchangeable complete runtimesUHP executionThe server translates each runtime into tasks, results and continuation.
Add a tool or resource to an existing runtimeMCPTool connectivity alone does not require an outer UHP server.
Embed an agent in an editorAgent Client ProtocolThe editor needs its own interactive session and permission contract.
Call a model and manage the loop yourselfModel APIsYour application still owns tools, recovery and orchestration.

For a product evaluating UHP, prove three things with one small workflow: the server advertises the required contract, the configured harness can actually execute the task, and the client can retain a response identity through failure or continuation. A common HTTP shape does not make two harnesses equally capable or make their outputs interchangeable. Compare the evidence at each boundary before committing to a runtime.

Complete agent harnesses expose more than model completion. They maintain state, run tools, manipulate files, stream intermediate events and produce artifacts. Without a shared contract, a product needs a different adapter/lifecycle model for each harness.

Product / CLI / CI job
        │
        │  UHP over HTTP
        ▼
     UHP server
        │
        ├── Codex ─────────── tools / model provider
        ├── Claude Code ──── tools / model provider
        ├── Hermes ───────── tools / model provider
        └── other configured harnesses

Containers, subprocesses, queues and remote workers are implementation details outside the wire contract.

A concrete product workflow

Section titled “A concrete product workflow”

Imagine a product that asks an agent to inspect an uploaded report and produce a summary file. The product selects a configured harness, submits the work to its UHP server and shows progress. The server drives the chosen harness, whose own agent loop calls its tools and model provider. The product then retrieves the result and, where supported, the output artifact.

The value is the stable outer contract: the product need not implement every harness’s native event and session format. The server still needs a real adapter, provider credentials, execution permissions and storage. A different harness can produce a different answer even when both satisfy the same protocol.

For a follow-up, the client uses the protocol’s continuation semantics rather than assuming a fresh request shares the previous workspace. It discovers optional capabilities before depending on files, sharing, plugins or environments. See lifecycle and the API reference for exact request shapes; the example here is a conceptual workflow, not a fabricated endpoint transcript.

What UHP standardizes

Section titled “What UHP standardizes”
  • Protocol-version negotiation and capability discovery.
  • Harness discovery and Full-class harness lifecycle management.
  • One-shot and streaming task execution.
  • Session continuation, inspection and canonical session deletion at applicable classes.
  • Optional Full-class session sharing with publish/read/revoke semantics.
  • Cancellation and terminal task states.
  • File input, artifacts and downloads at higher classes.
  • Authentication/object scoping and a machine-readable error model.
  • In 2026-09-12, an optional Harness Plugins sub-protocol for binding Agent Plugins 1.0.0 packages to a hosted harness, including package retrieval, composition and export.
  • In 2026-09-28, optional Environments for reusable project files and dependencies mounted read-only into sessions; task selection uses metadata.environment.

The current published date-version is 2026-09-28. It is additive to 2026-09-12 and adds optional Environments: reusable project files and dependencies built once and mounted read-only into sessions.

What UHP is not

Section titled “What UHP is not”

It is not a model API. It drives a harness, not raw inference. It is not MCP. MCP standardizes a different tool/resource/context boundary. It is not a new plugin package format. UHP 2026-09-12 deliberately reuses Agent Plugins 1.0.0 for its optional Harness Plugins surface.

The current source also preserves two compatibility/lifecycle boundaries introduced in the preceding version:

  • Request-level tools and include are accepted but reserved and ignored; carried fields are reported in response.metadata.ignored_fields rather than becoming per-task capability grants.
  • The canonical session-delete operation is DELETE /v1/sessions/{session_id}. The older /v1/traces/{session_id} route may remain as a compatibility alias; clients should use the session path.

For session sharing, bodyless POST publishes, a share has a required url, DELETE on /v1/sessions/{session_id}/share revokes, and revocation reaches every link minted for the session.

For Harness Plugins, the server derives visible manifest/MCP/skill state from the package, keeps direct harness mcpServers and skills separate, and can export a configured harness as an installable Agent Plugins package with credentials omitted and omissions recorded. See Harness Plugins.

Current status

Section titled “Current status”

As of 4 October 2026, UHP remains 2026-09-28 Draft. The current conformance package is 2026.9.28.post3 with 85 executable checks: 40 Core, 9 Extended and 36 Full. UHP 2026-09-12 remains the historical release that introduced Harness Plugins; 2026-09-28 adds Environments.

HarnessRouter Community Edition’s latest stable release is v0.29.0 / 2826cf633b0588fa494da20fdf2828deacfb7e79; development main was separately checked at 360eeacb on 4 October. The released backend count is now 20. Releases after the v0.26.x Environments implementation add product/runtime behavior such as Microsoft 365 Runtime Plugins, public artifact-sharing hardening, new model catalogue coverage and four additional harness bases; they do not revise the UHP protocol version or the conformance denominator.

Historical conformance results remain revision-bounded. A provider/support matrix or backend-specific model measurement is implementation evidence, not UHP conformance.

Section titled “Read next”

Continue with architecture, Harness Plugins, conformance, UHP clients, uhp-go, HarnessRouter, and releases.

Primary sources

Section titled “Primary sources”