Skip to main content
Before you instrument anything, it helps to understand exactly what the SDK does on every request, what ends up in your product’s response, and how an agent runtime turns that into a stored outcome review. This page traces the full flow from a product response to a dashboard entry — nothing is hand-waved.

​
The two interaction surfaces

Agent Feedback recognizes two types of product surface, and treats them differently from the start. An unclassified interaction is not a failure — it means the SDK cannot confirm that the requesting client is a feedback-aware agent runtime. Many generic HTTP agents will still read the _agentFeedback field and act on it correctly. A confirmed interaction means the MCP framing guarantees a capable agent is on the other side.
The SDK never claims to identify individual agents. customerRef, session continuity, and runtime hints are optional context fields you supply — not something the protocol infers.

​
How a capability token is created

When a product response is eligible for instrumentation, the SDK creates a capability token locally before the response is sent. No network call is involved at this step.
The token is write-only and scoped: it authorizes exactly one outcome submission for exactly one interaction. It contains no customer reference, prompt, product payload, or personal data.

​
How the feedback contract is embedded

After the capability token is created, the SDK embeds a feedback envelope into the product response using one of three mechanisms, chosen automatically based on the response content type. JSON objects — The SDK appends _agentFeedback directly to the response body without wrapping or restructuring your existing fields:
HTML pages — The SDK injects <script id="agent-feedback" type="application/json"> into the <head> (or <body> if no <head> is present) containing the same JSON envelope. Arrays, scalars, and other non-object JSON — Because the SDK cannot safely append a field to these body types, it uses the Agent-Feedback: <base64url-encoded envelope> response header instead, accompanied by a Link header pointing to the discovery document.
The SDK automatically skips instrumentation for error responses (non-2xx), redirects, HEAD requests, health/metrics endpoints, asset paths, streams, binary bodies, and the Agent Feedback API endpoints themselves. It also skips any response that already contains an _agentFeedback field, and adds Cache-Control: private, no-store to every instrumented response because each capability token is unique.

​
How the agent submits an outcome

After the agent runtime completes its task and knows the outcome, it POSTs a compact review directly to the URL in submit.url, using the scoped capability token as the Bearer credential — not your product key:
The outcome field must be success, partial, or failure. The note field must be 8–500 characters and must not contain prompts, transcripts, credentials, or personal data. The server rejects unknown fields and duplicate submissions (a second submission for the same interaction ID returns the first accepted review rather than creating a new one). The capability token carries its own expiry (exp), so submissions after two hours are rejected. This window is intentionally short: outcome reviews are most accurate immediately after task completion.

​
How telemetry reaches the dashboard

Your product response goes out before any network I/O touches Agent Feedback. After the response is fully sent, the SDK enqueues an opportunity metadata event in a bounded in-process queue and returns immediately. A background timer (default: 500 ms) drains the queue in batches of up to 50 events:
Each event records the interaction ID, surface type, normalized operation path, HTTP status code, response duration, optional customerRef, classification, and timestamp. No request body content, user data, or prompt text is included. If the telemetry endpoint is unreachable, the SDK retries each event up to three times, then drops it rather than growing the queue unboundedly or delaying your application. A warning is logged once per failure run, and subsequent product responses are never affected.
During graceful shutdown, call middleware.shutdown() (Node) or the equivalent in your SDK. This flushes any remaining queued events before the process exits, so you don’t lose the last few interactions.

​
Agent-side helpers: deterministic outcome submission

Generic agents can read _agentFeedback from any response and POST an outcome directly. Every SDK also ships optional helpers for feedback-aware runtimes that want a type-safe, allow-listed path: The parse helper extracts the _agentFeedback envelope from the response body (JSON) or Agent-Feedback header (non-object bodies). The submit helper validates that the submit.url in the envelope belongs to the Agent Feedback service before making the network call, preventing a compromised product from redirecting outcome data to an attacker-controlled endpoint.
Agent-side helpers are optional. They are designed for runtimes that call your product programmatically. End-user agents that read the contract directly from the response body work equally well without them.

​
Privacy guarantees

The protocol enforces a strict data minimization model at every layer:
  • Capability tokens contain only a version, interaction ID, issued-at timestamp, expiry, and a random nonce — nothing else.
  • Outcome submissions accept only outcome and note. The server rejects any additional fields.
  • Telemetry events carry opportunity metadata (timing, surface, operation) and the optional opaque customerRef you supply. They never contain request bodies, response content, or any user-generated text.
  • Notes are limited to 8–500 characters and the protocol explicitly instructs agents not to include user data, prompts, transcripts, credentials, or raw product content.
The result is a feedback signal you can act on without ever storing what your customers’ agents said or did.