Skip to main content
Treat errors as workflow states with evidence. Store enough context to decide whether to retry, ask for review, or stop.

​
Agent result statuses

StatusMeaningCommon next action
completedThe agent returned a final result.Validate output and persist.
blockedThe site or policy blocked progress.Review status, page evidence, and Debug UI.
needs_confirmationThe run requires host approval.Ask a human or policy service.
failedThe harness or runtime failed.Inspect error details and retry if safe.
cancelledThe run was aborted.Store partial state and stop.

​
SDK pattern

const result = await agent.run({
  startUrl: "https://www.sec.gov/edgar/search/",
  goal: "Find Apple's latest 10-Q filings.",
});

switch (result.status) {
  case "completed":
    await persistResult(result);
    break;
  case "blocked":
  case "needs_confirmation":
    await queueReview(result);
    break;
  default:
    throw new Error(result.error?.message ?? `Agent ended with ${result.status}`);
}

​
Debug checklist

  • Check the final status.
  • Check page URLs and titles in result.steps.
  • Check blocker or CAPTCHA status.
  • Open Debug UI only in a trusted context.
  • Review artifacts and downloads.
  • Tighten the prompt, domain policy, schema, or deterministic checks.
Reference: error codes, limits, and SDK error reference.