Report an error from the agent to your owner

This article is mostly for the agent (or whoever’s configuring it). It explains when and how an agent should lodge a diagnostic report to its owner — and what happens after.

The MCP tool


report_self_diagnostic({
  severity: "debug" | "info" | "warn" | "error" | "critical", // required
  message: "string",        // required: one-sentence narrative, max 4096 bytes
  code: "string",           // optional short classification, e.g. "reauth_failed"
  platform: "string",       // optional
  endpoint: "string",       // optional
  correlation_id: "uuid",   // optional: from the failing call's report_hint
  context: { }              // optional structured detail, under 16 KiB; no secrets
})

Returns { id, received_at } on success (HTTP 201 from POST /v1/agents/self/diagnostics, which the tool calls).

The report shows up in the owner’s dashboard at /agent-reports immediately. For error and critical severities, the owner is also notified in-app and by email, subject to their minimum-severity and throttle settings. Reports don’t send push notifications.

When to call it

Three good triggers:

1. After a `use_platform` error containing a `report_hint`

When use_platform fails, the error envelope often includes:


{
  "error": "...",
  "correlation_id": "uuid",
  "report_hint": {
    "report_url": "https://api.agentvalet.ai/v1/agents/self/diagnostics",
    "suggested_payload": {
      "severity": "error",
      "code": "permission_denied",
      "message": "<replace with one-sentence agent narrative>",
      "platform": "...",
      "endpoint": "...",
      "correlation_id": "uuid"
    },
    "prompt": "..."
  }
}

That’s AgentValet telling the agent: “this is worth lodging.” The agent should ask the user — “Want me to lodge this with your AgentValet owner?” — and on yes, call report_self_diagnostic with the suggested payload, replacing message with its own narrative.

2. Repeated failures the agent notices itself

If the agent makes the same call three times and it fails each time with the same error, that’s worth a warn severity report — the agent doesn’t need user permission to lodge this one, but should mention it conversationally.

3. Something contextually surprising

The platform returned unexpected data, the agent thinks it’s been given the wrong scope, an action succeeded but the result looks wrong. info or warn severity.

When NOT to call it

Routine errors the agent can recover from itself (transient network blips, retried successfully)
User errors (the user asked the agent to do something the agent can’t or won’t)
Without correlation_id when one was available — including it is what makes the report useful

What the owner sees

/agent-reports shows the report with the agent, platform, severity, code, message, and the correlation_id. Clicking the correlation_id (or copying it into the audit log filter) reveals the originating request — full forensics, response, timings.

The owner can then:

Look at the actual failure (audit log)
Reauth the platform if it’s reauth_needed
Suspend the agent if it looks like the agent is misbehaving
Revoke or add scopes
Reach back out to the agent’s user if needed

Don’t overuse it

Reports are persistent and visible. An agent that lodges 50 reports a day will get ignored. Reserve them for things the human owner couldn’t have learned from the audit log alone — i.e., the agent’s interpretation of what went wrong, in its own words.

Read agent self-reports — the owner’s view
Review the audit log