feat(ui): add A2A error extension (work in progress)

Signed-off-by: Petr Bulánek <bulanek.petr@gmail.com>

Author: PetrBulanek

apps/agentstack-sdk-ts/src/client/a2a/extensions/ui/error.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AUiExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/ui/error/v1';
+
+const schema = z.object({
+  message: z.string(),
+  title: z.string().nullish(),
+  context: z.record(z.string(), z.unknown()).nullish(),
+  stacktrace: z.string().nullish(),
+});
+
+export type ErrorMetadata = z.infer<typeof schema>;
+
+export const errorExtension: A2AUiExtension<typeof URI, ErrorMetadata> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: schema }).partial(),
+  getUri: () => URI,
+};

apps/agentstack-sdk-ts/src/client/api/types.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { z } from 'zod';
+import z from 'zod';
 
 export const contextSchema = z.object({
   id: z.string(),

apps/agentstack-sdk-ts/src/index.ts

@@ -22,6 +22,7 @@ export * from './client/a2a/extensions/services/secrets';
 export * from './client/a2a/extensions/types';
 export * from './client/a2a/extensions/ui/agent-detail';
 export * from './client/a2a/extensions/ui/citation';
+export * from './client/a2a/extensions/ui/error';
 export * from './client/a2a/extensions/ui/form-request';
 export * from './client/a2a/extensions/ui/oauth';
 export * from './client/a2a/extensions/ui/settings';

apps/agentstack-ui/src/api/a2a/client.ts

@@ -9,7 +9,7 @@ import { handleAgentCard, handleInputRequired, handleTaskStatusUpdate } from 'ag
 import { defaultIfEmpty, filter, lastValueFrom, Subject } from 'rxjs';
 import { match } from 'ts-pattern';
 
-import { UnauthenticatedError } from '#api/errors.ts';
+import { A2AExtensionError, UnauthenticatedError } from '#api/errors.ts';
 import type { UIMessagePart } from '#modules/messages/types.ts';
 import type { TaskId } from '#modules/tasks/api/types.ts';
 import { getBaseUrl } from '#utils/api/getBaseUrl.ts';
@@ -18,15 +18,20 @@ import { AGENT_ERROR_MESSAGE } from './constants';
 import { processMessageMetadata, processParts } from './part-processors';
 import type { ChatResult, TaskStatusUpdateResultWithTaskId } from './types';
 import { type ChatParams, type ChatRun, RunResultType } from './types';
-import { createUserMessage, extractTextFromMessage } from './utils';
+import { createUserMessage, extractErrorExtension, extractTextFromMessage } from './utils';
 
 function handleStatusUpdate<UIGenericPart = never>(
   event: TaskStatusUpdateEvent,
   onStatusUpdate?: (event: TaskStatusUpdateEvent) => UIGenericPart[],
 ): (UIMessagePart | UIGenericPart)[] {
   const { message, state } = event.status;
+  const extensionError = extractErrorExtension(message?.metadata);
 
   if (state === 'failed' || state === 'rejected') {
+    if (extensionError) {
+      throw new A2AExtensionError(extensionError);
+    }
+
     const errorMessage = extractTextFromMessage(message) ?? AGENT_ERROR_MESSAGE;
 
     throw new Error(errorMessage);

apps/agentstack-ui/src/api/a2a/utils.ts

@@ -7,6 +7,7 @@ import type { FilePart, FileWithUri, Message, Part, TextPart } from '@a2a-js/sdk
 import {
   type Citation,
   citationExtension,
+  errorExtension,
   extractUiExtensionData,
   trajectoryExtension,
   type TrajectoryMetadata,
@@ -30,6 +31,7 @@ import { PLATFORM_FILE_CONTENT_URL_BASE } from './constants';
 
 export const extractCitation = extractUiExtensionData(citationExtension);
 export const extractTrajectory = extractUiExtensionData(trajectoryExtension);
+export const extractErrorExtension = extractUiExtensionData(errorExtension);
 
 export function extractTextFromMessage(message: Message | undefined) {
   const text = message?.parts

apps/agentstack-ui/src/api/errors.ts

@@ -3,7 +3,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { ApiErrorCode, ApiErrorResponse, ApiValidationErrorResponse, StreamErrorResponse } from './types';
+import type {
+  A2AErrorMetadata,
+  ApiErrorCode,
+  ApiErrorResponse,
+  ApiValidationErrorResponse,
+  StreamErrorResponse,
+} from './types';
 
 export class ErrorWithResponse extends Error {
   name: string;
@@ -64,3 +70,17 @@ export class StreamError extends ErrorWithResponse {
 }
 
 export class UnauthenticatedError extends ErrorWithResponse {}
+
+export class A2AExtensionError extends Error {
+  title: NonNullable<A2AErrorMetadata['title']>;
+  context: A2AErrorMetadata['context'];
+  stacktrace: A2AErrorMetadata['stacktrace'];
+
+  constructor({ message, title, context, stacktrace }: A2AErrorMetadata) {
+    super(message);
+
+    this.title = title ?? 'A2AExtensionError';
+    this.context = context;
+    this.stacktrace = stacktrace;
+  }
+}

apps/agentstack-ui/src/api/types.ts

@@ -5,6 +5,8 @@
 
 import type { components } from './schema';
 
+export type { ErrorMetadata as A2AErrorMetadata } from 'agentstack-sdk';
+
 export type ApiErrorResponse = {
   code: string;
   message?: string;

apps/agentstack-ui/src/api/utils.ts

@@ -8,12 +8,15 @@ import type { ServerSentEventMessage } from 'fetch-event-stream';
 import type { FetchResponse } from 'openapi-fetch';
 import type { MediaType } from 'openapi-typescript-helpers';
 
+import type { QueryMetadataError } from '#contexts/QueryProvider/types.ts';
+import type { Toast } from '#contexts/Toast/toast-context.ts';
 import type { Agent } from '#modules/agents/api/types.ts';
 import { NEXTAUTH_URL, TRUST_PROXY_HEADERS } from '#utils/constants.ts';
 import { isNotNull } from '#utils/helpers.ts';
+import { createSection, joinSections } from '#utils/markdown.ts';
 
-import { ApiError, ApiValidationError, HttpError, UnauthenticatedError } from './errors';
-import type { ApiErrorCode, ApiErrorResponse, ApiValidationErrorResponse } from './types';
+import { A2AExtensionError, ApiError, ApiValidationError, HttpError, UnauthenticatedError } from './errors';
+import type { A2AErrorMetadata, ApiErrorCode, ApiErrorResponse, ApiValidationErrorResponse } from './types';
 
 export function ensureData<T extends Record<string | number, unknown>, O, M extends MediaType>(
   fetchResponse: FetchResponse<T, O, M>,
@@ -111,3 +114,45 @@ export async function getProxyHeaders(headers: Headers, url?: URL) {
 
   return { forwardedHost, forwardedProto, forwarded };
 }
+
+export function buildErrorToast({ metadata = {}, error }: { metadata?: QueryMetadataError; error: unknown }): Toast {
+  const { includeErrorMessage } = metadata;
+
+  const defaults: Partial<Toast> = {
+    kind: 'error',
+    renderMarkdown: true,
+  };
+
+  if (error instanceof A2AExtensionError) {
+    const message = includeErrorMessage ? createA2AErrorMessage(error) : undefined;
+
+    return {
+      ...defaults,
+      title: error.title,
+      message,
+    };
+  }
+
+  const { title = 'An error occurred' } = metadata;
+  const message = joinSections([metadata.message, includeErrorMessage ? getErrorMessage(error) : undefined]);
+
+  return {
+    ...defaults,
+    title,
+    message,
+  };
+}
+
+function createA2AErrorMessage(error: A2AErrorMetadata) {
+  const { context, stacktrace } = error;
+
+  const errorMessage = getErrorMessage(error);
+  const contextMessage = context
+    ? createSection({ heading: 'Context', content: JSON.stringify(context, null, 2) })
+    : undefined;
+  const stacktraceMessage = stacktrace ? createSection({ heading: 'Stacktrace', content: stacktrace }) : undefined;
+
+  const message = joinSections([errorMessage, contextMessage, stacktraceMessage]);
+
+  return message;
+}

apps/agentstack-ui/src/components/ErrorMessage/ErrorMessage.tsx

@@ -6,31 +6,35 @@
 import { ActionableNotification, Button, InlineLoading } from '@carbon/react';
 import type { ReactNode } from 'react';
 
+import { LineClampText } from '#components/LineClampText/LineClampText.tsx';
 import { MarkdownContent } from '#components/MarkdownContent/MarkdownContent.tsx';
 
 import classes from './ErrorMessage.module.scss';
 
 interface Props {
   title?: string;
-  subtitle?: string;
+  message?: string;
   onRetry?: () => void;
   isRefetching?: boolean;
   children?: ReactNode;
 }
 
-export function ErrorMessage({ title, subtitle, onRetry, isRefetching, children }: Props) {
+export function ErrorMessage({ title, message, onRetry, isRefetching }: Props) {
   return (
     <ActionableNotification title={title} kind="error" lowContrast hideCloseButton>
-      {(subtitle || onRetry) && (
+      {(message || onRetry) && (
         <div className={classes.body}>
-          {subtitle && <MarkdownContent>{subtitle}</MarkdownContent>}
+          {message && (
+            <LineClampText lines={4} useBlockElement>
+              <MarkdownContent>{message}</MarkdownContent>
+            </LineClampText>
+          )}
 
           {onRetry && (
             <Button size="sm" onClick={() => onRetry()} disabled={isRefetching}>
               {!isRefetching ? 'Retry' : <InlineLoading description="Retrying&hellip;" />}
             </Button>
           )}
-          {children}
         </div>
       )}
     </ActionableNotification>

apps/agentstack-ui/src/hooks/useHandleError.ts

@@ -6,10 +6,9 @@ import { useRouter } from 'next/navigation';
 import { useCallback } from 'react';
 
 import { UnauthenticatedError } from '#api/errors.ts';
-import { getErrorMessage } from '#api/utils.ts';
+import { buildErrorToast } from '#api/utils.ts';
 import type { QueryMetadata } from '#contexts/QueryProvider/types.ts';
 import { useToast } from '#contexts/Toast/index.ts';
-import { isNotNull } from '#utils/helpers.ts';
 import { routes } from '#utils/router.ts';
 
 export function useHandleError() {
@@ -25,14 +24,9 @@ export function useHandleError() {
         router.replace(routes.signIn({ callbackUrl }));
         console.error(error);
       } else if (errorToast !== false) {
-        const errorMessage = errorToast?.includeErrorMessage ? getErrorMessage(error) : undefined;
+        const toast = buildErrorToast({ metadata: errorToast, error });
 
-        addToast({
-          kind: 'error',
-          title: errorToast?.title ?? 'An error occurred',
-          message: [errorToast?.message, errorMessage].filter(isNotNull).join('\n\n'),
-          renderMarkdown: true,
-        });
+        addToast(toast);
       } else {
         console.error(error);
       }