Getting started with UHP

Note

Scope: UHP is an HTTP contract for driving complete agent harnesses through one interface. The normative authority is the official specification; this page summarizes the minimum implementation path and links to primary sources.

First workflow: prove one task before adding optional features

You need a reachable UHP server, a bearer token for authenticated operations and a configured harness that can run the work. Discovery itself is public. A backend name or an installed CLI alone does not provide a configured harness ID.

1. DiscoverRead capabilities
2. NegotiateSelect a version
3. SubmitRetain task identity
4. InspectProve terminal state

Discover → negotiate → submit → inspect. Each step establishes a different part of the integration; acceptance is not completion.

1. Read GET /v1/uhp. Check protocol: "uhp", a non-empty versions array, default_version within it and the capabilities your workflow needs. Treat absent capability keys as false.
2. Send a supported UHP-Version on subsequent requests and read the version returned, including on errors. An unsupported version returns 400 / unsupported_protocol_version; do not silently retry with another contract.
3. Select a configured harness in your own scope. Submit a short, non-destructive task through POST /v1/responses, initially without streaming or optional plugins/environments.
4. Save the response ID and inspect status, output, errors and response metadata. Only completed means the harness finished; incomplete means a budget stopped it. Follow the lifecycle before deciding whether to continue.

{
  "input": "Describe the intended task in one sentence.",
  "metadata": { "harness_id": "REPLACE_WITH_CONFIGURED_HARNESS_ID" },
  "stream": false
}

This is an illustrative request shape, not a runnable harness ID or a live-tested execution. Replace the ID with an authorized configured harness; choose a model only after model discovery. A client that omits the model must still inspect any reported substitution.

Diagnose the first failure

Observation	Next action
Discovery is not a UHP document	Verify the server URL and route; do not send credentials to a lookalike.
404 / harness_not_found	Check configured-harness identity and caller scope; the CLI family name is insufficient.
409 / session_busy	Wait for the existing task’s terminal result before continuing the same session.
422 / model_unavailable	Recheck the selected harness/model combination instead of changing it invisibly.
Network fails after submission	Inspect any known response ID and advertised idempotency support before resubmitting potentially effectful work.

The versioned lifecycle and task contract define these checks. This guide’s diagnosis table connects those rules into a client workflow.

1. Choose a conformance class

UHP defines three cumulative conformance classes:

• Core — discovery, harness discovery, task execution/streaming, continuation, cancellation, error behavior and reserved request-field handling.
• Extended — Core plus file input, artifacts and session listing/inspection.
• Full — Extended plus harness lifecycle management, canonical session deletion, optional session sharing where advertised, and capability-gated Harness Plugins behavior when the server advertises that surface.

Pick the lowest class your product actually needs. A client MUST NOT assume capabilities above Core without discovery.

2. Capability discovery and version negotiation

Read GET /v1/uhp before using optional/higher-class surfaces. It advertises supported versions, the server default, conformance class and capability booleans. Negotiate with UHP-Version; unsupported versions fail explicitly rather than being silently substituted.

For UHP 2026-09-28, optional capabilities include Harness Plugins and Environments. A plugin-capable server advertises plugins plus supported plugin_schemas; an Environment-capable server advertises environments. Clients must discover optional surfaces instead of assuming them.

3. Submit a task

The normative task surface is POST /v1/responses. A request supplies input, model, harness selection, streaming preference and optional continuation/budget fields. Current source accepts Responses-compatible tools and include, but they are reserved and ignored; carried reserved fields are reported in response.metadata.ignored_fields.

Caution

Treat the versioned specification and generated OpenAPI as endpoint authority. UHP task execution is under /v1/responses*; a convenience guide or implementation-specific route does not override the versioned contract.

4. Sessions, sharing and deletion

Continuation uses previous_response_id. The session preserves conversational context, working-directory state and the configured harness.

For optional Full-class sharing, bodyless POST /v1/sessions/{session_id}/share publishes, GET reads the share object, and DELETE on the same path revokes every minted link. The share object has a required url.

The protocol-named Full-class session-delete path is:

DELETE /v1/sessions/{session_id}

The server must cancel in-flight work first, remove stored transcript/trace/working-folder state, stop deleted state counting toward enforced storage/memory allowances, return 2xx, and make a later GET /v1/sessions/{session_id} return 404. The older /v1/traces/{session_id} path may remain as a compatibility alias; clients should use the session path.

5. Decide whether you need Harness Plugins

UHP 2026-09-12 adds the optional Harness Plugins sub-protocol. A plugin is an Agent Plugins 1.0.0 package with root plugin.json, optional mcp.json and optional skills.

If you implement the capability:

• accept the package rather than inventing a second UHP package format;
• derive manifest, mcpServers, skills and skipped from package contents;
• keep direct harness MCP servers/skills separate from plugin-derived components;
• support the package-file and harness-export surfaces;
• materialize stdio MCP processes inside the agent sandbox;
• omit credentials from exports and record omissions;
• advertise plugins and plugin_schemas truthfully.

Read Harness Plugins before implementing the P-series surface.

6. Decide whether you need Environments

UHP 2026-09-28 adds optional Environments for reusable project files and dependencies built into versions and mounted read-only into sessions. Task selection uses metadata.environment; the harness/session objects retain their documented environment fields. Read Environments before implementing this capability.

7. Generate from the OpenAPI and JSON Schema

UHP publishes per-version OpenAPI 3.1 and JSON Schema 2020-12 artifacts. Generate typed clients/models from the versioned schema rather than hand-copying shapes. The 2026-09-28 artifacts include the current plugin and Environment surfaces.

8. Conformance is the final test

Current upstream main contains 85 executable checks under package 2026.9.28.post3:

• Core: 40
• Extended: 9
• Full: 36
• Total registry: 85

Harness Plugins and Environments checks are capability-gated where the specification defines them as optional. Historical results remain tied to the suite revision that produced them; do not relabel an older 64/64, 74/74, 75/75, 76/76 or 84/84 run as an 85/85 result.

9. Responses compatibility is not semantic identity

UHP intentionally resembles the OpenAI Responses wire shape, but that does not import every Responses semantic. Task-level tools and include are reserved/ignored rather than capability grants. Configure direct tool/MCP authority on the harness or install an authorized plugin at the harness configuration layer.

10. HarnessRouter is the reference implementation, not the requirement

A conformant UHP server may use containers, subprocesses, queues or remote workers internally. HarnessRouter Community Edition’s latest stable release is v0.29.1 / d257219281ef3b5a113fe8d8f2550ae0d12be320; development main was separately checked at the same d2572192 commit on 4 October. The released backend set remains 20: Kilo CLI, MiniMax Code, Grok Build and Agent Zero were added in v0.29.0, while v0.29.1 fixes relay streaming/upstream liveness without changing UHP or conformance.

HarnessRouter’s Runtime Plugins, provider/model catalogue, support matrices and backend adapters are implementation behavior. They are not requirements for another UHP server and are not proof of native UHP adoption by upstream harness or model vendors.

Evaluate a backend against the work it must preserve

When evaluating HarnessRouter, start with a configured harness you can operate and observe. Backend names alone do not tell you whether follow-up context, tools or provider behavior match your workload.

Evaluation question	Integration guide	What to inspect before choosing
Will an in-process coding driver fit a tool-constrained workflow?	Aider	Driver limits, shell-command policy, persistence and the adapter’s MCP bridge.
Does the runtime preserve failure and resume evidence?	Goose	Adapter pin, continuation behavior and the distinction between upstream ACP support and UHP integration.
Which Kimi product and session contract does the adapter actually use?	Kimi Code CLI	The replacement of the predecessor CLI, checkpoint behavior, tool policy and model/provider normalization.
Can the integration preserve the behavior tested for the pinned runtime?	Oh My Pi	Upstream release versus adapter pin, native execution surfaces and the scope of historical measurements.

Use a small task representative of your own tools and provider after reading those constraints. A published adapter test is useful prior evidence, but it does not verify your credentials, deployment or workload.

Related pages

Read What is UHP?, architecture, specification, Harness Plugins, HTTP API map, conformance, HarnessRouter, uhp-go and adoption.

Primary sources

• Official UHP site
• Current UHP protocol
• UHP 2026-09-28 specification
• UHP Environments
• UHP Harness Plugins
• Current conformance suite
• Current conformance package metadata
• HarnessRouter v0.29.1
• PR #381 — relay streaming and upstream liveness
• HarnessRouter v0.29.0
• PR #373 — four new harness bases
• PR #331 — Environment task override