Skip to main content
The integration doctor is a command-line tool bundled with @agent-feedback/node. It fetches a real URL from your product, checks that the Agent Feedback contract is correctly embedded, and then submits a synthetic outcome review through the full chain — all in a single command. Run it right after your first deployment to confirm everything is wired up before you open feedback collection to agents.

​
Install and run

​
What the doctor checks

The doctor performs these checks in order:
  1. HTTP status is 2xx — the target URL must return a successful response. Any error status causes an immediate failure.
  2. Feedback contract is present — the doctor looks for the contract in three locations depending on your content type:
    • _agentFeedback key in a JSON response body
    • <script id="agent-feedback" type="application/json"> tag in an HTML response
    • Agent-Feedback response header (base64url-encoded JSON) for all other content types
  3. instruction field is non-empty — the contract must contain a valid instruction string.
  4. submit object is complete — the doctor verifies:
    • submit.url is present
    • submit.method is "POST"
    • submit.authorization starts with "Bearer afr2_"
    • submit.fields is present
  5. Synthetic review is accepted — the doctor submits { "outcome": "success", "note": "The integration doctor verified this product response end to end." } to the submit URL and confirms the backend returns a 2xx response with an interactionId.
Run the doctor against each URL in your include list after every deployment that touches your middleware configuration. It takes a few seconds and confirms the full chain from response injection through backend acceptance.

​
Failure messages

The doctor found a 2xx response but no feedback contract in any of the three expected locations (JSON body, HTML script tag, or response header).What to check:
  • Confirm the middleware is mounted before your route handlers, not after them.
  • Check your include list — if it’s set, make sure the URL path you’re testing matches one of the patterns.
  • Check your exclude list — the path may be excluded by one of your patterns or by the built-in exclusions.
  • Verify feedbackMode is not "off" and AGENT_FEEDBACK_ENABLED is not "false" in your environment.
  • Make sure the response has a 2xx status code; the middleware skips non-success responses.
The doctor found a contract with an instruction field, but the submit object is missing required fields, uses the wrong method, or the authorization header does not start with "Bearer afr2_".What to check:
  • This error almost always means you’re using a v1 key format that cannot produce v2 capability tokens. Open the Agent Feedback dashboard, create a new product key, and update AGENT_FEEDBACK_KEY in your environment.
  • Confirm you haven’t set a custom endpoint that points to an unreachable or incorrect backend.
The target URL returned a non-2xx HTTP status code.What to check:
  • Make sure the URL is correct and the service is running.
  • If the route requires authentication, the doctor does not send credentials. Consider testing with a public endpoint first, or add a test route that doesn’t require auth.
  • Check your server logs for the underlying error.
The contract was valid, but when the doctor submitted the synthetic review to submit.url, the backend returned a non-2xx status.What to check:
  • HTTP 401 or 403 — the capability token may have expired (tokens last two hours) or the product key may have been revoked. Fetch the URL again to get a fresh token.
  • HTTP 503 — the Agent Feedback backend may be temporarily unavailable. Wait a moment and retry.
  • If the problem persists, copy the submit.url and submit.authorization values from the raw response and check the Agent Feedback status page.
You ran the command without a URL argument.Fix: Pass a full URL as the first argument: