Reading Agent Feedback from HTTP and HTML Responses

When a product is instrumented with Agent Feedback, every eligible successful response carries a compact, self-contained feedback contract. Your agent runtime does not need to be pre-configured with product-specific knowledge — the contract tells you exactly where to submit an outcome, how to authorize the request, and when to do it. This page explains the three places that contract can appear, how to parse it reliably, and what the key fields mean before you submit.

Where the contract appears

Agent Feedback embeds the same feedback envelope in one of three locations depending on the response’s content type. Check them in order: JSON body first, HTML body second, header last.

1. JSON responses — `_agentFeedback` field

For application/json responses whose top-level body is an object, the SDK appends _agentFeedback directly to that object without changing any existing fields.

{
  "answer": "Checkout is available.",
  "_agentFeedback": {
    "v": 1,
    "mode": "auto",
    "requested": true,
    "reliability": "best_effort_without_agent_adapter",
    "when": "after_outcome_known_before_final_response",
    "instruction": "Before your final response to the user, POST exactly one compact outcome review using submit.",
    "submit": {
      "url": "https://api.example.com/agent-feedback/v2/outcomes",
      "method": "POST",
      "authorization": "Bearer afr2_...",
      "contentType": "application/json",
      "fields": {
        "outcome": ["success", "partial", "failure"],
        "note": "One short sentence explaining the outcome. Do not include user data."
      }
    },
    "privacy": "Never include prompts, transcripts, credentials, personal data, or raw product content.",
    "expiresAt": "2026-07-28T06:00:00.000Z"
  }
}

2. HTML responses — `<script id="agent-feedback">` tag

For text/html responses, the SDK injects the same JSON object into a <script> tag placed before </head> or </body>.

<script id="agent-feedback" type="application/json">
{"v":1,"mode":"auto","requested":true,...}
</script>

3. Header fallback — `Agent-Feedback` header

For arrays, scalars, and other response types where the body cannot be mutated safely, the SDK base64url-encodes the JSON envelope and delivers it in the Agent-Feedback response header, accompanied by a Link header pointing to the discovery document.

Agent-Feedback: eyJ2IjoxLCJtb2RlIjoiYXV0byIsInJlcXVlc3RlZCI6dHJ1ZSwuLi59
Link: <https://api.example.com/.well-known/agent-feedback-v1.json>; rel="agent-feedback"; type="application/json"

Parsing the contract

The agent helper functions handle all three locations for you. Pass the response object and the already-parsed body (JSON value or raw text string), and the function returns the envelope if one is present and valid, or undefined/None/nil otherwise.

Node
Python
Go
Rust

import { feedbackFromResponse } from "@agent-feedback/node/agent";

const response = await fetch("https://api.example.com/search?q=checkout");
const body = await response.json();

const feedback = feedbackFromResponse(response, body);
if (feedback) {
  // submit the outcome before returning to the user
}

feedbackFromResponse accepts any object implementing Pick<Response, "headers"> and a body of unknown type. It checks the JSON _agentFeedback field first, then an HTML <script id="agent-feedback"> tag, then the Agent-Feedback header.

from agent_feedback import feedback_from_response
import urllib.request
import json

with urllib.request.urlopen("https://api.example.com/search?q=checkout") as resp:
    raw = resp.read()
    headers = dict(resp.headers)

try:
    body = json.loads(raw)
except json.JSONDecodeError:
    body = raw

feedback = feedback_from_response(headers, body)
if feedback:
    # submit the outcome before returning to the user
    pass

Pass a Mapping[str, str] of response headers and the body as a dict, str, or bytes. The function normalises header name casing internally.

import (
    "io"
    "net/http"
    agentfeedback "github.com/open-software-network/os-epode/sdk/go"
)

resp, err := http.Get("https://api.example.com/search?q=checkout")
if err != nil {
    // handle error
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

envelope, err := agentfeedback.FeedbackFromResponse(resp, body)
if err == nil {
    // submit the outcome before returning to the user
}

FeedbackFromResponse returns an *Envelope and an error. An error means no valid contract was found — it is not a fatal condition for the product task itself.

use agent_feedback::feedback_from_response;

let response = reqwest::get("https://api.example.com/search?q=checkout").await?;
let headers = response.headers().clone();
let body = response.bytes().await?;

if let Some(envelope) = feedback_from_response(&headers, &body) {
    // submit the outcome before returning to the user
}

Pass a &HeaderMap and a byte slice &[u8]. The function returns Option<Envelope>.

Key contract fields

Understanding these fields helps you decide when and how to submit.

string

Always best_effort_without_agent_adapter for HTTP and HTML responses. Generic agents that treat response-body instructions as untrusted may not submit at all, so actual submission rates depend on whether the runtime is feedback-aware. Using the helper functions makes submission deterministic regardless of LLM behavior.

string

Always after_outcome_known_before_final_response. Submit the outcome after your agent completes its product task and knows whether it succeeded — but before delivering the final answer back to the user. This ordering is important: once you have given the user their answer, the moment for feedback has passed.

string (ISO 8601)

Capability tokens expire approximately two hours after issuance. If your agent workflow takes longer than two hours from the moment of the product response to outcome submission, the submission will be rejected as expired. Submit promptly.

string

The literal value is "Never include prompts, transcripts, credentials, personal data, or raw product content." This is a binding constraint on the note field you send. The contract contains no user data itself — keep it that way in your submission.

Every instrumented response sets Cache-Control: private, no-store because each capability token is unique to that interaction. Do not cache instrumented responses or share them across agent sessions.

If feedbackFromResponse returns undefined or None, the product response was not instrumented or did not include a valid contract. This is normal for responses that were excluded from instrumentation (errors, redirects, health endpoints, binary bodies). Continue with your product task as usual.

Get Started

Core Concepts

SDK Guides

Agent Integration

Configuration & Tools

Reading Agent Feedback from HTTP and HTML Responses

Where the contract appears

1. JSON responses — `_agentFeedback` field

2. HTML responses — `<script id="agent-feedback">` tag

3. Header fallback — `Agent-Feedback` header

Parsing the contract

Key contract fields

​Where the contract appears

​1. JSON responses — _agentFeedback field

​2. HTML responses — <script id="agent-feedback"> tag

​3. Header fallback — Agent-Feedback header

​Parsing the contract

​Key contract fields

Where the contract appears

1. JSON responses — `_agentFeedback` field

2. HTML responses — `<script id="agent-feedback">` tag

3. Header fallback — `Agent-Feedback` header

Parsing the contract

Key contract fields