SeggWat LogoSeggWat
BlogDashboard

Agent Feedback Reports

Let autonomous AI agents file structured reports about your API, docs, CLI and SDK, with no human in the loop.

Overview

Coding agents hit your API, read your docs and run your CLI all day. When something breaks or doesn't match the docs, they usually work around it and move on. Agent feedback reports give them somewhere to say so: an unauthenticated endpoint where an agent files a structured report on its own, and the report lands in your SeggWat inbox.

The receiver is wire-compatible with the agent feedback protocol pioneered by feedback.now (discovery at /.well-known/agent-feedback.json), so any agent that already speaks that protocol works unchanged.

How this differs from other agent integrations

Integration Who the agent works for Auth
Agent feedback reports (this page) Itself, reporting problems it hit in your product None
Hosted MCP server Your team, triaging feedback in SeggWat API key or OAuth
WebMCP tools A human, on a page they're signed in to Browser session

How It Works

  1. You enable Agent feedback reports for a project.
  2. You host a discovery file at https://<your-domain>/.well-known/agent-feedback.json.
  3. An agent fetches the discovery file, optionally fetches the policy, and POSTs a report.
  4. SeggWat returns a receipt. The agent can poll the receipt for status.
  5. The report shows up in your feedback inbox with source Agent Report, plus a metadata panel with the reporter, subject, signal and evidence.

Setup

1

Enable agent reports

In the SeggWat Dashboard, open your project, go to Settings, and turn on Agent feedback reports. Copy the Project Key while you're there.

2

Host the discovery file

SeggWat generates the discovery document for you:

https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/discovery.json

Serve it at /.well-known/agent-feedback.json on your own domain. See Hosting the discovery file.

3

Verify

bash
curl https://your-domain.com/.well-known/agent-feedback.json

Hosting the Discovery File

All URLs in the discovery document are absolute, so any of these work:

  • Static file: download the JSON and save it as .well-known/agent-feedback.json in your site's public directory. Re-download it if you rename the project.
  • Redirect: point the path at SeggWat. For Nginx:
nginx
location = /.well-known/agent-feedback.json {
    return 301 https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/discovery.json;
}
  • Docs sites built on dioxus-docs-kit (0.10+): one builder call serves the file and adds a "Reporting problems" section to llms.txt:
rust
use dioxus_docs_kit::server::{AgentFeedback, SeoRouter};

SeoRouter::new("https://your-domain.com", "Your Docs", "Documentation")
    .with_docs(&DOCS, "/docs")
    .with_agent_feedback(AgentFeedback::Redirect(
        "https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/discovery.json".into(),
    ))
    .into_router()

Tell Agents Where to Report

Most agents don't probe /.well-known on their own yet. The reliable path is to put the pointer in text agents already read: your llms.txt, an AGENTS.md or CLAUDE.md in your SDK repos, your README, or your API error bodies. The discovery file stays there for agents that do look.

Snippet for llms.txt, AGENTS.md or README

markdown
## Reporting problems

If you hit a bug, a docs mismatch, friction, or a missing feature while using
this API, docs, CLI or SDK, file a report. No auth needed.

1. GET https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/discovery.json
2. POST a JSON report to `endpoints.feedback.submit.url`. Only
   `subject.surface`, `signal.category` and `content.title` are required;
   everything else is optional. `policy_url` lists the accepted enums and
   limits. Redact secrets in `evidence`.

One report per distinct problem. Keep working after filing; nobody replies
in-band.

Prompt for a one-off agent run

Paste this into Claude Code or any coding agent, with your own task in the first sentence:

text
Integrate the Acme Orders API into this project using only https://docs.acme.com.

Whenever the docs and the real behaviour disagree, or something is harder than
it should be, file a report before working around it:
- GET https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/discovery.json
- POST to endpoints.feedback.submit.url. Required: subject.surface,
  signal.category, content.title. Everything else is optional; add what you
  know: reporter (your vendor, product, version), subject.domain/kind,
  signal.severity/confidence (0-1)/reproducibility, content.summary/hypothesis,
  and up to 10 evidence items with secrets redacted.
One report per distinct problem, then continue the task.

Hint in API error responses

Agents read error bodies closely. Adding the discovery URL to your 4xx/5xx JSON is the cheapest discovery of all:

json
{
  "error": "invalid_auth",
  "message": "Use Authorization: Bearer <key>",
  "agent_feedback": "https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/discovery.json"
}

Endpoints

All endpoints live under https://seggwat.com. Replace {project_key} with your project key.

Method Path Purpose
GET /api/v1/agent/{project_key}/discovery.json Discovery document
GET /api/v1/agent/{project_key}/policy Accepted categories, evidence types and limits
POST /api/v1/agent/{project_key}/feedback Submit a report
GET /api/v1/agent/{project_key}/receipts/{id} Look up a receipt
  • Auth: none.
  • Rate limit: bursts of 20, then about 60 requests per hour per IP, shared with the public widget submit endpoints.
  • Not found: 404 when the project doesn't exist or agent reports are turned off.

Discovery Document

json
{
  "schema_version": "1.1",
  "name": "Acme API",
  "description": "Agent feedback for Acme API. Agents submit structured reports about API, docs, CLI and SDK issues they encounter.",
  "spec_url": "https://seggwat.com/docs/guides/agent-feedback",
  "policy_url": "https://seggwat.com/api/v1/agent/{project_key}/policy",
  "endpoints": {
    "feedback": {
      "submit": {
        "method": "POST",
        "url": "https://seggwat.com/api/v1/agent/{project_key}/feedback",
        "description": "Submit a structured feedback report."
      }
    },
    "receipts": {
      "get": {
        "method": "GET",
        "url": "https://seggwat.com/api/v1/agent/{project_key}/receipts/{id}",
        "description": "Check the status of a submitted report."
      }
    },
    "policy": {
      "get": {
        "method": "GET",
        "url": "https://seggwat.com/api/v1/agent/{project_key}/policy",
        "description": "Accepted categories, enums and limits."
      }
    }
  },
  "categories": ["bug", "docs_mismatch", "friction", "feature_gap", "quality_degradation", "other"],
  "evidence_types": ["http_summary", "stderr_excerpt", "repro_steps", "screenshot", "log_excerpt", "other"],
  "contact": "https://seggwat.com"
}

Policy Document

json
{
  "version": "1.0",
  "categories": ["bug", "docs_mismatch", "friction", "feature_gap", "quality_degradation", "other"],
  "severity_levels": ["critical", "high", "medium", "low"],
  "reproducibility_options": ["always", "sometimes", "intermittent", "once"],
  "evidence_types": ["http_summary", "stderr_excerpt", "repro_steps", "screenshot", "log_excerpt", "other"],
  "surface_kinds": ["api_endpoint", "docs_page", "cli_command", "sdk_method", "other"],
  "limits": {
    "max_evidence_per_feedback": 10,
    "max_evidence_content_bytes": 65536,
    "max_title_length": 256,
    "max_summary_length": 4096,
    "max_hypothesis_length": 2048,
    "confidence_range": { "min": 0, "max": 1 }
  },
  "rate_limit_per_hour": 60,
  "endpoints": {
    "submit_feedback": "https://seggwat.com/api/v1/agent/{project_key}/feedback",
    "get_receipt": "https://seggwat.com/api/v1/agent/{project_key}/receipts/{id}",
    "discovery": "https://seggwat.com/api/v1/agent/{project_key}/discovery.json"
  }
}

Submitting a Report

POST /api/v1/agent/{project_key}/feedback with a JSON body.

Request Body

Field Required Description
reporter.agent_vendor No Who makes the agent, e.g. anthropic. Defaults to unknown
reporter.agent_product No Agent name, e.g. claude-code. Defaults to the first name/version token of the User-Agent header, or unknown
reporter.agent_version No Agent version. Defaults to the version in that User-Agent token
subject.surface Yes What the agent was using: endpoint path, docs URL, CLI command or SDK method
subject.domain No Domain the surface belongs to, e.g. api.acme.com. Defaults to the host of the project's first allowed origin, or unknown
subject.kind No api_endpoint, docs_page, cli_command, sdk_method or other
subject.product No Product name, if the domain hosts several
signal.category Yes See category mapping
signal.severity No critical, high, medium or low. Defaults to medium
signal.confidence No Number from 0 to 1. Defaults to 0.5
signal.reproducibility No always, sometimes, intermittent or once
content.title Yes Up to 256 characters
content.summary No Up to 4096 characters
content.hypothesis No The agent's guess at the cause. Up to 2048 characters
evidence No Up to 10 items
evidence[].type Yes http_summary, stderr_excerpt, repro_steps, screenshot, log_excerpt or other
evidence[].content Yes Up to 64 KB
evidence[].redacted No true if the agent removed secrets or PII. Defaults to false

Category Mapping

Each report becomes a feedback item. Its type comes from signal.category:

Category Feedback type
bug Bug
quality_degradation Bug
feature_gap Feature
friction Improvement
docs_mismatch Improvement
other Other

Example

Minimal report

Only the three required fields. The reporter comes from the User-Agent header:

bash
curl -X POST "https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/feedback" \
  -H "Content-Type: application/json" \
  -H "User-Agent: claude-code/2.1.0" \
  -d '{
    "subject": { "surface": "GET /v2/orders" },
    "signal": { "category": "docs_mismatch" },
    "content": { "title": "Docs say X-API-Key, but /v2/orders only accepts Authorization: Bearer" }
  }'

Full report

An agent followed the docs, sent X-API-Key, got 401, and only succeeded with Authorization: Bearer:

bash
curl -X POST "https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "reporter": {
      "agent_vendor": "anthropic",
      "agent_product": "claude-code",
      "agent_version": "2.1.0"
    },
    "subject": {
      "surface": "GET /v2/orders",
      "domain": "api.acme.com",
      "kind": "api_endpoint",
      "product": "Acme Orders API"
    },
    "signal": {
      "category": "docs_mismatch",
      "severity": "medium",
      "confidence": 0.9,
      "reproducibility": "always"
    },
    "content": {
      "title": "Docs say X-API-Key, but /v2/orders only accepts Authorization: Bearer",
      "summary": "The authentication page at https://docs.acme.com/auth says to send the key in the X-API-Key header. GET /v2/orders returns 401 with that header. The same key works when sent as Authorization: Bearer <key>.",
      "hypothesis": "v2 endpoints dropped X-API-Key support and the auth page still documents v1 behaviour."
    },
    "evidence": [
      {
        "type": "http_summary",
        "content": "GET /v2/orders\nX-API-Key: [REDACTED]\n-> 401 {\"error\":\"missing_credentials\"}\n\nGET /v2/orders\nAuthorization: Bearer [REDACTED]\n-> 200",
        "redacted": true
      },
      {
        "type": "repro_steps",
        "content": "1. Follow https://docs.acme.com/auth\n2. curl -H 'X-API-Key: $KEY' https://api.acme.com/v2/orders\n3. Observe 401"
      }
    ]
  }'

Responses

201 Created

json
{
  "receipt": {
    "id": "66f5a1c2e4b0a1b2c3d4e5f6",
    "feedback_id": "66f5a1c2e4b0a1b2c3d4e5f6",
    "status": "accepted",
    "evidence_ids": [],
    "created_at": "2026-09-27T10:15:30Z"
  }
}

400 Bad Request

json
{
  "error": "validation_failed",
  "errors": [
    {
      "field": "signal.confidence",
      "error": "out_of_range",
      "message": "signal.confidence must be between 0 and 1"
    }
  ]
}

404 Not Found

json
{
  "error": "not_found",
  "message": "Project not found or agent reports are not enabled"
}

Checking a Receipt

bash
curl "https://seggwat.com/api/v1/agent/YOUR_PROJECT_KEY/receipts/66f5a1c2e4b0a1b2c3d4e5f6"
json
{
  "data": {
    "id": "66f5a1c2e4b0a1b2c3d4e5f6",
    "feedback_id": "66f5a1c2e4b0a1b2c3d4e5f6",
    "observation_id": null,
    "status": "accepted",
    "quality_score": null,
    "duplicate_of": null,
    "created_at": "2026-09-27T10:15:30Z"
  }
}

status is accepted until your team archives the feedback item, then rejected. The receipt id is the feedback item's id. observation_id, quality_score and duplicate_of are always null for now, and evidence_ids is always empty.

Triaging Agent Reports

Agent reports appear in the project's feedback inbox alongside widget feedback, with source Agent Report. Each item shows a metadata panel with the reporter, subject, signal and evidence, and you triage it like any other feedback.

Next Steps

MCP Integration

Let your own agents triage the reports

API Integration

Read and update feedback over the REST API

Navigation