Read the failure before retrying

agent-trace-brief turns an execution trace into a readable report, with failure points tied to the supplied evidence. It costs 0.02 USDC per call, paid through x402 on Base mainnet.

Use it after a failed run, before deciding what to retry. A routing agent can pass the report to a debugging workflow; a developer can read the same result while investigating an incident.

The boundary is explicit. The brief includes a root-cause hypothesis and labels missing evidence in unknowns. If the trace can't support an explanation, the report should say so.

Send step objects or a text log

Both formats go to the same route: 

POST https://x402.agentutility.ai/agent-trace-brief
Content-Type: application/json

For a run already recorded as structured events, put the step objects in trace. Here's a hypothetical request: 

{
  "trace": [
    {
      "step": 1,
      "tool": "search_web",
      "args": {
        "query": "x402 protocol"
      }
    },
    {
      "step": 2,
      "tool": "parse_result",
      "error": "TypeError: undefined is not an object"
    }
  ],
  "focus": "Why did parse_result fail, and what evidence is missing?"
}

The endpoint accepts an array without prescribing field names for every event. Keep your tool names and recorded outcomes intact so the report can refer to them.

Have a plain-text log? Send it as a string inside the JSON body: 

{
  "trace": "step=1 tool=search_web query=\"x402 protocol\"\nstep=2 tool=parse_result error=\"TypeError: undefined is not an object\"",
  "focus": "Why did parse_result fail, and what evidence is missing?"
}

You don't need to convert those lines into step objects first. The HTTP body still needs valid JSON; a raw text body isn't the accepted request shape.

trace is required and must contain a non-empty array or a non-blank string. Its serialized form is capped at 40,000 characters. Oversized traces receive HTTP 413.

And focus is optional. It's a string capped at 300 characters, useful for directing attention to a particular tool call or suspected timeout. A hint such as “inspect the retrieval step” gives the report a target. It doesn't supply evidence that the log lacks.

Separate the error from its explanation

For the examples above, the recorded failure is the TypeError at step 2. The search result itself isn't present. That's a limit on the diagnosis.

An illustrative brief object for that evidence looks like this. This isn't a captured response: 

{
  "step_summary": [
    {
      "step": 1,
      "action": "Call search_web for x402 protocol",
      "outcome": "Return value isn't recorded"
    },
    {
      "step": 2,
      "action": "Call parse_result",
      "outcome": "TypeError: undefined is not an object"
    }
  ],
  "failure_points": [
    "Step 2: parse_result raised the recorded TypeError."
  ],
  "root_cause_hypothesis": "The trace lacks enough evidence to identify why parse_result encountered this error.",
  "confidence": "low",
  "unknowns": [
    "The value returned by search_web",
    "The arguments passed to parse_result"
  ]
}

The response places this report under brief. Its step_summary follows distinguishable steps in order, while failure_points identifies moments where the trace shows something went wrong.

root_cause_hypothesis holds the explanation supported by that record. confidence expresses confidence in the hypothesis. Treat that label as part of the analysis, not proof that a proposed cause is correct.

But missing evidence deserves its own place. unknowns can flag absent return values or missing timestamps. For a clean trace, the expected hypothesis is “no failure observed.”

Route the report into the next investigation

A useful routing instruction is concrete: 

Call agent-trace-brief when a failed agent run has a recorded trace
and needs review before a retry.

Read brief.failure_points to locate the recorded failure.
Use brief.unknowns to decide which additional evidence to collect.

For the sample run, collect the search response and the parser's input before changing the parser. Attach those records to the next trace review. Keep the original trace beside the brief so whoever handles the incident can check each claim against the recorded events.