UHP Protocol: Same Model, 2.1x Cost Difference Across Harnesses

Problem: Harness Integration Complexity and Cost Variance

MCP manages tools, A2A manages agent-to-agent communication, AG-UI manages interfaces. Now UHP (Unified Harness Protocol) manages the harness — the runtime that plans work, calls tools, manages files, and decides when a task is done. HarnessRouter's first controlled test shows that changing only the harness while keeping the model and task identical can produce a 2.1× cost difference; the cheaper combination used about 53% fewer credits. Harnesses are not thin wrappers: Codex and Claude Code may call the same model, but their instruction structures, tool usage, context management, permission models, and task-completion logic differ, directly affecting cost and latency.

Directly integrating multiple harnesses creates an explosion of integration points: 4 harnesses require 36 integration points, 5 require 45. HarnessRouter's comparison animation illustrates that with UHP the number stays at one.

What UHP Does

UHP defines an HTTP contract covering task creation, progress tracking, session management, file operations, task cancellation, and error handling. Its API shape deliberately mirrors the OpenAI Responses API so existing clients need minimal changes. The flow: product backend sends a task and a harness_id to HarnessRouter; HarnessRouter routes to the configured harness runtime; the harness streams progress and artifacts back through the router to the product.

Three core components:

Gateway — handles Responses API, harness configuration, and model keys.

Runner — manages isolated workspaces, unifies event streams, provides turn-level checkpoints.

Built-in tools — cover MCP servers, browser, database, GitHub, media, etc.

This makes agent infrastructure fully pluggable: swap Codex for Claude Code without changing product code; run the same task against multiple harnesses to compare outputs; add new harnesses as they appear.

Model Routing vs Harness Routing

Model routing happens at the inference layer — selecting which model processes the reasoning request — while the agent loop stays the same. Harness routing selects the runtime that owns the entire task lifecycle. In UHP, the model is chosen via the model field; the harness is chosen via metadata.harness_id. Both can be switched independently. As the UHP site states: a model API gives you a turn (message in, tokens out, you run tools yourself); UHP gives you a task (drop the work in, the agent uses tools, manages sessions, returns results and files). The unit of exchange is a task, not a completion.

Benchmark Results

HarnessRouter's benchmark page shows 8 harness×model configurations running the same task. Cost ranged from 223 down to 0.47 credits (99.8% difference); end-to-end latency ranged from 4m36s down to 1m25s (3.2× difference). The lowest-cost and lowest-latency combinations are not always the same and depend on the task — reinforcing that "try a different harness" should be as easy as "try a different model".

Getting Started

Run HarnessRouter with Docker:

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

Default username and password are both harnessrouter. After logging in, connect provider API keys, then select a harness in the Console to run tasks.

To integrate, generate an API key in the Console and call /v1/responses. Switching harnesses means changing metadata.harness_id:

curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
  -H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
  -H 'content-type: application/json' \
  -d '{
    "input": "Reply with exactly: it works.",
    "metadata": {"harness_id": "codex"},
    "model": "gpt-5.4-mini",
    "stream": false
  }'

Changing harness_id to hermes selects another runtime; the request body stays the same. Streaming responses use Server-Sent Events. To continue a session, pass previous_response_id. The protocol specifies 13 chapters covering architecture, lifecycle, harness configuration, plugins, environment, memory, tasks, streaming, sessions, files, errors, security, and schema. It uses OpenAPI 3.1 + JSON Schema 2020-12 and includes 98 runnable compliance tests.

Boundaries and Limitations

UHP standardizes the task lifecycle, not harness behavior. Each harness retains its own permission model, tool usage, and completion criteria. A notable limitation: a task checkpointed in one harness cannot be resumed in another mid-stream. If Codex starts a task and you want Claude Code to finish, you must start a new session and pass the context (summary, next-step instructions, files) manually. HarnessRouter isolates sessions using separate OS users and workspaces, not containers. Production deployments must evaluate the security model themselves. The protocol does not require a hosted service, accounts, or license keys; a compliant server can run entirely on your own hardware, with your own provider keys, storing data on your own volumes.

Perspective

Model routing has been a hot topic, but as model capabilities converge and personal agents rise, the focus shifts to how different agents can leverage their respective strengths and seamlessly dispatch tasks to different agent services. Tokenbank, for example, internally implements a similar agent routing protocol so that different agents specialize and collaborate — even across users. UHP simplifies such adaptation complexity. For anyone integrating agents into a product, UHP's value is clear: it prevents lock-in to a specific runtime, which is more meaningful than evaluating yet another model API.