Skip to Content
How-to guidesHow-to guidesReport an error to your owner

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",
  code: "string",          // short classification, e.g. "upstream_401_after_refresh"
  message: "string",       // one-sentence human-readable narrative
  correlation_id: "string" // from the original error response's report_hint
})

Returns { ok: true, report_id } on success.

The report shows up in the owner’s dashboard at /agent-reports immediately, and (for error / critical severities, if push is enabled) sends a Web Push notification.

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": "...",
  "report_hint": {
    "correlation_id": "uuid",
    "narrative_template": "I tried to {action} and got {error}"
  }
}

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 that correlation_id.

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.

Next

Understand overage