Architecture
Unified Harness Protocol architecture
The core UHP boundary is simple: a client speaks UHP to a server; the server drives one or more complete harnesses behind that interface. UHP 2026-09-12 adds optional Agent Plugins packages inside configured harnesses.
The three roles
Section titled “The three roles”┌──────────┐ UHP / HTTP ┌──────────┐ internal mechanism ┌──────────┐│ Client │ ───────────────▶ │ Server │ ────────────────────▶ │ Harness │└──────────┘ └──────────┘ └──────────┘Client: the product backend, CLI, CI job or another agent that requests work. A conforming client should not need to know how the server launches a harness.
Server: the protocol implementation. It accepts tasks, drives harnesses and translates execution into UHP objects, events and errors.
Harness: the full runtime with its own agent loop, tools and session state. UHP identifies harness families by stable bases such as codex, claude-code and hermes. A harness still calls a model provider underneath UHP; for how the UHP contract relates to a direct model API such as the OpenAI Responses API, see UHP vs model APIs.
Configured harnesses
Section titled “Configured harnesses”UHP treats configuration as a first-class object rather than assuming that a base name fully defines behavior. A configured harness can combine a base with a default model, instructions, tool restrictions, skills, MCP servers, execution budgets and, in UHP 2026-09-12, optional Harness Plugins.
A Harness Plugin is an Agent Plugins 1.0.0 package bound to that configured harness. The package can contribute skills and MCP servers without rewriting the harness’s direct skills or mcpServers fields. See Harness Plugins for the derivation, composition, stdio-MCP and export rules.
The server assigns each configured harness an id that clients use when submitting work.
Object model
Section titled “Object model”| Object | Purpose | Typical lifetime |
|---|---|---|
| Harness | Saved configured runtime, including optional plugin bindings | Until deleted |
| Response | One atomic task and its result | Server retention policy |
| Session | Chain of responses sharing context and workspace | Until deleted/expired |
| Container | File namespace for a session | With session |
| File | Input or artifact in a container | With container |
| Event | Progress fact in the event stream | Streamed and replayable |
Plugin packages are configuration attached to a harness rather than a replacement for these task/session objects. The server derives plugin manifest/MCP/skill state from the package and combines enabled plugin components with direct harness components at execution time.
Sessions are implicit
Section titled “Sessions are implicit”A first task can create a session automatically. Continuation uses the prior response relationship rather than requiring every client to create a session object before doing any work. A session preserves conversational context, working-directory state and the selected configured harness across tasks.
The specification requires a mismatch to fail rather than silently switching to a different configured harness inside the same conversation chain.
Transport and streaming
Section titled “Transport and streaming”UHP uses HTTP/1.1 or later. TLS is required outside loopback development. Normal request and response bodies use JSON; file upload uses multipart form data; downloads use the file media type. Streaming uses Server-Sent Events (SSE).
This choice keeps the client-facing contract web-native while leaving the server free to run local CLIs, containers or remote execution internally.
Conformance classes
Section titled “Conformance classes”| Class | Required surface |
|---|---|
| Core | Discovery, harness discovery, task execution, streaming, continuation, cancellation and errors. |
| Extended | Core plus file input, artifacts and session listing/inspection. |
| Full | Extended plus harness create/update/delete, session sharing and capability-gated Harness Plugins checks when the server advertises that optional surface. |
Clients are expected to discover capabilities rather than assume everything above Core exists. A 2026-09-12 server can remain conformant while reporting plugins: false; the plugin-specific P-series checks then skip rather than pass.
Security boundary
Section titled “Security boundary”Clients authenticate with bearer tokens. UHP requires every object to be scoped to the principal that created it. Cross-principal attempts to read or manipulate another party’s objects should return 404 rather than disclose whether an id exists.
Plugins add another execution boundary: packaged stdio MCP processes execute inside the agent sandbox, and exported packages omit credentials while recording those omissions. See security and Harness Plugins.