@datalayer/agent-runtimes 1.0.10 → 1.0.18

package/lib/examples/A2UiAgentExample.js

@@ -0,0 +1,442 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A2UiAgentExample
+ *
+ * A comprehensive, real-world A2UI generative-UI example. The agent
+ * (agentspec: `example-a2ui-agent`) exposes a single backend tool,
+ * `render_a2ui_surface`, that turns a natural-language request into a
+ * validated A2UI v0.9 surface (createSurface + updateComponents +
+ * updateDataModel). The frontend renders the returned messages live:
+ *
+ * - INLINE in the chat as a compact confirmation card.
+ * - In the main canvas as a fully interactive A2UI surface (forms, cards,
+ *   choice pickers, sliders, date pickers, ...).
+ *
+ * Submitting the rendered surface emits an A2UI client action which we display
+ * in a "Submitted values" panel, closing the generate → interact loop.
+ *
+ * This mirrors the working tool-based generative UI pattern (see
+ * AgUiHaikuGenUiExample) but renders A2UI surfaces instead of bespoke cards.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
+import { Button, Spinner, Text } from '@primer/react';
+import { basicCatalog } from '@a2ui/react/v0_9';
+import { A2UI_RENDER_SCOPE_SX, A2uiSurfaceComposed } from '../components/a2ui';
+import { ThemedProvider } from './utils/themedProvider';
+import { A2uiMarkdownProvider } from './utils/a2uiMarkdownProvider';
+import { useA2uiProcessor } from './utils/a2ui';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
+import { uniqueAgentId } from './utils/agentId';
+import { useSpecRenderToolResult, specRendererClassName, } from './hooks/useSpecRenderToolResult';
+import { Chat } from '../chat';
+setupPrimerPortals();
+const AGENT_NAME = 'a2ui-agent';
+const AGENTSPEC_ID = 'example-a2ui-agent';
+const SUGGESTIONS = [
+    {
+        title: 'Support ticket intake',
+        message: 'Build a support ticket intake form with category, priority and a description.',
+    },
+    {
+        title: 'Trip booking',
+        message: 'Create a trip booking form with destination, dates, travelers and budget.',
+    },
+    {
+        title: 'Feedback survey',
+        message: 'Generate a customer feedback survey with a rating slider and comments.',
+    },
+    {
+        title: 'Product configurator',
+        message: 'Make a product configurator for a laptop with CPU, RAM and add-ons.',
+    },
+];
+/**
+ * Whether a submitted form value should count as "not provided" for the
+ * purpose of required-field validation. Handles the value shapes the A2UI
+ * basic catalog emits: strings (text/email), arrays (choice), booleans
+ * (checkbox).
+ */
+function isEmptyValue(value) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    if (typeof value === 'string') {
+        return value.trim() === '';
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+    if (typeof value === 'boolean') {
+        return value === false;
+    }
+    return false;
+}
+/**
+ * Basic email format check (matches the intent of the backend `email` field
+ * type). Intentionally permissive: requires `local@domain.tld` with no spaces.
+ */
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Validate a single submitted value against its backend-provided rule. Returns
+ * a human-readable error message, or `null` when the value is acceptable.
+ */
+function validateFieldValue(rule, value) {
+    const empty = isEmptyValue(value);
+    if (empty) {
+        // Optional fields left blank are fine; only required ones fail here.
+        return rule.required ? `${rule.label} is required.` : null;
+    }
+    if (rule.format === 'email' &&
+        typeof value === 'string' &&
+        !EMAIL_PATTERN.test(value.trim())) {
+        return `${rule.label} must be a valid email address.`;
+    }
+    if (rule.pattern && typeof value === 'string') {
+        let matches = true;
+        try {
+            matches = new RegExp(rule.pattern).test(value.trim());
+        }
+        catch {
+            matches = true; // Ignore malformed patterns rather than blocking.
+        }
+        if (!matches) {
+            return `${rule.label} is not in the expected format.`;
+        }
+    }
+    if (rule.minLength !== undefined &&
+        typeof value === 'string' &&
+        value.trim().length < rule.minLength) {
+        return `${rule.label} must be at least ${rule.minLength} characters.`;
+    }
+    if (rule.type === 'slider' && typeof value === 'number') {
+        if (rule.min !== undefined && value < rule.min) {
+            return `${rule.label} must be at least ${rule.min}.`;
+        }
+        if (rule.max !== undefined && value > rule.max) {
+            return `${rule.label} must be at most ${rule.max}.`;
+        }
+    }
+    return null;
+}
+/**
+ * Normalize a backend tool result (object or JSON string) into A2UI messages,
+ * rewriting the catalog id to the frontend catalog so the renderer accepts it.
+ */
+function extractToolResult(result) {
+    if (!result) {
+        return null;
+    }
+    let obj = result;
+    if (typeof result === 'string') {
+        try {
+            obj = JSON.parse(result);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof obj !== 'object' ||
+        obj === null ||
+        !Array.isArray(obj.messages)) {
+        return null;
+    }
+    const parsed = obj;
+    const messages = (parsed.messages ?? []).map(message => {
+        const payload = message;
+        if (payload.createSurface &&
+            payload.createSurface.catalogId !== basicCatalog.id) {
+            return {
+                ...payload,
+                createSurface: {
+                    ...payload.createSurface,
+                    catalogId: basicCatalog.id,
+                },
+            };
+        }
+        return message;
+    });
+    return { ...parsed, messages };
+}
+/**
+ * Renders a fully interactive A2UI surface *inline* in the chat transcript.
+ *
+ * Uses its own `useA2uiProcessor` instance (independent from the canvas
+ * processor) so the same generated surface can be filled in and submitted from
+ * both places. Messages are processed once on mount.
+ */
+const InlineA2uiSurface = ({ messages, onAction, validationError }) => {
+    const { surfaces, processMessages, resetSurfaces, themeStyle } = useA2uiProcessor(onAction);
+    const processedRef = useRef(false);
+    useEffect(() => {
+        if (processedRef.current) {
+            return;
+        }
+        processedRef.current = true;
+        resetSurfaces();
+        processMessages(messages);
+    }, [messages, processMessages, resetSurfaces]);
+    if (surfaces.length === 0) {
+        return null;
+    }
+    return (_jsxs(Box, { style: themeStyle, sx: {
+            ...A2UI_RENDER_SCOPE_SX,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 2,
+        }, children: [validationError && (_jsx(Box, { role: "alert", sx: {
+                    px: 3,
+                    py: 2,
+                    borderRadius: 2,
+                    bg: 'danger.subtle',
+                    border: '1px solid',
+                    borderColor: 'danger.muted',
+                    color: 'danger.fg',
+                    fontSize: 1,
+                }, children: validationError })), surfaces.map(surface => (_jsx(Box, { sx: {
+                    border: '1px solid',
+                    borderColor: 'border.default',
+                    borderRadius: 2,
+                    p: 3,
+                    bg: 'canvas.default',
+                }, children: _jsx(A2uiSurfaceComposed, { surface: surface }) }, surface.id)))] }));
+};
+const A2UiAgentExample = () => {
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const { agentId, error: chatError, status, isReady, } = useExampleAgentRuntime({
+        exampleId: 'A2UiAgentExample',
+        agentName,
+        specId: AGENTSPEC_ID,
+        agentConfig: {
+            protocol: 'ag-ui',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
+    const isCreatingChat = !isReady && status !== 'error';
+    const [surfaceTitle, setSurfaceTitle] = useState(null);
+    const [submissions, setSubmissions] = useState([]);
+    const [pendingPrompt, setPendingPrompt] = useState(undefined);
+    const [validationError, setValidationError] = useState(null);
+    const submissionSeq = useRef(0);
+    // Validation rules per surface id, populated from each tool result so the
+    // (stable) action handler can block submission of an invalid form.
+    const fieldRulesBySurfaceRef = useRef({});
+    // Keep the latest surface title in a ref so the (stable) action handler can
+    // reference it without being re-created on every render.
+    const surfaceTitleRef = useRef(null);
+    useEffect(() => {
+        surfaceTitleRef.current = surfaceTitle;
+    }, [surfaceTitle]);
+    // Handle A2UI actions emitted by the rendered surface (e.g. form submit).
+    const handleAction = useCallback((action) => {
+        if (action.name === 'submit_a2ui_form') {
+            const values = (action.context ?? {});
+            // Block submission when any field fails validation (required, email
+            // format, pattern, length, slider range).
+            const rules = fieldRulesBySurfaceRef.current[action.surfaceId] ?? [];
+            const errors = rules
+                .map(rule => validateFieldValue(rule, values[rule.id]))
+                .filter((message) => message !== null);
+            if (errors.length > 0) {
+                setValidationError({
+                    surfaceId: action.surfaceId,
+                    message: errors.join(' '),
+                });
+                return;
+            }
+            setValidationError(null);
+            submissionSeq.current += 1;
+            const seq = submissionSeq.current;
+            setSubmissions(prev => [
+                {
+                    id: seq,
+                    values,
+                },
+                ...prev,
+            ]);
+            // Feed the submission back to the agent so it replies with a confirmation.
+            const title = surfaceTitleRef.current ?? 'the form';
+            const json = JSON.stringify(values, null, 2);
+            setPendingPrompt(`I just submitted "${title}" (submission #${seq}). Here are the values:\n\n\`\`\`json\n${json}\n\`\`\`\n\nPlease confirm you received them and briefly summarize what happens next.`);
+        }
+    }, []);
+    const { surfaces, processMessages, resetSurfaces, themeStyle } = useA2uiProcessor(handleAction);
+    // Stable ref so the memoized renderer can push surfaces without re-creating.
+    const showSurfaceRef = useRef(() => { });
+    useEffect(() => {
+        showSurfaceRef.current = (messages) => {
+            resetSurfaces();
+            processMessages(messages);
+        };
+    }, [resetSurfaces, processMessages]);
+    const processedToolCallIds = useRef(new Set());
+    const renderers = useMemo(() => ({
+        'a2ui-surface': (context, binding) => {
+            const parsed = context.status === 'complete'
+                ? extractToolResult(context.result)
+                : null;
+            if (context.status === 'complete' &&
+                parsed?.messages &&
+                parsed.messages.length > 0 &&
+                context.toolCallId &&
+                !processedToolCallIds.current.has(context.toolCallId)) {
+                processedToolCallIds.current.add(context.toolCallId);
+                showSurfaceRef.current(parsed.messages);
+                setSurfaceTitle(parsed.title ?? 'A2UI surface');
+                if (parsed.surfaceId) {
+                    fieldRulesBySurfaceRef.current[parsed.surfaceId] =
+                        parsed.fieldRules ?? [];
+                }
+                setValidationError(null);
+            }
+            return (_jsx("div", { className: specRendererClassName(binding), children: context.status === 'complete' &&
+                    parsed?.messages &&
+                    parsed.messages.length > 0 ? (_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsxs(Box, { sx: {
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: 2,
+                                color: 'fg.muted',
+                            }, children: [_jsx(Text, { sx: { fontSize: 2 }, children: "\uD83C\uDF9B\uFE0F" }), _jsx(Text, { sx: { fontWeight: 'bold', color: 'fg.default' }, children: parsed.title ?? 'A2UI surface' }), _jsx(Text, { sx: { fontSize: 0 }, children: "\u00B7 also in the canvas \u2192 fill it in and submit" })] }), _jsx(InlineA2uiSurface, { messages: parsed.messages, onAction: handleAction, validationError: validationError &&
+                                parsed.surfaceId &&
+                                validationError.surfaceId === parsed.surfaceId
+                                ? validationError.message
+                                : null })] })) : (_jsxs(Box, { sx: {
+                        border: '1px solid',
+                        borderColor: 'border.default',
+                        borderRadius: 2,
+                        px: 3,
+                        py: 2,
+                        bg: 'canvas.subtle',
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 2,
+                    }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Rendering A2UI surface..." })] })) }));
+        },
+    }), [handleAction, validationError]);
+    const renderToolResult = useSpecRenderToolResult(AGENTSPEC_ID, renderers);
+    const clearCanvas = useCallback(() => {
+        resetSurfaces();
+        setSurfaceTitle(null);
+        setValidationError(null);
+    }, [resetSurfaces]);
+    return (_jsx(ThemedProvider, { children: _jsx(A2uiMarkdownProvider, { children: _jsxs(Box, { sx: {
+                    minHeight: '100vh',
+                    height: ['auto', 'auto', '100dvh'],
+                    boxSizing: 'border-box',
+                    overflow: ['visible', 'visible', 'hidden'],
+                    display: 'grid',
+                    gridTemplateColumns: [
+                        '1fr',
+                        '1fr',
+                        'minmax(360px, 1fr) minmax(360px, 460px)',
+                    ],
+                    gap: 3,
+                    p: 3,
+                    bg: 'canvas.default',
+                }, children: [_jsxs(Box, { sx: {
+                            display: 'flex',
+                            flexDirection: 'column',
+                            gap: 3,
+                            minHeight: 0,
+                            overflowY: ['visible', 'visible', 'auto'],
+                        }, children: [_jsxs(Box, { sx: {
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    overflow: 'hidden',
+                                }, children: [_jsxs(Box, { sx: {
+                                            px: 3,
+                                            py: 2,
+                                            borderBottom: '1px solid',
+                                            borderColor: 'border.default',
+                                            bg: 'canvas.subtle',
+                                            display: 'flex',
+                                            justifyContent: 'space-between',
+                                            alignItems: 'center',
+                                        }, children: [_jsxs(Box, { children: [_jsx(Text, { as: "h1", sx: { fontSize: 2, fontWeight: 'bold' }, children: "A2UI Agent" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Ask the agent to build a UI \u2014 it renders a live A2UI surface." })] }), surfaces.length > 0 && (_jsx(Button, { size: "small", variant: "invisible", onClick: clearCanvas, children: "Clear" }))] }), _jsx(Box, { style: themeStyle, sx: {
+                                            ...A2UI_RENDER_SCOPE_SX,
+                                            p: 3,
+                                            display: 'flex',
+                                            flexDirection: 'column',
+                                            gap: 3,
+                                        }, children: surfaces.length === 0 ? (_jsxs(Box, { sx: {
+                                                textAlign: 'center',
+                                                py: 6,
+                                                px: 3,
+                                                color: 'fg.muted',
+                                                border: '2px dashed',
+                                                borderColor: 'border.muted',
+                                                borderRadius: 2,
+                                            }, children: [_jsx(Text, { sx: { fontSize: 4, display: 'block', mb: 2 }, children: "\uD83C\uDF9B\uFE0F" }), _jsxs(Text, { sx: { fontSize: 1, display: 'block' }, children: ["No surface yet. Try a suggestion in the chat, e.g.", ' ', _jsxs(Text, { as: "span", sx: { fontStyle: 'italic' }, children: ["\"", SUGGESTIONS[0].message, "\""] })] })] })) : (_jsxs(_Fragment, { children: [surfaceTitle && (_jsx(Text, { sx: { fontWeight: 'bold', color: 'fg.default' }, children: surfaceTitle })), validationError && (_jsx(Box, { role: "alert", sx: {
+                                                        px: 3,
+                                                        py: 2,
+                                                        borderRadius: 2,
+                                                        bg: 'danger.subtle',
+                                                        border: '1px solid',
+                                                        borderColor: 'danger.muted',
+                                                        color: 'danger.fg',
+                                                        fontSize: 1,
+                                                    }, children: validationError.message })), surfaces.map(surface => (_jsx(Box, { sx: {
+                                                        border: '1px solid',
+                                                        borderColor: 'border.default',
+                                                        borderRadius: 2,
+                                                        p: 3,
+                                                        bg: 'canvas.default',
+                                                    }, children: _jsx(A2uiSurfaceComposed, { surface: surface }) }, surface.id)))] })) })] }), submissions.length > 0 && (_jsxs(Box, { sx: {
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    overflow: 'hidden',
+                                }, children: [_jsxs(Box, { sx: {
+                                            px: 3,
+                                            py: 2,
+                                            borderBottom: '1px solid',
+                                            borderColor: 'border.default',
+                                            bg: 'success.subtle',
+                                            display: 'flex',
+                                            justifyContent: 'space-between',
+                                            alignItems: 'center',
+                                        }, children: [_jsx(Text, { sx: { fontWeight: 'bold' }, children: "Submitted values" }), _jsx(Button, { size: "small", variant: "invisible", onClick: () => setSubmissions([]), children: "Clear" })] }), _jsx(Box, { sx: {
+                                            p: 3,
+                                            display: 'flex',
+                                            flexDirection: 'column',
+                                            gap: 2,
+                                        }, children: submissions.map(record => (_jsx(Box, { as: "pre", sx: {
+                                                m: 0,
+                                                p: 2,
+                                                borderRadius: 2,
+                                                bg: 'canvas.subtle',
+                                                border: '1px solid',
+                                                borderColor: 'border.default',
+                                                fontSize: 0,
+                                                overflow: 'auto',
+                                                whiteSpace: 'pre-wrap',
+                                            }, children: JSON.stringify(record.values, null, 2) }, record.id))) })] }))] }), _jsx(Box, { sx: {
+                            position: ['static', 'static', 'sticky'],
+                            top: [0, 0, 3],
+                            alignSelf: ['auto', 'auto', 'start'],
+                            border: '1px solid',
+                            borderColor: 'border.default',
+                            borderRadius: 2,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            height: ['auto', 'auto', 'calc(100vh - 48px)'],
+                            minHeight: [420, 520, 0],
+                            overflow: 'hidden',
+                            bg: 'canvas.default',
+                        }, children: isCreatingChat ? (_jsxs(Box, { sx: {
+                                display: 'flex',
+                                flexDirection: 'column',
+                                alignItems: 'center',
+                                justifyContent: 'center',
+                                height: '100%',
+                                gap: 3,
+                            }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Creating A2UI agent..." })] })) : chatError || !agentId ? (_jsx(Box, { sx: { p: 3 }, children: _jsxs(Text, { sx: { color: 'danger.fg' }, children: ["Failed to initialize chat:", ' ', chatError || 'No agent id returned'] }) })) : (_jsx(Chat, { protocol: "ag-ui", baseUrl: baseUrl, agentId: agentId, title: "A2UI Agent", description: "Generate interactive A2UI surfaces", placeholder: "Describe the UI you want...", showHeader: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, suggestions: SUGGESTIONS, submitOnSuggestionClick: true, pendingPrompt: pendingPrompt, renderToolResult: renderToolResult })) })] }) }) }));
+};
+export default A2UiAgentExample;

package/lib/examples/A2UiComponentsGalleryExample.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const A2UiComponentsGalleryExample: React.FC;
+export default A2UiComponentsGalleryExample;