feat: structured AgentError + classified error UX with Retry

apps/website/content/docs/ag-ui/api/api-docs.json

@@ -421,7 +421,7 @@
       },
       {
         "name": "error",
-        "type": "Signal<unknown>",
+        "type": "Signal<AgentError<> | undefined>",
         "description": "",
         "optional": false
       },
@@ -455,6 +455,12 @@
         "description": "Discards the assistant message at the given index AND all messages after\nit, then re-runs the agent against the trimmed conversation tail. The\npreceding user message (at index - 1) is preserved and re-submitted as\nthe agent's input. No new user message is added to the history.\n\nThrows if the message at `index` is not 'assistant' role, or if the\nagent is currently loading another response.",
         "optional": false
       },
+      {
+        "name": "retry",
+        "type": "() => Promise<void>",
+        "description": "Re-run the last submitted input after a failure. No-op if a run is already\n in flight or there is nothing to retry. Clears `error` and sets loading.",
+        "optional": false
+      },
       {
         "name": "state",
         "type": "Signal<Record<string, unknown>>",

apps/website/content/docs/chat/api/api-docs.json

@@ -1426,6 +1426,65 @@
     ],
     "methods": []
   },
+  {
+    "name": "AgentError",
+    "kind": "class",
+    "description": "Structured, classified failure surfaced on `Agent.error`. Extends `Error`\n so existing `.message` / `instanceof Error` reads keep working.",
+    "params": [
+      {
+        "name": "init",
+        "type": "object",
+        "description": "",
+        "optional": false
+      }
+    ],
+    "examples": [],
+    "properties": [
+      {
+        "name": "cause",
+        "type": "unknown",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "kind",
+        "type": "AgentErrorKind",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "message",
+        "type": "string",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "name",
+        "type": "string",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "retryable",
+        "type": "boolean",
+        "description": "connection | server | interrupted → true; auth | aborted | non-auth-4xx → false.",
+        "optional": false
+      },
+      {
+        "name": "stack",
+        "type": "string",
+        "description": "",
+        "optional": true
+      },
+      {
+        "name": "status",
+        "type": "number",
+        "description": "",
+        "optional": true
+      }
+    ],
+    "methods": []
+  },
   {
     "name": "ChatApprovalCardComponent",
     "kind": "class",
@@ -2118,12 +2177,6 @@
         "type": "InputSignal<Agent>",
         "description": "",
         "optional": false
-      },
-      {
-        "name": "errorMessage",
-        "type": "Signal<string | null>",
-        "description": "",
-        "optional": false
       }
     ],
     "methods": []
@@ -5354,7 +5407,7 @@
       },
       {
         "name": "error",
-        "type": "Signal<unknown>",
+        "type": "Signal<AgentError<> | undefined>",
         "description": "",
         "optional": false
       },
@@ -5388,6 +5441,12 @@
         "description": "Discards the assistant message at the given index AND all messages after\nit, then re-runs the agent against the trimmed conversation tail. The\npreceding user message (at index - 1) is preserved and re-submitted as\nthe agent's input. No new user message is added to the history.\n\nThrows if the message at `index` is not 'assistant' role, or if the\nagent is currently loading another response.",
         "optional": false
       },
+      {
+        "name": "retry",
+        "type": "() => Promise<void>",
+        "description": "Re-run the last submitted input after a failure. No-op if a run is already\n in flight or there is nothing to retry. Clears `error` and sets loading.",
+        "optional": false
+      },
       {
         "name": "state",
         "type": "Signal<Record<string, unknown>>",
@@ -5648,7 +5707,7 @@
       },
       {
         "name": "error",
-        "type": "Signal<unknown>",
+        "type": "Signal<AgentError<> | undefined>",
         "description": "",
         "optional": false
       },
@@ -5694,6 +5753,12 @@
         "description": "Discards the assistant message at the given index AND all messages after\nit, then re-runs the agent against the trimmed conversation tail. The\npreceding user message (at index - 1) is preserved and re-submitted as\nthe agent's input. No new user message is added to the history.\n\nThrows if the message at `index` is not 'assistant' role, or if the\nagent is currently loading another response.",
         "optional": false
       },
+      {
+        "name": "retry",
+        "type": "() => Promise<void>",
+        "description": "Re-run the last submitted input after a failure. No-op if a run is already\n in flight or there is nothing to retry. Clears `error` and sets loading.",
+        "optional": false
+      },
       {
         "name": "state",
         "type": "Signal<Record<string, unknown>>",
@@ -6307,7 +6372,7 @@
       },
       {
         "name": "error",
-        "type": "WritableSignal<unknown>",
+        "type": "WritableSignal<AgentError<> | undefined>",
         "description": "",
         "optional": false
       },
@@ -6353,6 +6418,12 @@
         "description": "Discards the assistant message at the given index AND all messages after\nit, then re-runs the agent against the trimmed conversation tail. The\npreceding user message (at index - 1) is preserved and re-submitted as\nthe agent's input. No new user message is added to the history.\n\nThrows if the message at `index` is not 'assistant' role, or if the\nagent is currently loading another response.",
         "optional": false
       },
+      {
+        "name": "retry",
+        "type": "() => Promise<void>",
+        "description": "Re-run the last submitted input after a failure. No-op if a run is already\n in flight or there is nothing to retry. Clears `error` and sets loading.",
+        "optional": false
+      },
       {
         "name": "state",
         "type": "WritableSignal<Record<string, unknown>>",
@@ -6411,7 +6482,7 @@
     "properties": [
       {
         "name": "error",
-        "type": "unknown",
+        "type": "AgentError<>",
         "description": "",
         "optional": true
       },
@@ -6990,6 +7061,13 @@
     "signature": "Readonly<Record<string, Type<unknown> | A2uiViewEntry>>",
     "examples": []
   },
+  {
+    "name": "AgentErrorKind",
+    "kind": "type",
+    "description": "",
+    "signature": "\"connection\" | \"auth\" | \"server\" | \"interrupted\" | \"aborted\"",
+    "examples": []
+  },
   {
     "name": "AgentEvent",
     "kind": "type",
@@ -7144,6 +7222,13 @@
     "signature": "Readonly<Record<string, Type<unknown> | RenderViewEntry>>",
     "examples": []
   },
+  {
+    "name": "AGENT_ERROR_MESSAGES",
+    "kind": "const",
+    "description": "Default human-facing copy per kind.",
+    "signature": "Record<AgentErrorKind, string>",
+    "examples": []
+  },
   {
     "name": "cacheplaneMarkdownViews",
     "kind": "const",
@@ -7578,6 +7663,25 @@
     },
     "examples": []
   },
+  {
+    "name": "isAbortError",
+    "kind": "function",
+    "description": "True when `raw` represents a user-requested abort. Shared by adapters + classifier.",
+    "signature": "isAbortError(raw: unknown): boolean",
+    "params": [
+      {
+        "name": "raw",
+        "type": "unknown",
+        "description": "",
+        "optional": false
+      }
+    ],
+    "returns": {
+      "type": "boolean",
+      "description": ""
+    },
+    "examples": []
+  },
   {
     "name": "isAssistantMessage",
     "kind": "function",
@@ -7881,6 +7985,25 @@
     },
     "examples": []
   },
+  {
+    "name": "toAgentError",
+    "kind": "function",
+    "description": "Classify any raw error into a structured AgentError. Idempotent.",
+    "signature": "toAgentError(raw: unknown): AgentError<>",
+    "params": [
+      {
+        "name": "raw",
+        "type": "unknown",
+        "description": "",
+        "optional": false
+      }
+    ],
+    "returns": {
+      "type": "AgentError<>",
+      "description": ""
+    },
+    "examples": []
+  },
   {
     "name": "toClientToolSpecs",
     "kind": "function",

apps/website/content/docs/langgraph/api/api-docs.json

@@ -1439,7 +1439,7 @@
       },
       {
         "name": "error",
-        "type": "Signal<unknown>",
+        "type": "Signal<AgentError<> | undefined>",
         "description": "",
         "optional": false
       },
@@ -1581,6 +1581,12 @@
         "description": "Re-submit the last input to restart the stream.",
         "optional": false
       },
+      {
+        "name": "retry",
+        "type": "() => Promise<void>",
+        "description": "Re-run the last submitted input after a failure. No-op if a run is already\n in flight or there is nothing to retry. Clears `error` and sets loading.",
+        "optional": false
+      },
       {
         "name": "setBranch",
         "type": "(branch: string) => void",
@@ -1861,7 +1867,7 @@
       },
       {
         "name": "error",
-        "type": "WritableSignal<unknown>",
+        "type": "WritableSignal<AgentError<> | undefined>",
         "description": "",
         "optional": false
       },
@@ -2003,6 +2009,12 @@
         "description": "Re-submit the last input to restart the stream.",
         "optional": false
       },
+      {
+        "name": "retry",
+        "type": "() => Promise<void>",
+        "description": "Re-run the last submitted input after a failure. No-op if a run is already\n in flight or there is nothing to retry. Clears `error` and sets loading.",
+        "optional": false
+      },
       {
         "name": "setBranch",
         "type": "(branch: string) => void",