Unified Harness Protocol — specification 2026-09-28
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 | Plugins | Packages of tools and skills, in the Agent Plugins format, installed into a harness; composition; export |
| 5 | Environments | A project's files and installed dependencies, built once, read-only in every session that names it; builds, versions, attachment |
| 6 | Tasks | Running work, the response object, model substitution, idempotency |
| 7 | Streaming | The event vocabulary, ordering guarantees, reconnection |
| 8 | Sessions | Continuing, inspecting, cancelling, sharing, deleting |
| 9 | Files | File input, artifacts, download, retention and scope |
| 10 | Errors | The error envelope, codes, retry rules, timeouts |
| 11 | Security | Credentials, object scope, artifacts, injection, exhaustion, plugins, environments, error hygiene |
| 12 | 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 |
GET |
/v1/harnesses/{id}/skills/{name}/files |
Full | Harnesses |
GET |
/v1/harnesses/{id}/plugins/{name}/files |
Full, plugins |
Plugins |
GET |
/v1/harnesses/{id}/plugin |
Full, plugins |
Plugins |
POST |
/v1/sessions/{id}/share |
Full | Sessions |
GET |
/v1/sessions/{id}/share |
Full | Sessions |
DELETE |
/v1/sessions/{id} |
Full | Sessions |
DELETE |
/v1/traces/{id} |
Full | Sessions (older path, same operation) |
GET |
/v1/environments |
Full, capability environments |
Environments |
POST |
/v1/environments |
Full, capability environments |
Environments |
GET PUT DELETE |
/v1/environments/{id} |
Full, capability environments |
Environments |
GET |
/v1/environments/{id}/files |
Full, capability environments |
Environments |
GET PUT DELETE |
/v1/environments/{id}/files/{path} |
Full, capability environments |
Environments |
POST |
/v1/environments/{id}/directories |
Full, capability environments |
Environments |
POST |
/v1/environments/{id}/import |
Full, capability environments |
Environments |
POST |
/v1/environments/{id}/build |
Full, capability environments |
Environments |
GET |
/v1/environments/{id}/builds/{version} |
Full, capability environments |
Environments |
GET |
/v1/environments/{id}/versions |
Full, capability environments |
Environments |
POST |
/v1/environments/{id}/versions/{version}/activate |
Full, capability environments |
Environments |
GET |
/v1/environments/{id}/harnesses |
Full, capability environments |
Environments |
The plugins column entries are served only by a server whose discovery document reports the
plugins capability; the capability is optional at every class.
What changed in this version
This version is additive to 2026-08-11: every request and object that was valid then is valid
now, and a client written against the previous version keeps working against a server that serves
this one. It adds the Plugins chapter, with stdio MCP servers inside plugins, the
plugins capability, and five error codes. A server may serve both versions from one code path. The changelog has the full list.
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.