1. Choose a conformance class
UHP defines three cumulative conformance classes. A server declares the class it implements:
- Core — capability discovery, harness discovery, non-streaming and streaming task execution, session continuation, cancellation, and the error model.
- Extended — Core, plus file input, artifact retrieval, and session listing/inspection.
- Full — Extended, plus harness lifecycle management (create, update, delete) and session sharing.
Because each class is cumulative, Extended includes Core and Full includes Extended. Pick the lowest class your product actually needs; a client MUST NOT assume any capability above Core without checking capability discovery first.
2. Capability discovery and version negotiation
Before using anything beyond Core, read the server's capability-discovery document (defined in the Lifecycle chapter). It advertises the protocol version, the conformance class, and the features the server supports. A server MUST NOT advertise a capability it does not implement — advertising is a promise a client is allowed to trust. Negotiate the version explicitly so a future protocol revision does not silently change the contract you depend on.
3. Task submission shape
A task is submitted as a single request describing the work, the model, and which configured harness should run it. The request body carries the input, a model identifier, a reference to the harness (for example under metadata), and a flag for whether progress should stream. The response is a response object: one task in, one result out. That request/response unit is the atomic unit of work in UHP.
At a conceptual level the shape is:
- input text or structured content;
- a model selection;
- a harness reference so the server knows which agent runtime to drive;
- optional flags such as streaming.
The fields are normative in the specification's Tasks chapter; treat the names above as the conceptual roles, not a literal paste-ready payload.
4. Streaming and session continuity
When streaming is requested, progress arrives as a stream of events describing what happened — text, a tool call, a file — never how to display it. The final event carries the finished response object, including any files the agent produced.
Continuity is opt-in: to continue the same conversation, send the next request quoting the previous response id. A session is the chain of responses that share context and a working directory; it is created implicitly by the first task and extended through that reference, so one-shot clients never need to manage a session object directly.
5. Generated OpenAPI and JSON Schema
UHP publishes its machine-readable definitions per version using OpenAPI 3.1 and JSON Schema 2020-12. Those artifacts are the basis for generating typed clients and validating payloads against the exact version you target. Generate from the per-version schema rather than hand-writing request and response models; that keeps your client aligned with the normative contract as it evolves.
6. The conformance suite is the final test
“UHP conformant” means one thing: a server passes the official conformance suite for a declared class. The current suite contains 52 checks across Core (37), Extended (+8) and Full (+7), and it runs real agent tasks against a live server — not just schema inspection.
A server that passes at a class MAY describe itself as “UHP 2026-08-11 conformant” at that class. A skip is never a pass: the report separates skips from passes precisely so a green summary cannot hide unverified behavior. HarnessRouter Community Edition, the reference implementation, has published Full-class 52/52 runs (including through its Pi and DeepSeek Harness backend paths), but that is a HarnessRouter implementation fact, not a requirement that any other server behave identically.
7. Relationship to the OpenAI Responses-compatible surface
UHP's task surface is deliberately shaped like the OpenAI Responses API, and a conformant server MUST accept the documented subset of that request body and emit the documented event vocabulary. This is a compatibility decision: existing SDKs, streaming parsers and UI components work against a UHP server with no changes.
Where UHP extends the Responses surface it does so in documented, additive places — extra metadata, a small number of additional request fields, and additional object types — and never by changing the meaning of an existing field. A client that ignores every UHP extension still gets a working task.
8. HarnessRouter is a reference implementation, not the requirement
UHP is an HTTP contract. A conformant server is any server that answers the specification's requests with the specified responses; it may run agents in containers, subprocesses, a queue, or someone else's infrastructure. Nothing in the wire format requires a hosted service, an account, a licence key, or HarnessRouter Cloud.
Two known implementations keep that honest: HarnessRouter Community Edition (self-hosted reference implementation) and HarnessRouter Cloud (hosted). Building against the specification means your client works with either, and with any third implementation that passes the conformance suite. Do not assume a HarnessRouter-specific behavior is normative UHP behavior.
Related pages
Read What is UHP?, architecture, the specification guide, the HTTP API map, conformance, HarnessRouter Community Edition, and the adoption tracker.