Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

UHP vs model APIs

A direct model API is a model-level turn interface. UHP is an execution contract around a complete agent harness. This page separates the two and explains the current relationship between UHP's task surface and the OpenAI Responses-compatible shape.

Page reviewed 4 Oct 2026 Source and review policy

Protocol: 2026-09-28Static SSG

Compare the actual operation, not the endpoint spelling

Modern provider APIs can expose hosted tools, stored responses, background work and cancellation. The current OpenAI Responses reference, reopened 4 October 2026, is therefore broader than a bare token-completion endpoint. Its provider-specific features still differ from UHP 2026-09-28 Draft’s cross-harness execution contract.

Product requirement	Direct provider API	UHP
Use provider-native inference/tools	Follow that provider’s documented model and tool contract	Harness decides the underlying provider/tool configuration
Switch between complete coding harnesses	Build/operate those runtime integrations yourself	Address configured harnesses through the execution API
Continue workspace-based work	Provider sandbox/file semantics where offered	Same-configured-harness session/workspace lifecycle
Port a Responses-shaped client	Verify every used field and operation	Reserved request `tools` and `include` are ignored, not provider tool configuration

For example, a request using a provider’s web-search tool cannot be copied to a UHP server and assumed to activate web search. Configure the equivalent capability on the selected harness, inspect discovery, and check returned metadata.ignored_fields. Conversely, a provider file identifier is not a UHP session-file path.

Before redirecting an SDK’s base URL, inventory the calls it makes: creation, retrieval, streaming, cancellation and file access. Test each against the UHP API map rather than treating a successful first request as feature equivalence. This comparison establishes contracts, not OpenAI endorsement or an executed compatibility test.

Two layers, not one

┌──────────┐    UHP / HTTP    ┌──────────┐   internal mechanism   ┌──────────┐
│  Client  │ ───────────────▶ │  Server  │ ─────────────────────▶ │ Harness  │ ──▶ model API
└──────────┘                  └──────────┘                        └──────────┘

A direct model API is the rightmost arrow: it provides inference and any provider-defined hosted capabilities. UHP is the contract that wraps everything to its left — a client asks a server to run a complete harness, and the harness itself still calls a model provider underneath. UHP standardizes the layer around the agent runtime; it does not replace the model API.

Direct model APIs (the inference interface)

A model API lets you call a model provider directly for generation and supported provider-hosted operations. The request shape, sampling parameters and streaming format are defined by the provider.

What you address: a model and the tools that model can call.
Parameters: provider-defined — for example model, temperature, top_p, max_output_tokens, tools, instructions, and a provider-specific conversation handle such as previous_response_id.
What you get: token generation, tool/function calling, multimodal input and structured output — at the model level.
Portability limit: provider-hosted tools, files, background work and cancellation follow that provider’s contract. They are not a common complete-harness interface spanning separately configured runtimes.

The OpenAI Responses API (POST /responses) is the concrete shape UHP reuses for its task surface; other model providers expose their own inference and hosted-operation interfaces.

UHP (the harness execution contract)

In UHP’s three-role model, the client speaks only UHP, the server implements the spec and drives the harness, and harness execution (containers, subprocess, queues, workers) is implementation-defined and out of scope for the client. On top of the underlying inference call, UHP adds:

Harness selection and configuration — metadata.harness_id and harness-scoped config let one client request target Codex, Claude Code, Hermes, Pi, DeepSeek Harness, or others, without the client knowing which harness runs.
Agent task lifecycle — submit, poll or stream, cancel, retrieve and list, with explicit terminal events and status codes.
Sessions and workspaces — continuity within the same configured harness, with a working directory, files and downloadable artifacts. A continuation naming a different configured harness fails with harness_mismatch; UHP does not promise transparent migration of a live session between harnesses.
Capability discovery — GET /v1/uhp lets clients adapt to advertised features and protocol version.
Uniform behavior — a single error envelope with closed codes and retry rules, a sequence-numbered event stream, idempotency, date-based versioning, and a conformance suite so behavior is verifiable across servers.

Architectural comparison

Dimension	Direct model API	UHP
Addressable unit	A model and its tools	A configured harness and a task
Calling convention	Provider-defined endpoint and fields	`POST /v1/responses` (Responses-compatible) plus UHP lifecycle endpoints
Model selection	Provider-native model id	Canonical model id resolved by the server to a concrete provider model
Agent loop / harness	Not specified; provider-specific	Harness selected via metadata; the loop is harness-internal
Tool and function semantics	Provider-defined, per the model service	Harness-defined tools and MCP, surfaced through UHP events
Session continuity	Provider-specific handle (for example `previous_response_id`)	Same-configured-harness sessions with working directory and files
Progress and cancellation	Provider streaming; cancellation varies	UHP SSE with `sequence_number`, defined terminal events, documented cancellation
Files and artifacts	Provider file store or sandbox	Session workspace, artifacts and download
Errors	Provider error model	Single envelope, closed codes, retry rules
Discovery, versioning, conformance	Provider-specific; no cross-implementation standard	`GET /v1/uhp`, date versioning, conformance suite

The Responses-compatible task surface

UHP’s task surface is deliberately Responses-compatible. The request and response shapes — input and output items (input_text, input_file, input_image, message, reasoning, function_call), previous_response_id, instructions, tools, store and stream — follow the OpenAI Responses API, so a Responses SDK can be pointed at a UHP server with minimal change.

The extension point is metadata.harness_id plus harness-scoped configuration: that is how a compatible request selects which harness runs. Compatibility is a matter of interface shape only, and it is important to keep three boundaries straight:

Compatibility limit, checked 4 October 2026: current UHP reserves and ignores request-level tools and include, reporting carried reserved fields in metadata.ignored_fields. A Responses-shaped request is therefore not evidence of identical tool semantics. Configure tools on the harness, and discover optional UHP capabilities before using them. See the HTTP API map and task contract.

OpenAI owns the Responses API and has not endorsed, adopted, or participated in UHP.
A compatible shape does not imply native UHP adoption by OpenAI.
A UHP server does not require OpenAI models or OpenAI infrastructure. The same request runs against any configured harness.

What UHP does not require

Not OpenAI models, not OpenAI infrastructure, and not the OpenAI SDK — though a Responses SDK can be reused for the task surface.
Not a specific harness; the server chooses how execution happens.
Not any change to how a harness calls its underlying model provider.

Primary sources

Related: independent UHP clients are catalogued on UHP clients; editor/UI-to-agent integration is compared in UHP vs ACP.