UHP vs model APIs

Two layers, not one

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

A direct model API is the rightmost arrow: it generates tokens for one turn. 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: you send one turn (or a short conversation window) and get back generated tokens. 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.
• What you don't get: a standard way to run an agent loop, manage a working directory or files, choose among multiple harnesses, track a long-running task lifecycle, cancel work, or verify behavior across implementations. Each provider solves — or omits — these differently.

The OpenAI Responses API (POST /responses) is the concrete shape UHP reuses for its task surface; other model providers expose analogous turn-level 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 — cross-harness continuity with a working directory, files and downloadable artifacts.
• 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

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:

• 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.