Skip to main content
Use this guide when a preview, test, deployment, or runtime path fails.

​
Give Agent the failure

Include the error, failing command, URL, or deployment state.

​
Ask for cause before edits

For unclear failures, ask Agent to explain the cause before changing files.

​
Inspect an agent run

Start with the run’s recorded status and error. Then read its events with list_run_events, one page at a time.
  • Failure: Filter by is_error to find the failing event. Then query again with only its span_id to see the call arguments next to the result.
  • Overview: Filter event_class to fact to skip streaming deltas.
  • More events: Pass page_info.next as cursor and keep the same filters.
Use the run ID the API returns. Don’t build a conversation ID from it. A filtered page doesn’t prove the rest of the run succeeded.

​
Improve context and cost

Compare runs with the same input, model, and configuration. Check usage, discovery calls, retrieved knowledge, loaded skills, retries, and the outcome. If usage data is missing, say so. Fix the part that caused the failure: project code, agent instructions, skill guidance, docs, or the platform. Rerun the same request and check both the outcome and any usage claim.

​
Keep the fix scoped

Name the behavior that must stay unchanged.

​
Verify the fix

Ask Agent to rerun the failing path and any related checks.

​
Next