@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/examples/LexicalAgentSidebarExample.js

@@ -42,15 +42,15 @@ import { ChatInlinePlugin } from '../lexical/ChatInlinePlugin';
 import { useChatInlineToolbarItems } from '../lexical/useChatInlineToolbarItems';
 import { useLexicalTools } from '../tools/adapters/agent-runtimes/lexicalHooks';
 import { editorConfig } from './lexical/editorConfig';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { DEFAULT_MODEL } from '../specs';
 import '@datalayer/jupyter-lexical/style/index.css';
 import './lexical/lexical-theme.css';
 // Fixed lexical document ID
 const LEXICAL_ID = 'chat-lexical-example';
 // 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 || 'lexical-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) {
@@ -70,70 +70,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 Lexical 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 lexical 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 lexical documents. For document operations, always use the lexical frontend tools so actions happen in the live document UI. Use executeCode only for temporary inspection code that should not modify persisted document content.',
-                        enable_codemode: false,
-                        sandbox_variant: 'jupyter',
-                        jupyter_sandbox: jupyterSandboxUrl,
-                    }),
-                });
-                if (mounted) {
-                    if (response.ok) {
-                        console.warn(`[LexicalAgentSidebarExample] Created agent: ${agentId}`);
-                        setError(null);
-                        setIsReady(true);
-                    }
-                    else if (response.status === 409 || response.status === 400) {
-                        console.warn(`[LexicalAgentSidebarExample] 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('[LexicalAgentSidebarExample] 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 };
-}
 /**
  * Lexical plugin for code highlighting
  */
@@ -144,7 +80,7 @@ function CodeHighlightingPlugin() {
     }, [editor]);
     return null;
 }
-function LexicalEditor({ serviceManager }) {
+function LexicalEditor({ serviceManager, endpoint }) {
     const [floatingAnchorElem, setFloatingAnchorElem] = useState(null);
     const [_isLinkEditMode, setIsLinkEditMode] = useState(false);
     // AI actions registered as toolbar items
@@ -177,24 +113,60 @@ function LexicalEditor({ serviceManager }) {
                                     pointerEvents: 'none',
                                 }, children: "Start typing or use the chat to create content..." }), ErrorBoundary: LexicalErrorBoundary }), _jsx(HistoryPlugin, {}), _jsx(AutoFocusPlugin, {}), _jsx(OnChangePlugin, { onChange: onChange }), _jsx(MarkdownShortcutPlugin, { transformers: TRANSFORMERS }), _jsx(CodeHighlightingPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(LinkPlugin, {}), _jsx(TablePlugin, {}), _jsx(TableCellResizerPlugin, {}), _jsx(JupyterCellPlugin, {}), _jsx(JupyterInputOutputPlugin, {}), _jsx(ImagesPlugin, {}), _jsx(HorizontalRulePlugin, {}), _jsx(EquationsPlugin, {}), _jsx(YouTubePlugin, {}), _jsx(ExcalidrawPlugin, {}), _jsx(CollapsiblePlugin, {}), _jsx(AutoLinkPlugin, {}), _jsx(AutoEmbedPlugin, {}), _jsx(ListMaxIndentLevelPlugin, { maxDepth: 7 }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(ComponentPickerMenuPlugin, {}), _jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode, extraItems: toolbarItems }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] })), _jsx(ChatInlinePlugin, { protocol: {
                                 type: 'vercel-ai',
-                                endpoint: VERCEL_AI_ENDPOINT,
+                                endpoint,
                             }, isOpen: isAiOpen, onClose: closeAi, pendingPrompt: pendingPrompt, onPendingPromptConsumed: clearPendingPrompt })] })] }) }));
 }
 export function ChatLexicalAgentExampleInner({ 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: 'LexicalAgentSidebarExample',
+        agentName: DEFAULT_AGENT_ID,
+        autoCreateAgent: false,
+        agentConfig: {
+            name: DEFAULT_AGENT_ID,
+            description: 'Demo agent for lexical sidebar example',
+            protocol: 'vercel-ai',
+            model: DEFAULT_MODEL,
+            systemPrompt: 'You are a helpful AI assistant that helps users work with lexical documents. For document operations, always use the lexical frontend tools so actions happen in the live document UI. Use executeCode only for temporary inspection code that should not modify persisted document content.',
+            enableCodemode: false,
+            sandboxVariant: 'jupyter',
+            jupyterSandbox: jupyterSandboxUrl,
+        },
+    });
+    useEffect(() => {
+        if (!jupyterSandboxUrl || createRequested || agentId) {
+            return;
+        }
+        setCreateRequested(true);
+        void createAgent({
+            name: DEFAULT_AGENT_ID,
+            description: 'Demo agent for lexical sidebar example',
+            protocol: 'vercel-ai',
+            model: DEFAULT_MODEL,
+            systemPrompt: 'You are a helpful AI assistant that helps users work with lexical documents. For document operations, always use the lexical frontend tools so actions happen in the live document UI. Use executeCode only for temporary inspection code that should not modify persisted document content.',
+            enableCodemode: false,
+            sandboxVariant: 'jupyter',
+            jupyterSandbox: jupyterSandboxUrl,
+        }).catch(() => {
+            setCreateRequested(false);
+        });
+    }, [jupyterSandboxUrl, createRequested, agentId, createAgent]);
+    const effectiveReady = isReady || status === 'ready';
     // Get lexical tools for ChatSidebar
     const tools = useLexicalTools(LEXICAL_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 (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: {
                     height: 'calc(100vh - 70px)',
                     width: '100vw',
@@ -215,7 +187,7 @@ export function ChatLexicalAgentExampleInner({ serviceManager, }) {
                                     display: 'flex',
                                     overflow: 'hidden',
                                     bg: 'canvas.default',
-                                }, children: _jsx(LexicalEditor, { 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(LexicalEditor, { serviceManager: serviceManager, endpoint: vercelAiEndpoint }) })] }), 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: true,

package/lib/examples/NotebookAgentExample.js

@@ -15,13 +15,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * @module examples/NotebookAgentExample
  */
-import React, { useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 import { Box } from '@datalayer/primer-addons';
 import { Notebook } from '@datalayer/jupyter-react';
 import { ThemedJupyterProvider } from './utils/themedProvider';
 // Agent-runtimes imports
 import { ChatFloating } from '../chat';
 import { useNotebookTools } from '../tools/adapters/agent-runtimes/notebookHooks';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 // Import Matplotlib notebook
 import MatplotlibNotebook from './utils/notebooks/Matplotlib.ipynb.json';
 import { DEFAULT_MODEL } from '../specs';
@@ -29,11 +31,7 @@ import { DEFAULT_MODEL } from '../specs';
 const NOTEBOOK_ID = 'agui-notebook-example';
 // Use the imported Matplotlib notebook
 const NOTEBOOK_CONTENT = MatplotlibNotebook;
-// Base URL for agent-runtimes server
-const BASE_URL = 'http://localhost:8765';
 const AGENT_ID = 'notebook-agent-runtime-example';
-// Vercel AI endpoint
-const VERCEL_AI_ENDPOINT = `${BASE_URL}/api/v1/vercel-ai/${AGENT_ID}`;
 function getJupyterSandboxUrl(serviceManager) {
     const envUrl = import.meta.env.VITE_JUPYTER_SANDBOX_URL;
     if (envUrl) {
@@ -53,74 +51,7 @@ function getJupyterSandboxUrl(serviceManager) {
     const separator = baseUrl.includes('?') ? '&' : '?';
     return `${baseUrl}${separator}token=${encodeURIComponent(token)}`;
 }
-/**
- * Hook to ensure the example-agent is aligned with the active notebook runtime.
- * Recreates the agent with jupyter sandbox settings from the Notebook UI.
- */
-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 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(`[AgentRuntimeExample] Created agent: ${agentId}`);
-                        setError(null);
-                        setIsReady(true);
-                    }
-                    else if (response.status === 409 || response.status === 400) {
-                        // Agent already exists; reuse it and continue.
-                        console.warn(`[AgentRuntimeExample] Reusing existing agent: ${agentId}`);
-                        setError(null);
-                        setIsReady(true);
-                    }
-                    else {
-                        const errorData = await response.json().catch(() => ({}));
-                        setError(errorData.detail || `Failed to create agent: ${response.status}`);
-                    }
-                }
-            }
-            catch (err) {
-                if (mounted) {
-                    console.error('[AgentRuntimeExample] Error creating agent:', err);
-                    setError(err instanceof Error ? err.message : 'Failed to connect to server');
-                }
-            }
-        }
-        ensureAgent();
-        return () => {
-            mounted = false;
-        };
-    }, [agentId, baseUrl, jupyterSandboxUrl]);
-    return { isReady, error };
-}
-const NotebookUI = React.memo(function NotebookUI({ serviceManager, }) {
+const NotebookUI = React.memo(function NotebookUI({ serviceManager, onSessionConnection, }) {
     return (_jsxs(Box, { sx: {
             flex: 1,
             display: 'flex',
@@ -138,19 +69,57 @@ const NotebookUI = React.memo(function NotebookUI({ serviceManager, }) {
                     borderRadius: 2,
                     padding: 3,
                     backgroundColor: 'canvas.default',
-                }, children: serviceManager ? (_jsx(ThemedJupyterProvider, { children: _jsx(Notebook, { nbformat: NOTEBOOK_CONTENT, id: NOTEBOOK_ID, serviceManager: serviceManager, height: "calc(100vh - 300px)", cellSidebarMargin: 120, startDefaultKernel: true }) })) : (_jsx(Box, { sx: { padding: 3 }, children: _jsx("p", { children: "Loading service manager..." }) })) })] }));
+                }, children: serviceManager ? (_jsx(ThemedJupyterProvider, { children: _jsx(Notebook, { nbformat: NOTEBOOK_CONTENT, id: NOTEBOOK_ID, serviceManager: serviceManager, onSessionConnection: onSessionConnection, height: "calc(100vh - 300px)", cellSidebarMargin: 120, startDefaultKernel: true }) })) : (_jsx(Box, { sx: { padding: 3 }, children: _jsx("p", { children: "Loading service manager..." }) })) })] }));
 });
 function NotebookWithChat({ serviceManager, }) {
+    const baseUrl = useExampleAgentRuntimesUrl();
     const jupyterSandboxUrl = useMemo(() => getJupyterSandboxUrl(serviceManager), [serviceManager]);
-    // Ensure the agent exists before rendering chat
-    const { isReady, error } = useEnsureAgent(AGENT_ID, BASE_URL, jupyterSandboxUrl);
+    const [createRequested, setCreateRequested] = useState(false);
+    const [notebookKernel, setNotebookKernel] = useState(null);
+    const { agentId, isReady, status, error, createAgent } = useExampleAgentRuntime({
+        exampleId: 'NotebookAgentExample',
+        agentName: AGENT_ID,
+        autoCreateAgent: false,
+        agentConfig: {
+            name: AGENT_ID,
+            description: 'Demo agent for notebook 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: AGENT_ID,
+            description: 'Demo agent for notebook 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';
+    const handleSessionConnection = useCallback((session) => {
+        setNotebookKernel(session?.kernel ?? null);
+    }, []);
     const protocolConfig = useMemo(() => ({
         type: 'vercel-ai',
-        endpoint: VERCEL_AI_ENDPOINT,
+        endpoint: `${baseUrl}/api/v1/vercel-ai/${AGENT_ID}`,
         agentId: AGENT_ID,
         enableConfigQuery: true,
-        configEndpoint: `${BASE_URL}/api/v1/configure`,
-    }), []);
+        configEndpoint: `${baseUrl}/api/v1/configure`,
+    }), [baseUrl]);
     // Get notebook tools for ChatFloating
     const frontendTools = useNotebookTools(NOTEBOOK_ID);
     return (_jsxs(Box, { sx: {
@@ -158,7 +127,7 @@ function NotebookWithChat({ serviceManager, }) {
             width: '100%',
             display: 'flex',
             overflow: 'hidden',
-        }, children: [_jsx(NotebookUI, { serviceManager: serviceManager }), error && (_jsxs(Box, { sx: {
+        }, children: [_jsx(NotebookUI, { serviceManager: serviceManager, onSessionConnection: handleSessionConnection }), error && (_jsxs(Box, { sx: {
                     position: 'fixed',
                     bottom: 20,
                     right: 20,
@@ -167,7 +136,9 @@ function NotebookWithChat({ serviceManager, }) {
                     color: 'danger.fg',
                     borderRadius: 2,
                     maxWidth: 300,
-                }, children: [_jsx("strong", { children: "Error:" }), " ", error] })), isReady && (_jsx(ChatFloating, { protocol: protocolConfig, title: "Notebook AI Agent Runtime", description: "Hi! I can help you edit notebook cells. Try: 'Add a new code cell', 'Run cell 1', or 'Delete the last cell'", defaultOpen: true, defaultViewMode: "panel", position: "bottom-right", frontendTools: frontendTools, useStore: false, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, suggestions: [
+                }, children: [_jsx("strong", { children: "Error:" }), " ", error] })), effectiveReady && (_jsx(ChatFloating, { protocol: protocolConfig, title: "Notebook AI Agent Runtime", description: "Hi! I can help you edit notebook cells. Try: 'Add a new code cell', 'Run cell 1', or 'Delete the last cell'", defaultOpen: true, defaultViewMode: "panel", position: "bottom-right", frontendTools: frontendTools, useStore: false, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, panelProps: {
+                    kernel: notebookKernel,
+                }, suggestions: [
                     {
                         title: 'Add a cell',
                         message: 'Insert a random cell to the notebook',

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 });
         });
     }, []);