> ## Documentation Index
> Fetch the complete documentation index at: https://docs.epode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Doctor: Verify Your Feedback Contract End-to-End

> Run agent-feedback-doctor against a live URL to verify the feedback contract is correctly embedded and a synthetic outcome review is accepted end-to-end.

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

<Steps>
  ### Add the package (if you haven't already)

  The doctor is included in `@agent-feedback/node` and registered as the `agent-feedback-doctor` binary. If the package is already a dependency in your project, you can skip this step.

  ```bash theme={null}
  npm install @agent-feedback/node
  ```

  ### Run against a live product URL

  Pass the full URL of any endpoint you've instrumented. Include a realistic query string if your route requires one:

  <CodeGroup>
    ```bash npx (no install required) theme={null}
    npx agent-feedback-doctor https://api.example.com/search?q=checkout
    ```

    ```bash Global install theme={null}
    agent-feedback-doctor https://api.example.com/search?q=checkout
    ```
  </CodeGroup>

  ### Read the output

  A fully working integration prints three `PASS` lines:

  ```
  PASS response injection
  PASS scoped direct submission
  PASS synthetic review <interactionId>
  ```

  A failure prints a `FAIL` line with a specific message. See the [failure reference](#failure-messages) below to resolve it.
</Steps>

## 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`.

<Tip>
  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.
</Tip>

## Failure messages

<Accordion title="&#x22;Response is missing feedback instructions&#x22;">
  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.
</Accordion>

<Accordion title="&#x22;Response has an incomplete feedback submission contract&#x22;">
  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.
</Accordion>

<Accordion title="&#x22;Product returned HTTP <status>&#x22;">
  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.
</Accordion>

<Accordion title="&#x22;Synthetic review returned HTTP <status>&#x22;">
  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.
</Accordion>

<Accordion title="&#x22;Usage: agent-feedback-doctor <product-response-url>&#x22;">
  You ran the command without a URL argument.

  **Fix:** Pass a full URL as the first argument:

  ```bash theme={null}
  agent-feedback-doctor https://api.example.com/your-endpoint
  ```
</Accordion>