@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/examples/NotebookAgentSidebarExample.js

@@ -25,15 +25,15 @@ import { useNotebookTools } from '../tools/adapters/agent-runtimes/notebookHooks
 import { ThemedJupyterProvider } from './utils/themedProvider';
 import { ChatSidebar } from '../chat';
 import { DEFAULT_MODEL } from '../specs';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import MatplotlibNotebook from './utils/notebooks/Matplotlib.ipynb.json';
 // Fixed notebook ID
 const NOTEBOOK_ID = 'chat-notebook-example';
 // Use the imported Matplotlib notebook
 const NOTEBOOK_CONTENT = MatplotlibNotebook;
 // Default configuration
-const DEFAULT_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 const DEFAULT_AGENT_ID = import.meta.env.VITE_AGENT_ID || 'notebook-sidebar-agent-runtime-example';
-const VERCEL_AI_ENDPOINT = `${DEFAULT_BASE_URL}/api/v1/vercel-ai/${DEFAULT_AGENT_ID}`;
 function getJupyterSandboxUrl(serviceManager) {
     const envUrl = import.meta.env.VITE_JUPYTER_SANDBOX_URL;
     if (envUrl) {
@@ -53,70 +53,6 @@ function getJupyterSandboxUrl(serviceManager) {
     const separator = baseUrl.includes('?') ? '&' : '?';
     return `${baseUrl}${separator}token=${encodeURIComponent(token)}`;
 }
-function useEnsureAgent(agentId, baseUrl, jupyterSandboxUrl) {
-    const [isReady, setIsReady] = useState(false);
-    const [error, setError] = useState(null);
-    useEffect(() => {
-        let mounted = true;
-        async function ensureAgent() {
-            try {
-                if (!jupyterSandboxUrl) {
-                    if (mounted) {
-                        setError('Could not detect Jupyter server URL from Notebook service manager.');
-                        setIsReady(false);
-                    }
-                    return;
-                }
-                const response = await fetch(`${baseUrl}/api/v1/agents`, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                    },
-                    body: JSON.stringify({
-                        name: agentId,
-                        description: 'Demo agent for notebook sidebar example',
-                        agent_library: 'pydantic-ai',
-                        transport: 'vercel-ai',
-                        model: DEFAULT_MODEL,
-                        system_prompt: 'You are a helpful AI assistant that helps users work with Jupyter notebooks. For notebook operations, always use the notebook frontend tools (runCell, readAllCells, readCell, insertCell, updateCell, deleteCells) so actions happen in the live notebook UI. Use executeCode only for temporary inspection code that should not modify notebook cells.',
-                        enable_codemode: false,
-                        sandbox_variant: 'jupyter',
-                        jupyter_sandbox: jupyterSandboxUrl,
-                    }),
-                });
-                if (mounted) {
-                    if (response.ok) {
-                        console.warn(`[NotebookAgentSidebarExample] Created agent: ${agentId}`);
-                        setError(null);
-                        setIsReady(true);
-                    }
-                    else if (response.status === 409 || response.status === 400) {
-                        console.warn(`[NotebookAgentSidebarExample] Reusing existing agent: ${agentId}`);
-                        setError(null);
-                        setIsReady(true);
-                    }
-                    else {
-                        const errorData = await response.json().catch(() => ({}));
-                        setError(errorData.detail || `Failed to create agent: ${response.status}`);
-                        setIsReady(false);
-                    }
-                }
-            }
-            catch (err) {
-                if (mounted) {
-                    console.error('[NotebookAgentSidebarExample] Error creating agent:', err);
-                    setError(err instanceof Error ? err.message : 'Failed to connect to server');
-                    setIsReady(false);
-                }
-            }
-        }
-        void ensureAgent();
-        return () => {
-            mounted = false;
-        };
-    }, [agentId, baseUrl, jupyterSandboxUrl]);
-    return { isReady, error };
-}
 function NotebookUI({ serviceManager }) {
     if (!serviceManager) {
         return (_jsx(Box, { sx: {
@@ -130,20 +66,56 @@ function NotebookUI({ serviceManager }) {
     return (_jsx(Notebook, { nbformat: NOTEBOOK_CONTENT, id: NOTEBOOK_ID, serviceManager: serviceManager, height: "100%", cellSidebarMargin: 120, startDefaultKernel: true }));
 }
 export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const vercelAiEndpoint = `${baseUrl}/api/v1/vercel-ai/${DEFAULT_AGENT_ID}`;
+    const [createRequested, setCreateRequested] = useState(false);
     const jupyterSandboxUrl = useMemo(() => getJupyterSandboxUrl(serviceManager), [serviceManager]);
-    const { isReady, error } = useEnsureAgent(DEFAULT_AGENT_ID, DEFAULT_BASE_URL, jupyterSandboxUrl);
+    const { agentId, isReady, status, error, createAgent } = useExampleAgentRuntime({
+        exampleId: 'NotebookAgentSidebarExample',
+        agentName: DEFAULT_AGENT_ID,
+        autoCreateAgent: false,
+        agentConfig: {
+            name: DEFAULT_AGENT_ID,
+            description: 'Demo agent for notebook sidebar example',
+            protocol: 'vercel-ai',
+            model: DEFAULT_MODEL,
+            systemPrompt: 'You are a helpful AI assistant that helps users work with Jupyter notebooks. For notebook operations, always use the notebook frontend tools (runCell, readAllCells, readCell, insertCell, updateCell, deleteCells) so actions happen in the live notebook UI. Use executeCode only for temporary inspection code that should not modify notebook cells.',
+            enableCodemode: false,
+            sandboxVariant: 'jupyter',
+            jupyterSandbox: jupyterSandboxUrl,
+        },
+    });
+    useEffect(() => {
+        if (!jupyterSandboxUrl || createRequested || agentId) {
+            return;
+        }
+        setCreateRequested(true);
+        void createAgent({
+            name: DEFAULT_AGENT_ID,
+            description: 'Demo agent for notebook sidebar example',
+            protocol: 'vercel-ai',
+            model: DEFAULT_MODEL,
+            systemPrompt: 'You are a helpful AI assistant that helps users work with Jupyter notebooks. For notebook operations, always use the notebook frontend tools (runCell, readAllCells, readCell, insertCell, updateCell, deleteCells) so actions happen in the live notebook UI. Use executeCode only for temporary inspection code that should not modify notebook cells.',
+            enableCodemode: false,
+            sandboxVariant: 'jupyter',
+            jupyterSandbox: jupyterSandboxUrl,
+        }).catch(() => {
+            setCreateRequested(false);
+        });
+    }, [jupyterSandboxUrl, createRequested, agentId, createAgent]);
+    const effectiveReady = isReady || status === 'ready';
     // Get notebook tools for ChatSidebar
     const tools = useNotebookTools(NOTEBOOK_ID);
     // Build Vercel AI protocol config
     const protocolConfig = useMemo(() => {
         return {
             type: 'vercel-ai',
-            endpoint: VERCEL_AI_ENDPOINT,
+            endpoint: vercelAiEndpoint,
             agentId: DEFAULT_AGENT_ID,
             enableConfigQuery: true,
-            configEndpoint: `${DEFAULT_BASE_URL}/api/v1/configure`,
+            configEndpoint: `${baseUrl}/api/v1/configure`,
         };
-    }, []);
+    }, [baseUrl, vercelAiEndpoint]);
     return (_jsx(_Fragment, { children: _jsxs(Box, { sx: {
                 height: 'calc(100vh - 70px)',
                 width: '100vw',
@@ -171,7 +143,7 @@ export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
                                     borderColor: 'border.default',
                                     borderRadius: 2,
                                     overflow: 'hidden',
-                                }, children: _jsx(NotebookUI, { serviceManager: serviceManager }) }) })] }), isReady && (_jsx(ChatSidebar, { title: "AI Assistant", protocol: protocolConfig, position: "right", width: 400, showNewChatButton: true, showClearButton: true, showSettingsButton: true, defaultOpen: true, panelProps: {
+                                }, children: _jsx(NotebookUI, { serviceManager: serviceManager }) }) })] }), effectiveReady && (_jsx(ChatSidebar, { title: "AI Assistant", protocol: protocolConfig, position: "right", width: 400, showNewChatButton: true, showClearButton: true, showSettingsButton: true, defaultOpen: true, panelProps: {
                         protocol: protocolConfig,
                         frontendTools: tools,
                         useStore: false,

package/lib/examples/NotebookCollaborationExample.js

@@ -3,11 +3,13 @@ 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 { createDatalayerServiceManager } from '../services/DatalayerServiceManager';
 import { useState, useEffect, useMemo } from 'react';
 import { Checkbox, FormControl, Heading } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { useCoreStore, createDatalayerServiceManager, DatalayerCollaborationProvider, } from '@datalayer/core';
 import { loadJupyterConfig, Notebook } from '@datalayer/jupyter-react';
+import { DatalayerCollaborationProvider } from '../collaboration';
+import { useCoreStore } from '../state';
 import { ThemedJupyterProvider } from './utils/themedProvider';
 import nbformatExample from './utils/notebooks/NotebookExample1.ipynb.json';
 // This corresponds to the notebook ID in the URL when you open an existing notbook in your library
@@ -30,7 +32,7 @@ const NotebookCollaborationExample = (props) => {
                 return;
             }
             // Create DatalayerServiceManager if we have credentials
-            if (configuration?.token && configuration?.runUrl) {
+            if (configuration?.token && configuration?.datalayerUrl) {
                 try {
                     // Now we can pass undefined to use config/defaults
                     const manager = await createDatalayerServiceManager(configuration?.cpuEnvironment, configuration?.credits);
@@ -42,7 +44,7 @@ const NotebookCollaborationExample = (props) => {
                 }
             }
             else {
-                console.warn('Datalayer credentials not configured. Please set runUrl and token.');
+                console.warn('Datalayer credentials not configured. Please set datalayerUrl and token.');
             }
         };
         createManager();
@@ -52,20 +54,20 @@ const NotebookCollaborationExample = (props) => {
         if (!enableCollaboration) {
             return undefined;
         }
-        const runUrl = configuration?.runUrl;
+        const datalayerUrl = configuration?.datalayerUrl;
         const token = configuration?.token;
-        if (!runUrl || !token) {
-            console.warn('Datalayer collaboration enabled but runUrl or token not configured. ' +
+        if (!datalayerUrl || !token) {
+            console.warn('Datalayer collaboration enabled but datalayerUrl or token not configured. ' +
                 'Please configure them in the Datalayer store or environment.');
             return undefined;
         }
         // Create and return the Datalayer collaboration provider
         return new DatalayerCollaborationProvider({
-            runUrl,
+            datalayerUrl,
             token,
         });
     }, [enableCollaboration, configuration]);
-    return (_jsx(ThemedJupyterProvider, { children: _jsxs(Box, { p: 3, children: [_jsx(Heading, { as: "h2", sx: { mb: 3 }, children: "Notebook Collaboration Example" }), _jsx(Box, { sx: { mb: 3 }, children: _jsxs(FormControl, { children: [_jsx(Checkbox, { checked: enableCollaboration, onChange: e => setEnableCollaboration(e.target.checked) }), _jsx(FormControl.Label, { children: "Enable Datalayer Collaboration" })] }) }), (!configuration?.runUrl || !configuration?.token) && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'danger.subtle' }, children: "Warning: Datalayer configuration is missing. Please configure runUrl and token to use DatalayerServiceManager and collaboration features." })), !serviceManager && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'attention.subtle' }, children: "Note: DatalayerServiceManager is not available. Notebook functionality will be limited." })), enableCollaboration ? (_jsxs(Box, { sx: {
+    return (_jsx(ThemedJupyterProvider, { children: _jsxs(Box, { p: 3, children: [_jsx(Heading, { as: "h2", sx: { mb: 3 }, children: "Notebook Collaboration Example" }), _jsx(Box, { sx: { mb: 3 }, children: _jsxs(FormControl, { children: [_jsx(Checkbox, { checked: enableCollaboration, onChange: e => setEnableCollaboration(e.target.checked) }), _jsx(FormControl.Label, { children: "Enable Datalayer Collaboration" })] }) }), (!configuration?.datalayerUrl || !configuration?.token) && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'danger.subtle' }, children: "Warning: Datalayer configuration is missing. Please configure datalayerUrl and token to use DatalayerServiceManager and collaboration features." })), !serviceManager && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'attention.subtle' }, children: "Note: DatalayerServiceManager is not available. Notebook functionality will be limited." })), enableCollaboration ? (_jsxs(Box, { sx: {
                         display: 'flex',
                         gap: 2,
                         flexDirection: 'row',
@@ -95,6 +97,6 @@ const NotebookCollaborationExample = (props) => {
                         border: '1px solid',
                         borderColor: 'border.default',
                         borderRadius: 2,
-                    }, children: serviceManager ? (_jsx(Notebook, { id: NOTEBOOK_ID, height: "calc(100vh - 200px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." })) })), _jsxs(Box, { sx: { mt: 2, fontSize: 1, color: 'fg.subtle' }, children: [_jsx("p", { children: "This example demonstrates how to use Datalayer services with Notebook:" }), _jsxs("ul", { children: [_jsxs("li", { children: [_jsx("strong", { children: "DatalayerServiceManager:" }), " Connects to Datalayer infrastructure for kernel management"] }), _jsxs("li", { children: [_jsx("strong", { children: "DatalayerCollaborationProvider:" }), " Enables real-time collaboration"] }), _jsx("li", { children: "Both require Datalayer credentials (runUrl and token)" }), _jsx("li", { children: "Pass them directly to the base Notebook component" }), _jsx("li", { children: "No wrapper components needed - just create the services and pass them as props" }), _jsx("li", { children: "This shows the explicit, composable pattern for Datalayer integration" })] })] })] }) }));
+                    }, children: serviceManager ? (_jsx(Notebook, { id: NOTEBOOK_ID, height: "calc(100vh - 200px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." })) })), _jsxs(Box, { sx: { mt: 2, fontSize: 1, color: 'fg.subtle' }, children: [_jsx("p", { children: "This example demonstrates how to use Datalayer services with Notebook:" }), _jsxs("ul", { children: [_jsxs("li", { children: [_jsx("strong", { children: "DatalayerServiceManager:" }), " Connects to Datalayer infrastructure for kernel management"] }), _jsxs("li", { children: [_jsx("strong", { children: "DatalayerCollaborationProvider:" }), " Enables real-time collaboration"] }), _jsx("li", { children: "Both require Datalayer credentials (datalayerUrl and token)" }), _jsx("li", { children: "Pass them directly to the base Notebook component" }), _jsx("li", { children: "No wrapper components needed - just create the services and pass them as props" }), _jsx("li", { children: "This shows the explicit, composable pattern for Datalayer integration" })] })] })] }) }));
 };
 export default NotebookCollaborationExample;

package/lib/examples/NotebookExample.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+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.
@@ -17,6 +17,9 @@ const NOTEBOOK_ID = 'notebook-example-1';
 export const JupyterNotebookExample = (props) => {
     const { serviceManager } = props;
     const extensions = useMemo(() => [new CellSidebarExtension({ factory: CellSidebarButton })], []);
-    return (_jsxs(_Fragment, { children: [_jsx(Box, { as: "h1", children: "Jupyter Notebook Example" }), serviceManager && (_jsx(ThemedJupyterProvider, { children: _jsx(Notebook, { id: NOTEBOOK_ID, nbformat: nbformatExample, serviceManager: serviceManager, startDefaultKernel: true, extensions: extensions, Toolbar: NotebookToolbar }) }))] }));
+    if (!serviceManager) {
+        return (_jsxs(Box, { as: "h1", children: ["A Jupyter Notebook", _jsx("div", { children: "Loading..." })] }));
+    }
+    return (_jsxs(ThemedJupyterProvider, { children: [_jsx(Box, { as: "h1", children: "A Jupyter Notebook" }), _jsx(Notebook, { id: NOTEBOOK_ID, nbformat: nbformatExample, serviceManager: serviceManager, startDefaultKernel: true, extensions: extensions, Toolbar: NotebookToolbar })] }));
 };
 export default JupyterNotebookExample;

package/lib/examples/components/AuthRequiredView.js

@@ -14,7 +14,7 @@ import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 export const AuthRequiredView = () => {
     const setAuth = useSimpleAuthStore(s => s.setAuth);
     const syncTokenToIamStore = useCallback((token) => {
-        import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        import('../../state/substates').then(({ iamStore }) => {
             iamStore.setState({ token });
         });
     }, []);

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';