Collect agent feedback over HTTP

Any agent that can make an HTTP request can report a problem to Agentback, in any language and with no SDK. Each project has a public address that accepts reports and, when an agent opens it with GET, explains itself in Markdown.

Send a report

Post JSON to your project's address. The project key in the path is public, so no secret is needed.

sh
curl -X POST 'https://agentback.app/f/af_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Search results omit the published date",
    "tool": "search",
    "category": "bug",
    "outcome": "worked_around",
    "agent": { "name": "Research agent", "model": "gpt-6-luna" }
  }'

A stored report returns HTTP 201 with { "id": "fb_...", "status": "new" }.

Tell agents where to report

Agents only use the address if they are told about it. Because the address answers a GET with instructions for agents (when to report, the fields, and what each response means), one line in your agent-facing docs is enough. Add it to your README, llms.txt, AGENTS.md, a skill, or the system prompt your product ships:

text
If Your product gets in the way of your task, report the problem to its developers. Read https://agentback.app/f/af_... for how; it takes one POST request.

Forward reports from your backend

If agents already call your API with their user's credentials, you can add a feedback endpoint to your API and forward reports with the secret key. Your backend can then attach the account and details of the failed call, which the public address does not accept.

ts
import { Agentback } from 'agentback';
const agentback = new Agentback({
  secretKey: process.env.AGENTBACK_SECRET_KEY,
});
await agentback.send(
  { message, intent, category, outcome, request_id },
  {
    source: 'api',
    account: tenantId, // an opaque ID, never an email
    context: { endpoint: '/search', status_code: 200, duration_ms: 320 },
  },
);

In other languages, send the same JSON to POST https://agentback.app/feedback with Authorization: Bearer $AGENTBACK_SECRET_KEY, adding source, account and context next to the report fields. Validate the agent's input before forwarding, and do not tell the agent its report was sent when forwarding fails.

Reference

Field	Limit or accepted values
`message`	Required, at most 4000 characters
`outcome`	`blocked`, `worked_around` or `friction`: how the task ended
`category`	`bug`, `feature_request`, `docs` or `other` (default)
`intent`	At most 2000 characters: what the agent was trying to do
`expected`	At most 2000 characters: what it expected to happen
`actual`	At most 4000 characters: what happened instead, including the error text
`tool`	At most 128 characters: the tool, command or endpoint involved
`suggestion`	At most 2000 characters: what would have helped
`version`	At most 64 characters: your product's version
`request_id`	At most 256 characters: the ID of the failed call
`agent.name`, `agent.model`	At most 128 characters each
`source`	`direct`, `mcp`, `cli` or `web` on the public address; `api`, `mcp`, `cli` or `web` with the secret key
`page`	An http(s) address: the page a person reported from
`account`	At most 256 characters, with `account_signature` on the public address
`context`	`endpoint`, `status_code` and `duration_ms`; secret key only

Unknown fields are rejected and bodies are limited to 64 KiB.

Status	Meaning
201	Stored
400	Invalid JSON or fields; `details` lists each problem
401	Missing or invalid secret key or account signature
404	Unknown project key
413	Body larger than 64 KiB
415	Content-Type is not `application/json`
429	Rate limited; retry after 60 seconds
503	Storage unavailable; the report was not stored

Feedback is best effort: never let a failed report break the agent's main task.

Hand the setup to your coding agent

Paste one prompt into Claude Code, Cursor or Codex. It finds your MCP server, CLI, API or web app, connects to your account and adds Agentback.

Create a free inbox

CLI Web widget