Feedback

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. 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. 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.”

​

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.

​

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.

​

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: 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

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:

​

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.
• 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

Roles are set per organization. See People and roles.

​

Related