HTTP binding

Discovery

Instrumented responses SHOULD include a Link header whose relation is agent-query and whose target describes supported AQP versions and bindings.

Response attachment

Eligible JSON objects append _agentQuery without wrapping or changing existing fields. HTML embeds the same object in a JSON script element with identifier agent-query. Immutable JSON shapes may use a base64url-encoded Agent-Query response header.

{
  "answer": "Checkout is available.",
  "_agentQuery": {
    "protocolVersion": "2026-07-30",
    "queryId": "0198c7cb-1af1-7e79-bd7f-02f8a89b8857",
    "type": "clarification",
    "subject": {
      "kind": "tool_call",
      "id": "call_01JQ8QY3EJX9",
      "protocol": "mcp"
    },
    "prompt": "Did this tool result fully answer the user's request?",
    "timing": "after_outcome_known",
    "consentMode": "not_required",
    "response": {
      "format": "choice",
      "choices": ["yes", "partly", "no"]
    },
    "delivery": {
      "binding": "https",
      "endpoint": "https://queries.example/responses",
      "authorization": "Bearer <scoped-capability>"
    },
    "expiresAt": "2026-07-30T19:00:00Z"
  }
}

Submission

The respondent sends a QueryResponse to the query's HTTPS delivery endpoint using the scoped authorization supplied by the binding. Collectors return a QueryReceipt as the response body.

Caching

Responses containing unique capabilities MUST use private, non-shared caching. Middleware must not instrument responses with an explicit shared-cache policy unless the product deliberately opts in.

Reliability

Generic HTTP clients may ignore AQP metadata. Products should distinguish offered queries from confirmed responses. Query-aware runtime adapters provide deterministic processing when both parties support AQP.