An open standard for running complete agent harnesses as shared infrastructure.
UHP provides a universal translation layer that connects agent harnesses with applications and the modules surrounding each harness, standardizing the harness-to-application interface and unifying how skills, tools, models, context, permissions, environments, sessions, files, and artifacts connect to each harness.
Integrate once, and UHP-compatible modules, harnesses, and applications can communicate through the same shared contract. Released under the Apache 2.0 license, UHP can be freely implemented, extended, and built upon. With UHP, agent harnesses and their surrounding modules can become true plug-ins: portable, interchangeable, and reusable across applications through one unified interface.
A harness is a complete agent runtime — a loop that plans, calls tools, edits files, and reports back. Codex, Claude Code and Hermes are harnesses. Each one already knows how to do the work; what none of them agree on is how a product should drive one: how to start a task, follow its progress, continue the conversation, cancel it, get the files it produced, and understand why it failed.
Today every product answers those questions again, per harness. UHP answers them once.
your product ──▶ UHP ──▶ ┌── Codex
├── Claude Code
├── Hermes
├── DeepSeek Harness
├── Gemini CLI
├── Pi
├── ...
└── the harness that ships next
UHP is not a model API and does not replace one. Model APIs give you a turn: messages in, tokens out, tools you have to run yourself. UHP gives you a task: work in, and a running agent that uses its own tools, keeps its own session, and hands back results and files. The unit of exchange is a job, not a completion.
Specification The normative contract — 13 versioned chapters.
Conformance suite 98 runnable checks; the definition of conformant.
Implement a client Discovery, tasks, events, artifacts — over HTTP.
Implement a server The operations a server answers behind the contract.
Status of this document #
| Current version | 2026-10-04 |
| Status | Draft standard — stable enough to build on, versioned so it can change safely |
| Specification | versions/2026-10-04/ |
| Machine-readable | schema/ — OpenAPI 3.1 + JSON Schema 2020-12 |
| Conformance suite | conformance/ — runnable, and the definition of "conformant" |
| Change process | GOVERNANCE.md |
| Versioning rules | VERSIONING.md |
| License | Apache-2.0, same as the repository |
No hosted service required #
UHP is an HTTP contract. A conformant server is any server that answers the requests in this specification with the responses in this specification. It may run agents in containers, in subprocesses, on a queue, or on someone else's infrastructure. Nothing in the wire format requires a hosted service, an account, a licence key, or a call home — a conformant server can run wholly on your own machine, on your own provider keys, storing everything on a volume you own.
A client written against this specification works with any server that passes the conformance suite, whoever built it. The examples page lists the servers and clients built against UHP so far. If you find a behaviour the specification does not describe but your client depends on, that is a specification bug — please open an issue.
What the protocol covers #
| Chapter | What it defines |
|---|---|
| Architecture | Roles, conformance classes, and the object model |
| Lifecycle | Version negotiation, capability discovery, task lifecycle |
| Harnesses | Discovering, selecting and configuring a harness |
| Plugins | Packages of tools and skills, installed into a harness as one unit |
| Environments | A project's files and installed dependencies, built once and read-only in every session that names it |
| Memories | Memory that outlasts a session: a tree of memories, access per node, records, recall, providers |
| Tasks | Sending work and receiving a result |
| Streaming | Following progress as it happens |
| Sessions | Continuing a conversation, and cancelling one |
| Files | Sending files in, getting artifacts out |
| Errors | Failure taxonomy, retries and idempotency |
| Security | What an implementer must get right, collected in one place |
| Schema | The machine-readable definitions and how to use them |
Quick shape of it #
Discover what a server can run, run something, and follow it:
curl -s https://your-uhp-server/v1/harnesses -H "Authorization: Bearer $KEY"
curl -s -N https://your-uhp-server/v1/responses \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{
"input": "Summarise README.md in three bullets.",
"model": "claude-sonnet-4.6",
"metadata": { "harness_id": "chrn_…" },
"stream": true
}'
The stream is Server-Sent Events. The last event carries the finished response object, including
any files the agent produced. To continue the same conversation, send the next request with
previous_response_id set to the id you just received.
Full walk-through: Tasks.
Relationship to the OpenAI Responses API #
UHP's task surface is deliberately shaped like the OpenAI Responses API, and a conformant server MUST accept the subset of that request body described in Tasks and emit the event vocabulary described in Streaming.
This is a compatibility decision, not an accident. Products already have code that speaks Responses; existing SDKs, streaming parsers, and UI components work against a UHP server with no changes. What UHP adds is everything a harness needs and a model endpoint has no concept of: which harness runs the work, its tools and skills, the session that survives between tasks, the files that come back, and the cancellation of work that is already running.
Where UHP extends the Responses surface it does so in documented, additive places — metadata, a
small number of extra request fields, and additional object types — never by changing the meaning
of an existing field. A client that ignores every UHP extension still gets a working task.
Implementing UHP #
- Read Architecture and pick a conformance class.
- Generate types from
schema/uhp-2026-09-12.openapi.yaml. - Run the conformance suite against your server while you build:``` bash pip install -e protocol/conformance uhp-conformance --base-url https://your-server --api-key "$KEY"
4. Publish your report. A server that passes at a class MAY describe itself as
"UHP 2026-09-12 conformant ()".
Two role-specific guides walk through this in order:
[Implement a client](https://unifiedharnessprotocol.org/connecting) — discovery, task submission, event handling, and
artifact retrieval — and [Implement a server](https://unifiedharnessprotocol.org/serving) — the operations a server answers
and how it connects one or more harnesses.
## Contributing
Changes to this specification follow [`GOVERNANCE.md`](https://unifiedharnessprotocol.org/governance). The short version: propose in
prose first, and no change lands unless the specification, the reference implementation and the
conformance suite move together.
## Background
For the story behind the name, the alternatives weighed and why *Unified* won the letters UHP, see
[Background: the naming of UHP](naming).