Unified Harness Protocol

Tasks

Unified Harness Protocol, version 2026-10-19

A task is one unit of work: input in, a result out. It is the endpoint most clients spend all their time in.

1. Run a task

POST /v1/responses
Authorization: Bearer <token>
Content-Type: application/json
{
  "input": "Summarise README.md in three bullets.",
  "model": "claude-sonnet-4.6",
  "metadata": { "harness_id": "chrn_08dae611630d467ab3e67ed792570ae5" },
  "stream": true
}

1.1 Request fields

Field Type Required Meaning
input string | item[] yes The work. A bare string is shorthand for one user message. See §2.
model string no Canonical model id. Omitted means the harness's default.
metadata object no Client metadata. harness_id selects the configured harness (§1.2). memory names one more memory this task works with, on a server with the memories capability (Memories §9).
stream boolean no true streams Server-Sent Events; default false returns one JSON object.
previous_response_id string no Continue the session that produced that response. See Sessions.
branch boolean no With true, start a new session from the end of the response named in previous_response_id, leaving its session as it was (Sessions §1.1). Requires the session_branching capability. Default false.
instructions string no Additional system guidance for this task only.
store boolean no Whether the server retains the response for later reads. Default true.
max_output_tokens integer no Upper bound on generated tokens.
max_step integer no Upper bound on agent steps (tool-call rounds) for this task.
timeout_seconds integer no Wall-clock budget for this task.
environment string no The environment this task reads, overriding the harness's; refused with environment_not_found or environment_not_ready before the task starts. Requires the environments capability (Environments §5).
tools array no Reserved and ignored. Accepted, never acted on. See §1.4.
include string[] no Reserved and ignored. Accepted, never acted on. See §1.4.
background boolean no Return as soon as the task is accepted; follow it with the events endpoint.

A server MUST ignore request fields it does not understand rather than rejecting the request. A client MUST NOT rely on an unknown field having an effect.

Ignoring MUST be observable. When a server does not act on a field the request carried, it MUST name that field in metadata.ignored_fields on the response — an array of request-field names, in any order. This is the same principle as model substitution in §1.3: where the server did not do what the request literally said, the response says so. A silently ignored field is indistinguishable from an honoured one, and a client cannot tell which it got.

tools and include are reserved and ignored (§1.4), so a server MUST name them in metadata.ignored_fields whenever a request carries them. A server MUST NOT reject a request for carrying either.

max_step and timeout_seconds are budgets, not guarantees of precision: a server MUST stop the task at or after the budget, MUST report incomplete, and MUST NOT report completed for work it truncated.

1.2 Selecting the harness

The configured harness is selected by metadata.harness_id:

{ "metadata": { "harness_id": "chrn_…" } }
  • If harness_id is absent, the server MUST use a default harness and MUST report which one it used in the response metadata.
  • If harness_id names an unknown harness, or one outside the caller's scope, the server MUST fail with 404 and code: "harness_not_found".
  • If both previous_response_id and harness_id are present and disagree, the server MUST fail with 409 and code: "harness_mismatch" (see Lifecycle §4).

Why is the harness in metadata rather than a top-level field? Because the task surface is deliberately Responses-compatible (see the README), and metadata is the extension point that surface already defines for caller-supplied context. A top-level harness field would be a second, conflicting convention for the same idea, and every existing Responses SDK would have to be patched to send it.

1.3 Model selection and substitution

model names a canonical model id, not a provider-specific one. Canonical ids are stable across providers, so the same request works whether the server reaches a model directly or through an aggregator.

If the requested model cannot be served for the selected harness, a server MUST NOT fail silently and MUST NOT pretend it ran what was asked. It MUST do exactly one of:

  1. Fail with 422 and code: "model_unavailable"; or
  2. Substitute the harness's authorized default, and record the substitution in the response:
{
  "model": "gpt-5.4",
  "metadata": {
    "requested_model": "gpt-5.6-sol",
    "model_fallback": true,
    "model_fallback_reason": "model 'gpt-5.6-sol' is not available for this harness's backend"
  }
}

A client can therefore always answer "did the model I asked for actually run?" by comparing model with metadata.requested_model.

This rule exists because its absence is expensive. A server that substitutes silently makes every measurement downstream wrong — benchmarks, cost attribution, quality comparisons — and the client has no way to detect it. Reporting the substitution costs two fields.

1.4 Reserved fields: tools and include

Both fields arrived with the OpenAI Responses wire shape this version stays compatible with. Neither was designed for UHP, and neither has ever had defined semantics here. They are reserved: a server accepts them, never acts on them, and reports them under metadata.ignored_fields (§1.1).

This is a decision rather than a gap left open, so implementers can stop carrying them as unfinished work and client authors can stop building on them.

tools cannot mean what it means in the Responses API. There, the field exists because the client executes tools: the model emits a function_call, the client runs it, and returns a function_call_output as input on the next request. UHP puts both of those in output (§3.1). The harness invokes and executes tools itself and reports them as observability. There is no input path for a tool result, so the loop tools implies cannot be completed by a conformant server — not because implementations are immature, but because the object model has no place for the return leg. The one input item that answers an output item, input_response (§3.2), answers the harness's question to the person, not a tool the client ran: the harness still executes every tool itself.

tools also cannot mean "MCP servers for this task", which is the other plausible reading. Harnesses §4.1 already specifies MCP servers on the harness, with a field table and the semantics that matter: a disabled entry MUST NOT be contacted, an unreachable server MUST NOT fail the task. A request-level form would be a second mechanism for one behaviour.

More importantly, it would be an escalation primitive. If a request can attach an MCP server, anyone holding an API key can point the agent at an endpoint of their choosing, and the agent executes tools server-side with the harness's credentials and workspace access. The harness owner and the API caller are routinely different parties — a product configures a harness, and its end users drive tasks against it. Request-level declaration silently moves a capability decision from the accountable party to any caller. The configured harness is a first-class object precisely so that decision is made once, deliberately, by whoever owns the consequences.

The durable rule underneath, which applies beyond this field: narrowing is safe, widening is escalation. A future version could reasonably add a typed per-request tool disable list. It should never add a per-request grant.

include has no vocabulary. It is array of string with no enumerated values, so any string a server recognises is one that server named itself. Recognising a value would be inventing a vocabulary no other implementation shares.

How an agent gets tools: configure them on the harness. See Harnesses §4.1 for MCP servers and §4.2 for skills.

Removal is a question for the next version. This one is additive-only and cannot drop a field, so the honest form here is to say plainly that these two do nothing.

2. Input

input is either a string or an array of items.

{ "input": "Summarise README.md" }
{
  "input": [
    { "role": "user", "content": [
        { "type": "input_text", "text": "Summarise this report." },
        { "type": "input_file", "filename": "q3.pdf", "file_data": "data:application/pdf;base64,…" }
    ]}
  ]
}
Item type Purpose
input_text Text
input_file A file, inline as a data URL in file_data, or by file_id from a prior upload
input_image An image, inline or by file_id

A server at conformance class Core MUST accept input_text. A server at Extended MUST also accept input_file and input_image. See Files.

One item stands in the array on its own, with no role: input_response, the answer to a question the previous response asked (§3.2). A request carries at most one, and only with previous_response_id.

2.1 Earlier turns

A task can start from a conversation held somewhere else: a transcript the client kept, or a recorded run it continues as a task of its own. On a request without previous_response_id, an input array carries it the way the Responses API reads one: the user and assistant messages before the last user message, in order, are the conversation so far, and the last user message is the work.

{
  "input": [
    { "role": "user", "content": [{ "type": "input_text", "text": "Make a product image of a mug." }] },
    { "role": "assistant", "content": "Here is the mug on a light oak table." },
    { "role": "user", "content": [
        { "type": "input_text", "text": "Make the background white." },
        { "type": "input_file", "filename": "mug.png", "file_data": "data:image/png;base64,…" }
    ]}
  ]
}

An assistant message's content is a string or an array of output_text parts; files travel as input_file in a user message, under the limits of Files. A server that reports the input_history capability:

  • MUST give the harness the earlier messages as the conversation so far, and MUST treat only the last user message as the task's own message: it is what the task's turn records as the user's. system and developer messages stay instructions for the task, wherever they appear.
  • MUST keep the earlier messages in the session as its first turns, before the task's own, each marked imported: true in /turns. An imported turn is completed, ran no model and costs nothing.
  • MAY bound how many earlier messages and how much text it imports. Beyond a bound it MUST NOT import any of them and MUST NOT refuse the request for it: the request is read as it would be without the capability, so a client that sent such arrays before keeps working. A client that needs the turns kept checks that the first turn reads back imported: true.

With previous_response_id, the session already holds the conversation and this section does not apply. A client that needs the earlier turns kept MUST check capabilities.input_history first: a server without it may give the harness the last messages alone.

3. The response object

{
  "id": "resp_a1b2c3",
  "object": "response",
  "created_at": 1786400000,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "previous_response_id": null,
  "model": "claude-sonnet-4.6",
  "output": [
    { "id": "rs_1", "type": "reasoning", "summary": [ { "type": "summary_text", "text": "…" } ], "status": "completed" },
    { "id": "fc_1", "type": "function_call", "call_id": "call_1", "name": "read_file",
      "arguments": "{\"path\":\"README.md\"}", "status": "completed" },
    { "id": "fco_1", "type": "function_call_output", "call_id": "call_1", "output": "…", "status": "completed" },
    { "id": "msg_1", "type": "message", "role": "assistant", "status": "completed",
      "content": [ { "type": "output_text", "text": "- …\n- …\n- …", "annotations": [] } ] }
  ],
  "store": true,
  "usage": { "input_tokens": 5120, "output_tokens": 240, "total_tokens": 5360 },
  "metadata": { "session_id": "hsess7e78…" }
}
Field Type Required Notes
id string yes resp_-prefixed
object string yes Always response
created_at integer yes Unix seconds
status string yes See Lifecycle §3
error object | null yes Present and non-null only when status is failed
incomplete_details object | null yes Non-null only when status is incomplete: reason says what stopped the work. See Lifecycle §3
output item[] yes Ordered; MAY be empty for a task that produced nothing
model string yes The model that actually ran
usage object | null yes null when the server cannot account for usage — never a fabricated zero
metadata object yes MUST include session_id; see §1.3 for substitution fields
previous_response_id string | null yes The response this one continues, if any
store boolean yes Whether this response was retained

3.1 Output items

type Meaning
message Assistant text, in content[].text, with annotations for artifacts
reasoning The agent's summarised thinking, in summary[].text
function_call A tool the agent invoked, with arguments as a JSON string
function_call_output The result of that tool call, matched by call_id
input_request A question the harness asks the person; the task ended on it. See §3.2

A client MUST tolerate output item types it does not recognise, and MUST NOT assume any ordering beyond the array order given. A client that renders only message items and ignores the rest is a valid client.

3.2 Asking the person

A harness often needs one answer before it can go on: a choice between alternatives, a confirmation before an action that cannot be undone, a value it must not guess, a secret it must not invent. On a server that reports the input_requests capability, the harness asks, and the task ends on the question:

  • The response ends incomplete, with incomplete_details.reason input_required. Nothing waits: the turn is over and its working directory is kept as after any turn. The question stands until it is answered, passed over, or expires. A wait can last days, and a turn held open that long is a sandbox held open that long; ending the turn costs the server one resume, which it already does for every continuation.
  • The question is the response's last input_request item.
  • The turn's last message carries the question as text as well, so a client that renders only message items shows it (§3.1).
{ "id": "inreq_7c1d", "type": "input_request", "status": "completed",
  "kind": "choice", "prompt": "Which invoice?",
  "options": [ { "id": "left", "label": "Top toolbar" }, { "id": "right", "label": "Sidebar" } ],
  "expires_at": 1760000000 }
Field Type Required Meaning
id string yes inreq_-prefixed; what the answer names
kind string yes choice, confirm, free_text or secret
prompt string yes The question, as the person reads it
options object[] for choice and confirm { id, label } each; the answer is one id. A confirm without options is answered yes or no
expires_at integer no Unix seconds; an answer after it is refused

The answer is an input_response item in the next request's input, chained on the response that asked — a normal continuation (Sessions §1), the way a function_call_output answers a function_call:

{ "previous_response_id": "resp_a1b2c3",
  "input": [ { "type": "input_response", "input_request_id": "inreq_7c1d", "answer": "left" } ] }
Field Type Required Meaning
type string yes input_response
input_request_id string yes The input_request it answers
answer string yes An option id for choice and confirm; any text for free_text and secret

A server that reports input_requests:

  • MUST run the answer as a continuation of the session, and MUST give the harness the answer as the person's reply, with the question it answers, so the harness does not depend on its own record of having asked.
  • MUST refuse an answer with 409 and code: "input_not_pending" when the response has no pending request with that id: the id is unknown, the request was already answered, or a later task in the session passed it over. Not 404: the response exists, and in this protocol a 404 says the addressed object does not.
  • MUST refuse an answer after expires_at with 410 and code: "input_request_expired". Nothing runs during the wait, so this is a check at answer time.
  • MUST refuse an answer that does not fit the kind or the options with 422 and code: "input_response_invalid", and MUST keep the request pending for a better one.
  • MUST treat any other input chained on a response with a pending question as a normal task that voids the question, and MUST name the voided request's id in metadata.voided_input_requests on the new response. The same request, answered later, is input_not_pending.
  • MUST keep a secret answer out of the conversation. It reaches the harness through a reference of the server's own — an environment variable the message names, an entry in the server's secret store — and MUST NOT appear in any event, in the stored response, in GET /v1/responses/{id}, or in its input_items.
  • MUST refuse a request that carries an input_response and no previous_response_id, or more than one input_response, with 400 and code: "invalid_input".

How a harness asks is the server's. A base with a question tool of its own maps it; a base without one is given a tool, and that tool MUST be named ask_user and take the request's fields (kind, prompt, options), so that a client — and the conformance suite — can ask any harness on a server with the capability to put a question. Which bases can ask is the server's to say, beside the capability; a base that cannot asks in prose and the task completes, as before.

This section is additive. A server without the capability never emits input_request, and a client that does not know the item sees a terminal incomplete response with the question in its text (§3.1: a client tolerates item types it does not recognise).

4. Reading a task back

GET /v1/responses/{response_id}

Returns the same response object. A server that retained the response (store: true) MUST return it after completion; a server MAY return 404 with code: "response_not_found" for a response created with store: false.

GET /v1/responses/{response_id}/input_items

Returns the input the task was created with, for clients that need to reconstruct a transcript without having stored it themselves.

5. Cancelling

POST /v1/responses/{response_id}/cancel

See Sessions §4.

6. Idempotency

A client MAY send an idempotency key:

Idempotency-Key: <client-generated-unique-string>

A server that advertises idempotency MUST, for a repeated key:

  • return the result of the first request, and
  • not start a second execution.

If the first request is still running, the server MUST wait for it and return its result rather than returning a partial or a conflict. Agent tasks are expensive and side-effecting: a retry that runs the work twice is worse than a slow answer.

Idempotency keys SHOULD be retained for at least 24 hours.

7. Deleting

DELETE /v1/responses/{response_id}

Deletes the stored response. A server MUST NOT let this cancel a running task — cancellation and deletion are different intentions, and conflating them means a client cannot clean up history without stopping work.

Unified Harness Protocol 2026-10-19 · Apache-2.0 · defined and maintained in the HarnessRouter open-source repository. The standard can be implemented independently of any hosted service.