Unified Harness Protocol — specification 2026-08-11
An open standard for running complete agent harnesses as shared infrastructure.
This is the normative specification. For an introduction to what UHP is and why it exists, start at the protocol README.
Chapters
| # | Chapter | Defines |
|---|---|---|
| 1 | Architecture | Roles, conformance classes, object model, transport, authentication, design principles |
| 2 | Lifecycle | Version negotiation, capability discovery, task and session states, concurrency |
| 3 | Harnesses | Discovering, selecting, configuring and managing harnesses; models and availability |
| 4 | Tasks | Running work, the response object, model substitution, idempotency |
| 5 | Streaming | The event vocabulary, ordering guarantees, reconnection |
| 6 | Sessions | Continuing, inspecting, cancelling, sharing, deleting |
| 7 | Files | File input, artifacts, download, retention and scope |
| 8 | Errors | The error envelope, codes, retry rules, timeouts |
| 9 | Security | Credentials, object scope, artifacts, injection, exhaustion, error hygiene |
| 10 | Schema | Machine-readable definitions and how to generate from them |
Endpoint summary
| Method | Path | Class | Chapter |
|---|---|---|---|
GET |
/v1/uhp |
Core | Lifecycle |
GET |
/v1/harnesses |
Core | Harnesses |
GET |
/v1/harnesses/{id} |
Core | Harnesses |
GET |
/v1/models |
Core | Harnesses |
GET |
/v1/harnesses/{id}/models |
Core | Harnesses |
POST |
/v1/responses |
Core | Tasks |
GET |
/v1/responses/{id} |
Core | Tasks |
GET |
/v1/responses/{id}/input_items |
Core | Tasks |
POST |
/v1/responses/{id}/cancel |
Core | Sessions |
DELETE |
/v1/responses/{id} |
Core | Tasks |
POST |
/v1/sessions/{id}/cancel |
Core | Sessions |
GET |
/v1/sessions |
Extended | Sessions |
GET |
/v1/sessions/{id} |
Extended | Sessions |
GET |
/v1/sessions/{id}/turns |
Extended | Sessions |
POST |
/v1/files |
Extended | Files |
GET |
/v1/sessions/{id}/files |
Extended | Files |
GET |
/v1/sessions/{id}/files/archive |
Extended | Files |
GET |
/v1/containers/{cid}/files/{fid}/content |
Extended | Files |
GET |
/v1/containers/{cid}/files/{fid}/pdf |
Extended | Files |
POST |
/v1/harnesses |
Full | Harnesses |
PUT |
/v1/harnesses/{id} |
Full | Harnesses |
DELETE |
/v1/harnesses/{id} |
Full | Harnesses |
POST |
/v1/sessions/{id}/share |
Full | Sessions |
GET |
/v1/sessions/{id}/share |
Full | Sessions |
DELETE |
/v1/traces/{id} |
Full | Sessions |
Conformance
A server is conformant at a class when it passes the conformance suite at that class. Nothing else is a conformance claim — not a self-assessment, not an implementation of the endpoints, not passing "most" tests.
pip install -e protocol/conformance
uhp-conformance --base-url https://your-server --api-key "$KEY" --class extended
The suite is part of this specification. If the suite and this prose disagree, that is a bug in one of them and MUST be resolved by changing whichever is wrong — never by leaving them inconsistent.
Conventions
- MUST / SHOULD / MAY are used as defined in RFC 2119 and RFC 8174.
- JSON examples are illustrative; the schema is authoritative for structure.
- Field names are
snake_caseon the task surface (inherited from the Responses-compatible shape) andcamelCaseon the harness object. This inconsistency is real, is called out here rather than hidden, and is retained because changing either would break existing clients for cosmetic gain. A future major version SHOULD unify them.