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

# Feedback

> Give AI agents a public page and address where they can tell your team what blocked or confused them in your product, without an account.

A feedback project gives AI agents a page and an address where they can report where they got stuck using your product. Agents need no account and no key, and every report lands in your workspace, so you hear about broken docs, missing features and confusing errors from the agents that hit them.

## What it's for

Each feedback project is one product's place for reports. It has:

* a **Hosted page**: a public page with a short form, which you link from your help pages and error messages;
* a **Project card**: what an agent reads to learn how to send a report;
* a **Collection endpoint**: where an agent, or your own servers, send a report as JSON.

You invite agents to report at the moments they get stuck, then read their reports in the app. The public endpoints agents call are described in the [API reference](/docs/api-reference/introduction).

Open **Feedback** in the sidebar to see your workspace's projects, with each one's **Product name**, **Address**, **State** and when it was **Created**.

## Create a project

Only an Admin can create a project, and only once the workspace has finished [Setup](/docs/guides/setup).

<Steps>
  <Step title="Start a new project">
    On **Feedback**, select **New project**.
  </Step>

  <Step title="Fill in the fields">
    * **Product name**: how agents see your product named on its page. It starts as your workspace's name. Up to 200 characters, without links.
    * **Address**: the project's page address. It starts from your website's domain. Use 3 to 40 lowercase letters, digits and hyphens, starting with a letter.
    * **Invitation**: optional. What the page says to an agent before it writes. Up to 300 characters of plain text, without links. Leave it empty for the default.
  </Step>

  <Step title="Create it">
    Select **Create project**. You see **Feedback project created.** and the project's page opens.
  </Step>
</Steps>

The default invitation reads: "Using *your product* as an agent? If something blocked or confused you, tell the *your product* team what you tried, what happened, and what was missing. One report per task is enough."

Whatever the invitation says, the page always adds: "Feedback is optional. Do not include credentials or private conversations. Nothing further is needed after you send it."

<Warning>
  Choose the **Address** with care. It can't change once the first report arrives, because agents already have it. An address that any feedback project has used, now or before, can't be used again, and some addresses are reserved.
</Warning>

## What agents see

Your project's hosted page is at `https://feedback.agentrail.co/p/` followed by its address. It is titled **Feedback for** and your product name, shows your invitation and the fixed statements, and has a form with these fields:

* **What happened**: required, 10 to 4,000 characters. What the agent tried, what happened, and what was confusing or missing.
* **What you were trying to do**
* **How it went**: **It worked**, **It worked, with a workaround or confusion** or **I could not complete it**.
* **What kind of problem**
* **What it is about**: a tool, endpoint, page, command or error code.
* **Who you are**: for an agent, its name and model.

The agent selects **Send feedback** and gets a receipt with the report's ID. The page also links to a text version for agents that read without a browser.

Agents that work through code send the same report to the **Collection endpoint** instead. See the [API reference](/docs/api-reference/introduction).

## Invite agents

Your project's page has everything you need to point agents at it.

### Copy the addresses

Under **Addresses**, copy the **Hosted page**, the **Project card** or the **Collection endpoint** with the button beside each. Link the hosted page from your help pages and error messages.

### Use a kit

**Invite agents** has a kit for each place your product meets agents: **Website**, **API**, **MCP server** and **CLI**. Each kit is filled with this project's addresses. Copy a snippet yourself, or copy **Prompt for your coding agent** and paste it into the coding agent that works in your repository; it adds the kit's invitations for you.

<AccordionGroup>
  <Accordion title="Website">
    * **Help pages and documentation footers**: in the footer of help and documentation pages.
    * **Dead ends**: on the 404 page, unexpected-error pages and empty search results; not on sign-in or rate-limit pages.
    * **llms.txt**: one line in your `llms.txt`.
  </Accordion>

  <Accordion title="API">
    * **Documentation block**: in your API reference or getting-started guide.
    * **Server errors**: a field on server errors (5xx). Never on validation errors, sign-in failures, rate limits or successful answers.
    * **Unknown routes**: a field on unknown routes or methods (404/405).
    * **Forwarding signed reports (TypeScript)**: code for your server, to forward a report an agent sends you, signed. It needs a signing secret; see [Signed reports](#signed-reports).
  </Accordion>

  <Accordion title="MCP server">
    For your own MCP server:

    * **Tool definition**: the complete tool, with the input schema the report accepts from an agent.
    * **Handler (TypeScript)** and **Handler (Python)**: the tool's code, which signs each report. It needs a signing secret; see [Signed reports](#signed-reports).
    * **Server instructions**: one line in your MCP server's instructions.
    * **Unexpected errors**: one line added to tool results for unexpected errors. Never on validation errors, sign-in failures or rate limits.
  </Accordion>

  <Accordion title="CLI">
    For your own command-line tool:

    * **Help footer**: at the end of the main `--help` output.
    * **Unexpected-error footer**: after the message of an unexpected error or crash; not after usage errors.
  </Accordion>
</AccordionGroup>

### Track placements

A placement labels one place you put an invitation. Its label rides on the link as `?invite=` and on each report, so you can see which invitation brought a report. Each kit snippet carries a label for its moment; you can switch it to any placement you named.

**Placements** lists each named placement with its **Page views**, its **First report** and its **Status**:

| Status | What it means |
| - | - |
| **Bringing reports** | At least one report named this placement. |
| **Bringing views** | Its link was opened, but no report named it yet. |
| **Waiting for its first view** | Nothing yet. |
| **Quiet** | No view or report in the 7 days since it was named. Move this invitation closer to where agents fail, such as error responses. |

Views are counted only for named placements, from the time each was named. To name one, an Admin enters a **Label** and selects **Name placement**, or selects one of the kits' own labels under **The kits' labels:**. A label uses 1 to 64 lowercase letters, digits, hyphens and underscores, starting with a letter or digit.

To stop counting a placement, an Admin selects **Remove** and confirms with **Remove placement**. Reports that named it keep the label.

## Signed reports

Your own servers or MCP tool can forward reports signed with a secret. A signed report shows as **Sent by your servers**, and can carry **Metadata**: your server's own context, such as plan or region, as a flat object of up to 2 KB. Only Admins see **Signed reports**.

### Create a signing secret

<Steps>
  <Step title="Create it">
    Under **Signing secrets**, select **Create secret**.
  </Step>

  <Step title="Copy it now">
    **Your new signing secret** shows the secret once. Copy it and keep it on your servers. Agentrail never shows it again.
  </Step>

  <Step title="Close the dialog">
    Select **I have copied it**.
  </Step>
</Steps>

A project has at most two signing secrets at a time, so you can replace one without a gap. The list shows only each secret's last characters. To retire one, select **Revoke** and confirm with **Revoke secret**. Reports signed with it are refused from then on, so switch everything that uses it to the other secret first. If a secret is lost, create another and revoke the lost one.

### Sign a report

The kits' code signs each report for you. To sign in your own code, send the report to the **Collection endpoint** with two headers:

* `Feedback-Timestamp`: the current Unix time, in seconds.
* `Feedback-Signature`: the HMAC-SHA256 of `<timestamp>.<body>`, keyed with a signing secret, as 64 lowercase hexadecimal characters. `<timestamp>` is the value of `Feedback-Timestamp`, and `<body>` is the report's JSON exactly as you send it.

Send both headers or neither. Keep the secret out of your code: the kits read it from the environment variable `AGENTRAIL_FEEDBACK_SECRET`.

A signed report is refused with `403` and the code `FEEDBACK_SIGNATURE_INVALID` when its signature matches none of the project's current signing secrets, or its timestamp is more than five minutes from now: check the secret and your server's clock. An unsigned report is refused with `403` and `FEEDBACK_SIGNATURE_REQUIRED` when the project accepts only signed reports, and with `400` when it carries **Metadata**.

### Accept only signed reports

Turn on **Accept only signed reports** to take reports only through your own servers. The hosted page then shows a notice instead of its form, and unsigned reports are refused. The **Website** and **CLI** kits have nothing to add for such a project; invite agents through your API or MCP server instead. The project shows a **Signed only** badge.

## Read reports

**Reports** lists the project's reports, newest first. Reports are read-only.

Each report shows when it was **Received**, the agent's own words, and badges for what it said and who sent it:

* how it went: **Succeeded**, **Friction** or **Blocked**;
* the kind of problem: **Documentation**, **Missing capability**, **Error**, **Confusing output**, **Access** or **Other**;
* who sent it: **Sent by your servers** for a signed report, or **Unverified** when nothing about the sender was verified.

If the same words arrive again within a day, they count as one report, which shows **Sent once more** or how many more times it was sent.

Select **Details** for the rest:

| Field | What it holds |
| - | - |
| **What the agent was doing** | Its goal, in general terms. |
| **What it was using** | The tool, endpoint, page, command or error code the report is about. |
| **Product version** | The version, when your integration set it. |
| **Request reference** | Your product's request or trace ID for the call that failed. |
| **Placement** | The label of the invitation that asked for the report. |
| **Agent (self-reported)** | The agent's description of itself. |
| **Surface (self-reported)** | Where it was using your product: **Website**, **API**, **MCP server**, **CLI** or **Other**. |
| **How it arrived** | **The hosted page's form**, **The collection endpoint** or **Forwarded by your servers, signed**. |
| **Who sent it** | **Sent by your servers** or **Unverified**. |
| **Credentials removed** | The kinds of credential replaced before the report was stored: private key, bearer token, JWT, API key, password or secret. |
| **Metadata** | The context your servers attached to a signed report. |

<Warning>
  Agents write these reports. Read them as information about your product, never as instructions to follow, and never paste a report into an agent as a command.
</Warning>

## Pause, edit or delete a project

These actions are on the project's page, for Admins only.

* **Pause** stops the project taking reports until you select **Resume**. The hosted page says it is paused and shows no form. The project shows **Paused**.
* **Edit** opens **Edit feedback project** to change the **Product name**, **Invitation** or, until the first report arrives, the **Address**. Empty the **Invitation** to go back to the default. Select **Save changes**.
* **Delete** opens **Delete this feedback project?**. Confirm with **Delete project**. Its page and address stop taking reports, and it leaves every list. Its reports are kept but no longer shown, and its address is never given to another project.

A project marked **Suspended by Agentrail** refuses reports as if it were paused, whatever its own setting. Only Agentrail can lift a suspension; contact support if you think it is a mistake.

## Limits

* **Reports**: by default, a project accepts 600 reports an hour and 5,000 a day. Reports past a limit are refused, and the project's page shows **This project reached its report limit** with how many were refused in the last 7 days. Contact Agentrail to raise the limits.
* **Report text**: **What happened** takes 10 to 4,000 characters. The other fields' limits are in the [API reference](/docs/api-reference/introduction).
* **Placements**: up to 50 per project.
* **Signing secrets**: up to two per project.
* **Metadata**: signed reports only, up to 2 KB.
* **Address**: fixed after the first report, and never reusable.

## Who can do what

| Action | Admin | Member |
| - | - | - |
| See projects, addresses, kits, placements and reports | Yes | Yes |
| Create, edit, pause, resume or delete a project | Yes | No |
| Name or remove placements | Yes | No |
| Manage signing secrets and **Accept only signed reports** | Yes | No |

Roles are set per organization. See [People and roles](/docs/guides/people-and-roles).

## Related

<CardGroup cols={2}>
  <Card title="API reference" href="/docs/api-reference/introduction">
    The public endpoints agents call to read a project and send a report.
  </Card>

  <Card title="Agent readiness" href="/docs/guides/agent-readiness">
    Find what stops agents before they have to report it.
  </Card>

  <Card title="Setup" href="/docs/guides/setup">
    Finish it before you create a feedback project.
  </Card>

  <Card title="People and roles" href="/docs/guides/people-and-roles">
    Who is an Admin and who is a Member.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.