Not found
+This page does not exist. Start from the home page.
+This page does not exist. Start from the home page.
+The editor's copy is rebuilt from the main branch of philtzjp/agent-errors on every change.
+ +v1This URI identifies an Agent2Agent (A2A) protocol extension. An agent that declares it reports harness errors as harness error objects:
+https://agenterrors.org/ext/a2a/v1This page summarizes the A2A binding in the editor's copy of the draft. If they differ, the draft is authoritative.
+ +Declare the extension in the Agent Card with required set to false. Agents still report errors in the base A2A form, so clients that do not support the extension keep working.
"capabilities": {
+ "extensions": [
+ { "uri": "https://agenterrors.org/ext/a2a/v1", "required": false }
+ ]
+}When a task ends because of a harness error, the status message carries a text part with the detail text and a data part with the harness error object. The task state depends on the code:
| Harness error code | Task state |
|---|---|
harness.cancelled | canceled |
policy.model_refusal, policy.guardrail_triggered, policy.content_filtered | rejected |
| all other codes | failed |
Conditions that let the task continue, such as waiting for human approval or credentials, use input-required or auth-required and are not reported as harness errors.
{
+ "id": "task-123",
+ "status": {
+ "state": "failed",
+ "message": {
+ "role": "agent",
+ "parts": [
+ { "kind": "text", "text": "Stopped after reaching the 50-turn limit." },
+ { "kind": "data", "data": {
+ "type": "https://agenterrors.org/problems/harness-error",
+ "title": "Maximum Turns Exceeded",
+ "code": "loop.max_turns_exceeded",
+ "origin": "harness",
+ "retryable": false,
+ "limit": { "name": "turns", "value": 50, "observed": 50 }
+ } }
+ ]
+ }
+ }
+}An agent that delegates to a remote agent reports the remote failure as upstream.agent_failed and places the received object in causes. Each agent wraps the received object instead of rewriting it, so the original code and origin stay visible at the outermost level.
An AI agent runs a language model inside a harness. The harness parses model output, calls tools, manages context, and enforces limits. When something fails in this layer, such as malformed structured output, an exceeded turn limit, or context overflow, each implementation reports it differently. Many of them classify upstream failures by matching message text.
+ +Agent Errors defines a single error object for these failures. It is built on Problem Details (RFC 9457), carries a stable error code, and says whether the error is transient and whether the model can repair it. It also defines bindings to the Model Context Protocol and the Agent2Agent protocol.
+ +harness-errorv1{
+ "type": "https://agenterrors.org/problems/harness-error",
+ "title": "Output Schema Violation",
+ "code": "output.schema_violation",
+ "origin": "model",
+ "retryable": false,
+ "model_recoverable": true,
+ "model_feedback": "Field 'price' must be a number, got string.",
+ "location": { "turn": 5, "pointer": "/items/0/price" }
+}Work happens in the open on GitHub. Use issues for specific problems with the text, and discussions for broader questions. Contributions are subject to the IETF Note Well; see CONTRIBUTING.
+ +This is an individual Internet-Draft. It has no formal standing in the IETF and may change at any time.
+ + +harness-errorThis URI identifies a Problem Details (RFC 9457) object that describes an error detected by an AI agent harness:
+https://agenterrors.org/problems/harness-errorImplementations may use this URI until the problem type is registered with IANA as https://iana.org/assignments/http-problem-types#agent-harness-error. Consumers must treat the two URIs as equivalent.
This page summarizes the editor's copy of the draft. If they differ, the draft is authoritative.
+ +code is a registered error code of the form <category>.<name>, for example output.schema_violation. Consumers decide what kind of error occurred from code, never from title or detail.
| Member | Meaning |
|---|---|
origin | Where the error originated: model, harness, tool, upstream, or user. |
retryable | Whether repeating the same operation unchanged may succeed. |
model_recoverable | Whether the model is likely to correct the error if it is told about it. |
model_feedback | Text intended for the model, distinct from detail, which is for humans. |
retry_after | Seconds after which a retry is advised. |
attempts, max_attempts | Attempts already made, and the configured maximum. |
limit | The exceeded limit: name, value, observed, unit. |
location | Where in the run: run_id, turn, tool_name, tool_call_id, pointer. |
upstream | Raw information from an upstream component, kept for diagnosis. |
causes | Problem details objects that caused this one, most recent first. |
| Category | Description |
|---|---|
output | Model output could not be accepted by the harness. |
loop | A limit on the agent loop was reached, or the loop is not progressing. |
context | Context assembly or management failed. |
tool | Tool resolution or execution failed. |
policy | A policy, guardrail, refusal, or human decision stopped the operation. |
upstream | A remote dependency, typically the model API, failed. |
harness | The harness failed for another reason. |
The full list of codes, with default values for retryable and model_recoverable, is in the draft.
HTTP/1.1 422 Unprocessable Content
+Content-Type: application/problem+json
+
+{
+ "type": "https://agenterrors.org/problems/harness-error",
+ "title": "Output Retries Exhausted",
+ "code": "output.retries_exhausted",
+ "origin": "harness",
+ "retryable": false,
+ "attempts": 3,
+ "max_attempts": 3,
+ "causes": [
+ {
+ "type": "https://agenterrors.org/problems/harness-error",
+ "title": "Output Schema Violation",
+ "code": "output.schema_violation",
+ "origin": "model",
+ "model_feedback": "Field 'price' must be a number, got string.",
+ "location": { "turn": 5, "pointer": "/items/0/price" }
+ }
+ ]
+}_meta under the key org.agenterrors/harness-error, or in JSON-RPC error.data.