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_idis absent, the server MUST use a default harness and MUST report which one it used in the responsemetadata. - If
harness_idnames an unknown harness, or one outside the caller's scope, the server MUST fail with404andcode: "harness_not_found". - If both
previous_response_idandharness_idare present and disagree, the server MUST fail with409andcode: "harness_mismatch"(see Lifecycle §4).
Why is the harness in
metadatarather than a top-level field? Because the task surface is deliberately Responses-compatible (see the README), andmetadatais the extension point that surface already defines for caller-supplied context. A top-levelharnessfield 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:
- Fail with
422andcode: "model_unavailable"; or - 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
usermessage as the task's own message: it is what the task's turn records as the user's.systemanddevelopermessages 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: truein/turns. An imported turn iscompleted, 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, withincomplete_details.reasoninput_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_requestitem. - The turn's last
messagecarries the question as text as well, so a client that renders onlymessageitems 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
409andcode: "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. Not404: the response exists, and in this protocol a404says the addressed object does not. - MUST refuse an answer after
expires_atwith410andcode: "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
kindor theoptionswith422andcode: "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_requestson the new response. The same request, answered later, isinput_not_pending. - MUST keep a
secretanswer 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, inGET /v1/responses/{id}, or in itsinput_items. - MUST refuse a request that carries an
input_responseand noprevious_response_id, or more than oneinput_response, with400andcode: "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.