@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/examples/components/ExampleErrorBoundary.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+/**
+ * Props for {@link ExampleErrorBoundary}.
+ */
+export interface ExampleErrorBoundaryProps {
+    /** Child example tree to protect. */
+    children: React.ReactNode;
+}
+interface ExampleErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * Generic error boundary that surfaces render-time exceptions thrown by any
+ * example in the UI instead of leaving a blank screen with a console error.
+ *
+ * Reset it per example by passing a `key` (e.g. the example id) so switching
+ * examples clears a previous error.
+ */
+export declare class ExampleErrorBoundary extends React.Component<ExampleErrorBoundaryProps, ExampleErrorBoundaryState> {
+    /**
+     * Create the boundary with a clean error state.
+     *
+     * @param props - The boundary props.
+     */
+    constructor(props: ExampleErrorBoundaryProps);
+    /**
+     * Capture a thrown error into state so it can be rendered.
+     *
+     * @param error - The error thrown by a descendant.
+     * @returns The next boundary state.
+     */
+    static getDerivedStateFromError(error: Error): ExampleErrorBoundaryState;
+    /**
+     * Log the error for debugging while it is surfaced in the UI.
+     *
+     * @param error - The error thrown by a descendant.
+     */
+    componentDidCatch(error: Error): void;
+    /**
+     * Render either the protected children or the error surface.
+     *
+     * @returns The rendered tree.
+     */
+    render(): React.ReactNode;
+}
+export {};

package/lib/examples/components/ExampleErrorBoundary.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import React from 'react';
+import { Box } from '@datalayer/primer-addons';
+/**
+ * Generic error boundary that surfaces render-time exceptions thrown by any
+ * example in the UI instead of leaving a blank screen with a console error.
+ *
+ * Reset it per example by passing a `key` (e.g. the example id) so switching
+ * examples clears a previous error.
+ */
+export class ExampleErrorBoundary extends React.Component {
+    /**
+     * Create the boundary with a clean error state.
+     *
+     * @param props - The boundary props.
+     */
+    constructor(props) {
+        super(props);
+        this.state = { error: null };
+    }
+    /**
+     * Capture a thrown error into state so it can be rendered.
+     *
+     * @param error - The error thrown by a descendant.
+     * @returns The next boundary state.
+     */
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    /**
+     * Log the error for debugging while it is surfaced in the UI.
+     *
+     * @param error - The error thrown by a descendant.
+     */
+    componentDidCatch(error) {
+        console.error('Example rendering failed:', error);
+    }
+    /**
+     * Render either the protected children or the error surface.
+     *
+     * @returns The rendered tree.
+     */
+    render() {
+        const { error } = this.state;
+        if (!error) {
+            return this.props.children;
+        }
+        return (_jsx(Box, { sx: { p: 4 }, children: _jsxs(Box, { sx: {
+                    p: 3,
+                    border: '1px solid',
+                    borderColor: 'danger.muted',
+                    borderRadius: 2,
+                    bg: 'danger.subtle',
+                    color: 'danger.fg',
+                }, children: [_jsx(Box, { sx: { fontWeight: 600, mb: 2 }, children: "This example failed to load" }), _jsx(Box, { as: "pre", sx: {
+                            m: 0,
+                            whiteSpace: 'pre-wrap',
+                            wordBreak: 'break-word',
+                            fontFamily: 'mono',
+                            fontSize: 0,
+                        }, children: error.message || String(error) })] }) }));
+    }
+}

package/lib/examples/components/haiku/haiku-card.css

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+/* Loaded on demand from the agent spec's frontend_render_tools css field. */
+/* display: contents keeps the wrapper transparent so it adds no padding or
+   box around the card and preserves the card's own margins. */
+.dla-agui-render-haiku-card {
+  display: contents;
+}

package/lib/examples/components/weather/weather-card.css

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+/* Loaded on demand from the agent spec's frontend_render_tools css field. */
+/* display: contents keeps the wrapper transparent so it adds no padding or
+   box around the card and preserves the card's own margins. */
+.dla-agui-render-weather-card {
+  display: contents;
+}

package/lib/examples/example-selector.js

@@ -64,10 +64,11 @@ function makeEntry(id, loader, description, tags) {
  */
 export const EXAMPLE_ENTRIES = [
     makeEntry('HomeExample', () => import('./HomeExample'), 'Browse all available examples with search and quick navigation.', ['home', 'navigation']),
-    makeEntry('A2UiComponentGalleryExample', () => import('./A2UiComponentGalleryExample'), 'Gallery showcasing A2UI component patterns.'),
+    makeEntry('A2UiComponentsGalleryExample', () => import('./A2UiComponentsGalleryExample'), 'Consolidated A2UI components gallery with Primer-themed color modes.'),
     makeEntry('A2UiContactCardExample', () => import('./A2UiContactCardExample'), 'A2UI example rendering contact card interactions.'),
     makeEntry('A2UiRestaurantExample', () => import('./A2UiRestaurantExample'), 'A2UI restaurant flow example.'),
     makeEntry('A2UiViewerExample', () => import('./A2UiViewerExample'), 'A2UI viewer integration example.'),
+    makeEntry('A2UiAgentExample', () => import('./A2UiAgentExample'), 'A2UI Agent with built-in chat component and Python A2UI extension surface.'),
     makeEntry('AgUiAgenticExample', () => import('./AgUiAgenticExample'), 'AG-UI agentic workflow example.'),
     makeEntry('AgUiBackendToolRenderingExample', () => import('./AgUiBackendToolRenderingExample'), 'AG-UI backend tool rendering example.'),
     makeEntry('AgUiHaikuGenUiExample', () => import('./AgUiHaikuGenUiExample'), 'AG-UI generative UI Haiku example.'),
@@ -87,6 +88,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentGuardrailsExample', () => import('./AgentGuardrailsExample'), 'Guardrails and safety checks for agent runs.'),
     makeEntry('AgentHooksExample', () => import('./AgentHooksExample'), 'Pre-hooks and post-hooks lifecycle execution example.'),
     makeEntry('AgentInferenceProviderExample', () => import('./AgentInferenceProviderExample'), 'Switch local and datalayer inference providers with live low-level provider events.', ['example', 'agent', 'inference', 'provider', 'runtime']),
+    makeEntry('AgentLoopExample', () => import('./AgentLoopExample'), 'Define and launch an agent execution loop (observe/think/act/evaluate) over a live notebook, driven by generic loop specs.', ['example', 'agent', 'loop', 'notebook', 'agentspecs']),
     makeEntry('AgentToolApprovalsExample', () => import('./AgentToolApprovalsExample'), 'Tool approval workflows and manual decisions.'),
     makeEntry('AgentMemoryExample', () => import('./AgentMemoryExample'), 'Memory-aware conversation and retrieval example.'),
     makeEntry('AgentSkillsExample', () => import('./AgentSkillsExample'), 'Skills discovery, execution, and monitoring example.'),

package/lib/examples/hooks/useExampleAgentRuntime.d.ts

@@ -0,0 +1,35 @@
+import type { AgentConfig } from '../../types/config';
+interface UseExampleAgentRuntimeOptions {
+    exampleId: string;
+    agentName: string;
+    specId?: string;
+    environmentName?: string;
+    autoStart?: boolean;
+    autoCreateAgent?: boolean;
+    agentConfig?: AgentConfig;
+}
+interface UseExampleAgentRuntimeResult {
+    location: 'local' | 'cloud';
+    baseUrl: string;
+    agentId?: string;
+    agentBaseUrl?: string;
+    status: string;
+    isReady: boolean;
+    error: string | null;
+    createAgent: (config?: AgentConfig) => Promise<{
+        agentId?: string;
+        endpoint?: string;
+        isReady?: boolean;
+    }>;
+    /**
+     * Tear down the agent launched by this hook: delete it on the server and
+     * wipe in-process agent state so a fresh runtime can be launched.
+     */
+    teardown: () => Promise<void>;
+}
+/**
+ * Connects examples to agent runtimes through shared hooks and supports
+ * both local and cloud execution modes.
+ */
+export declare function useExampleAgentRuntime(options: UseExampleAgentRuntimeOptions): UseExampleAgentRuntimeResult;
+export {};

package/lib/examples/hooks/useExampleAgentRuntime.js

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useEffect, useMemo } from 'react';
+import { useAgentRuntimes } from '../../hooks/useAgentRuntimes';
+import { useExampleAgentRuntimesUrl } from '../utils/useExampleAgentRuntimesUrl';
+import { useRuntimeTargetStore } from '../utils/runtimeTargetStore';
+import { agentSummaryStore } from '../utils/agentSummaryStore';
+/**
+ * Connects examples to agent runtimes through shared hooks and supports
+ * both local and cloud execution modes.
+ */
+export function useExampleAgentRuntime(options) {
+    const { exampleId, agentName, specId, environmentName = 'local-agent-runtimes', autoStart = true, autoCreateAgent = true, agentConfig, } = options;
+    const location = useRuntimeTargetStore(state => state.target);
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const isCloud = location === 'cloud';
+    const combinedConfig = useMemo(() => ({
+        name: agentName,
+        agentSpecId: specId,
+        ...agentConfig,
+    }), [agentName, specId, agentConfig]);
+    const { runtime, status, isReady, error, connectToRuntime, createAgent, teardown, } = useAgentRuntimes({
+        agentSpecId: isCloud ? specId : undefined,
+        autoCreateAgent,
+        autoStart: isCloud ? autoStart : false,
+        runtimeCreationTarget: isCloud
+            ? 'backend-services'
+            : 'local-agent-runtimes',
+        runtimeCreationBaseUrl: isCloud ? undefined : baseUrl,
+        agentConfig: combinedConfig,
+    });
+    useEffect(() => {
+        if (isCloud) {
+            return;
+        }
+        connectToRuntime({
+            podName: agentName,
+            environmentName,
+            jupyterBaseUrl: baseUrl,
+        });
+    }, [isCloud, connectToRuntime, agentName, environmentName, baseUrl]);
+    useEffect(() => {
+        agentSummaryStore.getState().setActive({
+            exampleId,
+            agentName,
+            agentId: runtime?.agentId,
+            specId,
+            location,
+            baseUrl: runtime?.agentBaseUrl || baseUrl,
+            status,
+            isReady,
+            error: error || undefined,
+        });
+        return () => {
+            agentSummaryStore.getState().clearActive(exampleId);
+        };
+    }, [
+        exampleId,
+        agentName,
+        runtime?.agentId,
+        runtime?.agentBaseUrl,
+        specId,
+        location,
+        baseUrl,
+        status,
+        isReady,
+        error,
+    ]);
+    return {
+        location,
+        baseUrl,
+        agentId: runtime?.agentId,
+        agentBaseUrl: runtime?.agentBaseUrl,
+        status,
+        isReady,
+        error,
+        createAgent,
+        teardown,
+    };
+}

package/lib/examples/hooks/useSpecRenderToolResult.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import type { ToolCallRenderContext, RenderToolResult } from '../../types/chat';
+import type { FrontendRenderToolSpec } from '../../types/tools';
+/**
+ * Renderer function keyed by a spec's renderer id.
+ *
+ * Receives the tool call context plus the matching spec binding so the example
+ * can build presentation details (such as a CSS class) from the spec instead of
+ * hardcoding them.
+ */
+export type SpecRenderer = (context: ToolCallRenderContext, binding: FrontendRenderToolSpec) => ReactNode;
+/**
+ * Builds a `renderToolResult` from an agent spec's `frontendRenderTools`.
+ *
+ * The example provides only a local map of renderer id to component; the tool
+ * name to match and the CSS file to load are read from the spec, so examples do
+ * not hardcode tool names or CSS filenames.
+ *
+ * @param specId - Agent spec id to read render bindings from.
+ * @param renderers - Local map of renderer id to renderer function.
+ * @returns A render function suitable for the chat components' renderToolResult.
+ */
+export declare function useSpecRenderToolResult(specId: string | undefined, renderers: Record<string, SpecRenderer>): RenderToolResult;
+/**
+ * Derives the CSS class a spec renderer loads for its binding.
+ *
+ * @param binding - The frontend render binding from the spec.
+ * @returns A stable CSS class name based on the renderer id.
+ */
+export declare function specRendererClassName(binding: FrontendRenderToolSpec): string;

package/lib/examples/hooks/useSpecRenderToolResult.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useEffect, useMemo } from 'react';
+import { getAgentspecs } from '../../specs/agents';
+// Lazy importers for example CSS files, resolved by filename from the spec.
+const cssImporters = import.meta.glob('../components/**/*.css');
+/**
+ * Builds a `renderToolResult` from an agent spec's `frontendRenderTools`.
+ *
+ * The example provides only a local map of renderer id to component; the tool
+ * name to match and the CSS file to load are read from the spec, so examples do
+ * not hardcode tool names or CSS filenames.
+ *
+ * @param specId - Agent spec id to read render bindings from.
+ * @param renderers - Local map of renderer id to renderer function.
+ * @returns A render function suitable for the chat components' renderToolResult.
+ */
+export function useSpecRenderToolResult(specId, renderers) {
+    const bindings = useMemo(() => {
+        if (!specId) {
+            return [];
+        }
+        return getAgentspecs(specId)?.frontendRenderTools ?? [];
+    }, [specId]);
+    // Load any CSS files named by the spec bindings.
+    useEffect(() => {
+        for (const binding of bindings) {
+            if (!binding.css) {
+                continue;
+            }
+            const match = Object.keys(cssImporters).find(path => path.endsWith(`/${binding.css}`));
+            if (match) {
+                void cssImporters[match]();
+            }
+        }
+    }, [bindings]);
+    return useMemo(() => {
+        return (context) => {
+            const binding = bindings.find(b => b.tool === context.toolName);
+            if (!binding) {
+                return null;
+            }
+            const renderer = renderers[binding.renderer];
+            if (!renderer) {
+                return null;
+            }
+            return renderer(context, binding);
+        };
+    }, [bindings, renderers]);
+}
+/**
+ * Derives the CSS class a spec renderer loads for its binding.
+ *
+ * @param binding - The frontend render binding from the spec.
+ * @returns A stable CSS class name based on the renderer id.
+ */
+export function specRendererClassName(binding) {
+    return `dla-agui-render-${binding.renderer}`;
+}

package/lib/examples/index.d.ts

@@ -1,7 +1,8 @@
 export { default as AgentspecsExample } from './AgentspecsExample';
-export { default as A2UiComponentGalleryExample } from './A2UiComponentGalleryExample';
+export { default as A2UiComponentsGalleryExample } from './A2UiComponentsGalleryExample';
 export { default as A2UiContactCardExample } from './A2UiContactCardExample';
 export { default as A2UiRestaurantExample } from './A2UiRestaurantExample';
+export { default as A2UiAgentExample } from './A2UiAgentExample';
 export { default as A2UiViewerExample } from './A2UiViewerExample';
 export { default as AgUiAgenticExample } from './AgUiAgenticExample';
 export { default as AgUiBackendToolRenderingExample } from './AgUiBackendToolRenderingExample';
@@ -21,6 +22,7 @@ export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';
 export { default as AgentInferenceProviderExample } from './AgentInferenceProviderExample';
+export { default as AgentLoopExample } from './AgentLoopExample';
 export { default as AgentToolApprovalsExample } from './AgentToolApprovalsExample';
 export { default as AgentMemoryExample } from './AgentMemoryExample';
 export { default as AgentOtelExample } from './AgentOtelExample';

package/lib/examples/index.js

@@ -3,9 +3,10 @@
  * Distributed under the terms of the Modified BSD License.
  */
 export { default as AgentspecsExample } from './AgentspecsExample';
-export { default as A2UiComponentGalleryExample } from './A2UiComponentGalleryExample';
+export { default as A2UiComponentsGalleryExample } from './A2UiComponentsGalleryExample';
 export { default as A2UiContactCardExample } from './A2UiContactCardExample';
 export { default as A2UiRestaurantExample } from './A2UiRestaurantExample';
+export { default as A2UiAgentExample } from './A2UiAgentExample';
 export { default as A2UiViewerExample } from './A2UiViewerExample';
 export { default as AgUiAgenticExample } from './AgUiAgenticExample';
 export { default as AgUiBackendToolRenderingExample } from './AgUiBackendToolRenderingExample';
@@ -25,6 +26,7 @@ export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';
 export { default as AgentInferenceProviderExample } from './AgentInferenceProviderExample';
+export { default as AgentLoopExample } from './AgentLoopExample';
 export { default as AgentToolApprovalsExample } from './AgentToolApprovalsExample';
 export { default as AgentMemoryExample } from './AgentMemoryExample';
 export { default as AgentOtelExample } from './AgentOtelExample';