@datalayer/agent-runtimes 1.0.10 → 1.0.18

package/lib/examples/AgentGuardrailsExample.js

@@ -21,7 +21,7 @@ import { Text, Button, Spinner, Heading, Label, Flash, ProgressBar, } from '@pri
 import { ShieldCheckIcon, CheckIcon, XIcon, DotFillIcon, } from '@primer/octicons-react';
 import { Box } from '@datalayer/primer-addons';
 import { buildOtelWebSocketUrl } from '@datalayer/core/lib/otel';
-import { useCoreStore } from '@datalayer/core/lib/state';
+import { useCoreStore } from '../state/substates';
 import { AuthRequiredView, ErrorView } from './components';
 import { ThemedProvider } from './utils/themedProvider';
 import { uniqueAgentId } from './utils/agentId';
@@ -30,15 +30,18 @@ import { getAgentspecs } from '../specs/agents';
 import { subscribeOtelWs } from '../context/otelWsPool';
 import { toMetricValue } from '../hooks/useMonitoring';
 import { useAIAgentsWebSocket } from '../hooks';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 const queryClient = new QueryClient();
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { Chat } from '../chat';
 // ─── Constants ─────────────────────────────────────────────────────────────
 const AGENT_NAME = 'guardrails-example-agent';
 const AGENTSPEC_ID = 'example-guardrails';
-const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 const OTEL_BASE_URL_ENV = import.meta.env.VITE_OTEL_BASE_URL;
-const DATALAYER_RUN_URL_ENV = import.meta.env.DATALAYER_RUN_URL;
+// Consume-side OTEL override (DATALAYER_OTEL_IN_URL). When set, telemetry is
+// read from here instead of VITE_OTEL_BASE_URL (e.g. prod during local dev).
+const OTEL_IN_BASE_URL_ENV = import.meta.env.VITE_OTEL_IN_BASE_URL;
+const DATALAYER_URL_ENV = import.meta.env.VITE_DATALAYER_URL;
 const OTEL_SERVICE_NAME = 'agent-runtimes';
 const COST_RUN_METRIC = 'agent_runtimes.capability.cost.run.usd';
 const COST_CUMULATIVE_METRIC = 'agent_runtimes.capability.cost.cumulative.usd';
@@ -217,11 +220,13 @@ const AgentGuardrailsInner = ({ onLogout, }) => {
     // Tool approval queue
     const [approvals, setApprovals] = useState([]);
     const [approvalLoading, setApprovalLoading] = useState(null);
-    const agentBaseUrl = DEFAULT_LOCAL_BASE_URL;
-    const otelBaseUrl = configuration?.otelRunUrl ||
-        configuration?.runUrl ||
+    const agentBaseUrl = useExampleAgentRuntimesUrl();
+    const otelBaseUrl = configuration?.otelInUrl ||
+        OTEL_IN_BASE_URL_ENV ||
+        configuration?.otelUrl ||
+        configuration?.datalayerUrl ||
         OTEL_BASE_URL_ENV ||
-        DATALAYER_RUN_URL_ENV ||
+        DATALAYER_URL_ENV ||
         'https://prod1.datalayer.run';
     const podName = agentId;
     const chatAuthToken = token === null ? undefined : token;
@@ -420,7 +425,7 @@ const AgentGuardrailsInner = ({ onLogout, }) => {
                 flexDirection: 'column',
                 alignItems: 'center',
                 justifyContent: 'center',
-                height: '100vh',
+                height: '100%',
                 gap: 3,
             }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Launching guardrails example agent..." })] }));
     }
@@ -453,7 +458,7 @@ const AgentGuardrailsInner = ({ onLogout, }) => {
             ? 'attention.fg'
             : 'success.fg';
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [_jsxs(Box, { sx: {
@@ -482,7 +487,7 @@ const AgentGuardrailsInner = ({ onLogout, }) => {
                             ? ` (over by $${overBudgetAmountUsd.toFixed(4)}).`
                             : '.', ' ', "Start a new run or increase the run budget before continuing."] }) })), approvals.map(req => (_jsx(Flash, { variant: "warning", sx: { mx: 3, mt: 2 }, children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsxs(Text, { sx: { flex: 1, fontSize: 1 }, children: [_jsx("strong", { children: req.tool_name }), " requests approval", req.tool_args
                                     ? ` — ${JSON.stringify(req.tool_args).slice(0, 120)}`
-                                    : ''] }), _jsx(Button, { size: "small", variant: "primary", leadingVisual: CheckIcon, onClick: () => handleApprove(req.id), disabled: approvalLoading === req.id, children: "Approve" }), _jsx(Button, { size: "small", variant: "danger", leadingVisual: XIcon, onClick: () => handleReject(req.id), disabled: approvalLoading === req.id, children: "Reject" })] }) }, req.id))), _jsx(Box, { sx: { flex: 1, minHeight: 0 }, children: _jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, authToken: chatAuthToken, title: "Guardrails Agent", brandIcon: _jsx(ShieldCheckIcon, { size: 16 }), placeholder: "Ask something that triggers tools\u2026", description: "Cost guardrail with OTEL-backed gauge and hook-aware approvals (before_tool_execute, after_tool_execute, on_tool_execute_error, deferred_tool_calls)", showHeader: false, showTokenUsage: true, errorBanner: overBudgetBanner, disableInputPrompt: isOverRunBudget, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
+                                    : ''] }), _jsx(Button, { size: "small", variant: "primary", leadingVisual: CheckIcon, onClick: () => handleApprove(req.id), disabled: approvalLoading === req.id, children: "Approve" }), _jsx(Button, { size: "small", variant: "danger", leadingVisual: XIcon, onClick: () => handleReject(req.id), disabled: approvalLoading === req.id, children: "Reject" })] }) }, req.id))), _jsx(Box, { sx: { flex: 1, minHeight: 0 }, children: _jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, authToken: chatAuthToken, title: "Guardrails Agent", brandIcon: _jsx(ShieldCheckIcon, { size: 16 }), placeholder: "Ask something that triggers tools\u2026", description: "Cost guardrail with OTEL-backed gauge and hook-aware approvals (before_tool_execute, after_tool_execute, on_tool_execute_error, deferred_tool_calls)", showHeader: true, showTokenUsage: true, errorBanner: overBudgetBanner, disableInputPrompt: isOverRunBudget, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
                         { title: 'Update CRM', message: 'Update the CRM records for Q3' },
                         {
                             title: 'Trigger before_tool_execute',
@@ -500,7 +505,7 @@ const AgentGuardrailsInner = ({ onLogout, }) => {
 };
 // ─── Sync token to core IAM store ──────────────────────────────────────────
 const syncTokenToIamStore = (token) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token });
     });
 };
@@ -517,7 +522,7 @@ const AgentGuardrailsExample = () => {
     const handleLogout = useCallback(() => {
         clearAuth();
         hasSynced.current = false;
-        import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        import('../state/substates').then(({ iamStore }) => {
             iamStore.setState({ token: undefined });
         });
     }, [clearAuth]);

package/lib/examples/AgentHooksExample.js

@@ -3,13 +3,14 @@ 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 { useEffect, useState } from 'react';
+import { useMemo } from 'react';
 import { Text, Spinner } from '@primer/react';
 import { SyncIcon } from '@primer/octicons-react';
 import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
 import { ThemedProvider } from './utils/themedProvider';
 import { uniqueAgentId } from './utils/agentId';
 import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { ErrorView } from './components';
 import { Chat } from '../chat';
 setupPrimerPortals();
@@ -17,66 +18,24 @@ const AGENTSPEC_ID = 'example-hooks';
 const AGENT_NAME = 'hooks-example-agent';
 const AgentHooksExample = () => {
     const baseUrl = useExampleAgentRuntimesUrl();
-    const [agentId, setAgentId] = useState(null);
-    const [error, setError] = useState(null);
-    const [isCreating, setIsCreating] = useState(true);
-    useEffect(() => {
-        let cancelled = false;
-        const name = uniqueAgentId(AGENT_NAME);
-        const createAgent = async () => {
-            try {
-                const response = await fetch(`${baseUrl}/api/v1/agents`, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({
-                        name,
-                        agent_spec_id: AGENTSPEC_ID,
-                        transport: 'vercel-ai',
-                    }),
-                });
-                if (!response.ok) {
-                    const data = await response
-                        .json()
-                        .catch(() => ({ detail: 'Unknown error' }));
-                    throw new Error(data.detail || `Failed to create agent: ${response.status}`);
-                }
-                const data = await response.json();
-                if (!cancelled) {
-                    setAgentId(data.id);
-                    setIsCreating(false);
-                }
-            }
-            catch (err) {
-                if (!cancelled) {
-                    setError(err instanceof Error ? err.message : 'Failed to create agent');
-                    setIsCreating(false);
-                }
-            }
-        };
-        createAgent();
-        return () => {
-            cancelled = true;
-        };
-    }, [baseUrl]);
-    useEffect(() => {
-        return () => {
-            if (!agentId) {
-                return;
-            }
-            void fetch(`${baseUrl}/api/v1/agents/${encodeURIComponent(agentId)}`, {
-                method: 'DELETE',
-            }).catch(() => {
-                // Ignore teardown failures in example mode.
-            });
-        };
-    }, [agentId, baseUrl]);
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const { agentId, error, status, isReady } = useExampleAgentRuntime({
+        exampleId: 'AgentHooksExample',
+        agentName,
+        specId: AGENTSPEC_ID,
+        agentConfig: {
+            protocol: 'vercel-ai',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
+    const isCreating = !isReady && status !== 'error';
     if (isCreating) {
         return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
                     display: 'flex',
                     flexDirection: 'column',
                     alignItems: 'center',
                     justifyContent: 'center',
-                    height: '100vh',
+                    height: '100%',
                     gap: 3,
                     bg: 'canvas.default',
                 }, children: [_jsx(Spinner, { size: "large" }), _jsxs(Text, { sx: { color: 'fg.muted' }, children: ["Creating agent from ", AGENTSPEC_ID, "..."] })] }) }));

package/lib/examples/AgentInferenceProviderExample.js

@@ -9,12 +9,12 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { Button, Box, Heading, SegmentedControl, Spinner, Text, } from '@primer/react';
 import { ThemedProvider } from './utils/themedProvider';
 import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { Chat } from '../chat';
 import { useAIAgentsWebSocket } from '../hooks';
 const AGENTSPEC_ID = 'example-inference';
 const AGENT_NAME = 'inference-provider-example-agent';
-const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 const queryClient = new QueryClient();
 const nowIso = () => new Date().toISOString();
 const toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
@@ -51,14 +51,14 @@ const AgentInferenceProviderExampleInner = () => {
     const [expandedEventIds, setExpandedEventIds] = useState(() => new Set());
     const currentAgentRef = useRef(null);
     const requestEpochRef = useRef(0);
-    const baseUrl = DEFAULT_LOCAL_BASE_URL;
+    const baseUrl = useExampleAgentRuntimesUrl();
     const inferenceUrl = useMemo(() => {
         if (provider === 'local') {
             return 'local inference';
         }
         const env = import.meta.env ?? {};
         return (env.VITE_DATALAYER_AI_INFERENCE_URL ||
-            env.VITE_DATALAYER_RUN_URL ||
+            env.VITE_DATALAYER_URL ||
             'https://prod1.datalayer.run');
     }, [provider]);
     const authFetch = useCallback((url, init = {}) => {
@@ -248,7 +248,7 @@ const AgentInferenceProviderExampleInner = () => {
                                 borderRadius: 2,
                                 overflow: 'hidden',
                                 bg: 'canvas.default',
-                            }, children: agentId && !isLaunching ? (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, authToken: token ?? undefined, title: "Agent Inference Provider Example", subtitle: `Spec: ${AGENTSPEC_ID}`, placeholder: "Ask the inference provider something...", showHeader: true, showNewChatButton: true, showClearButton: false, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, onMessageSent: content => {
+                            }, children: agentId && !isLaunching ? (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, authToken: token ?? undefined, title: "Agent Inference Provider Example", subtitle: `Spec: ${AGENTSPEC_ID}`, placeholder: "Ask the inference provider something...", showHeader: true, showNewChatButton: true, showClearButton: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, onMessageSent: content => {
                                     appendProviderEvent('provider.request', `Sent message via ${provider}`, {
                                         provider,
                                         agentId,

package/lib/examples/AgentLoopExample.d.ts

@@ -0,0 +1,10 @@
+import { ServiceManager } from '@jupyterlab/services';
+interface AgentLoopExampleInnerProps {
+    serviceManager?: ServiceManager.IManager;
+}
+export declare function AgentLoopExampleInner({ serviceManager, }: AgentLoopExampleInnerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Main example component with Jupyter provider wrapper.
+ */
+export declare function AgentLoopExample(): import("react/jsx-runtime").JSX.Element;
+export default AgentLoopExample;

package/lib/examples/AgentLoopExample.js

@@ -0,0 +1,304 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * AgentLoopExample - Define and launch an agent execution *loop*.
+ *
+ * This example demonstrates the "loop" paradigm (observe → think → act →
+ * evaluate) instead of one-shot prompting. It is fully driven by the generic
+ * loop specifications defined in agentspecs (`src/specs/loops.ts`):
+ *
+ * - Pick any loop spec (Data Analysis, Plan/Execute/Critic, OODA,
+ *   Human-in-the-Loop). The list is read from the loop catalogue, so adding a
+ *   new YAML loop spec automatically makes it available here.
+ * - The agent's system prompt is composed generically from the selected loop's
+ *   objective, phases, constraints, termination policy and human settings — no
+ *   loop-specific code.
+ * - The agent then runs the loop against a live Jupyter notebook, where the
+ *   loop state (dataframes, charts, intermediate results) lives outside the
+ *   model so each iteration stays small and focused.
+ *
+ * To run this example:
+ * 1. Start the agent-runtimes server.
+ * 2. Select this example from the header dropdown (Agent group).
+ *
+ * @module examples/AgentLoopExample
+ */
+import { useEffect, useMemo, useState } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { Notebook, useJupyter } from '@datalayer/jupyter-react';
+import { useNotebookTools } from '../tools/adapters/agent-runtimes/notebookHooks';
+import { ThemedJupyterProvider } from './utils/themedProvider';
+import { ChatSidebar } from '../chat';
+import { DEFAULT_MODEL, listLoops, getLoop, DEFAULT_LOOP } 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 = 'agent-loop-example';
+// Use the imported Matplotlib notebook as the working surface for the loop.
+const NOTEBOOK_CONTENT = MatplotlibNotebook;
+// Default configuration
+const DEFAULT_AGENT_ID = import.meta.env.VITE_AGENT_ID || 'loop-agent-runtime-example';
+/**
+ * Compose an agent system prompt generically from a loop specification.
+ *
+ * This is intentionally spec-driven: every field comes from the loop YAML, so
+ * the same code drives any loop (data analysis, plan/execute/critic, OODA, ...).
+ */
+function buildLoopSystemPrompt(loop) {
+    const lines = [];
+    lines.push(`You are an agent that operates as a control LOOP rather than answering in a single prompt.`);
+    lines.push(`Loop: ${loop.name} (${loop.strategy}).`);
+    if (loop.objective) {
+        lines.push(`Objective: ${loop.objective}`);
+    }
+    if (loop.phases?.length) {
+        lines.push(`Each iteration, execute these phases in order: ${loop.phases.join(' → ')}. ` +
+            `Decide the single best next action each iteration; do not try to solve everything at once.`);
+    }
+    if (loop.constraints?.length) {
+        lines.push(`Constraints you must respect:\n${loop.constraints
+            .map(c => `- ${c}`)
+            .join('\n')}`);
+    }
+    if (loop.termination) {
+        const t = loop.termination;
+        lines.push(`Termination: stop after at most ${t.maxIterations} iterations, or when the goal is reached.`);
+        if (t.successCriteria?.length) {
+            lines.push(`Success criteria:\n${t.successCriteria.map(s => `- ${s}`).join('\n')}`);
+        }
+        if (t.onBlocked) {
+            lines.push(`If blocked: ${t.onBlocked}.`);
+        }
+    }
+    if (loop.human && loop.human.mode !== 'none') {
+        lines.push(`Human-in-the-loop: mode "${loop.human.mode}"` +
+            (loop.human.approvalRequired
+                ? `; request explicit approval before: ${loop.human.approvalFor.join(', ') || 'sensitive actions'}.`
+                : '.'));
+    }
+    lines.push(`Keep loop state (dataframes, charts, intermediate results) in the notebook/runtime, not in the prompt. ` +
+        `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.`);
+    return lines.join('\n\n');
+}
+function getJupyterSandboxUrl(serviceManager) {
+    const envUrl = import.meta.env.VITE_JUPYTER_SANDBOX_URL;
+    if (envUrl) {
+        return envUrl;
+    }
+    const baseUrl = serviceManager?.serverSettings?.baseUrl?.replace(/\/$/, '');
+    if (!baseUrl) {
+        return undefined;
+    }
+    if (baseUrl.includes('token=')) {
+        return baseUrl;
+    }
+    const token = serviceManager?.serverSettings?.token;
+    if (!token) {
+        return baseUrl;
+    }
+    const separator = baseUrl.includes('?') ? '&' : '?';
+    return `${baseUrl}${separator}token=${encodeURIComponent(token)}`;
+}
+function NotebookUI({ serviceManager }) {
+    if (!serviceManager) {
+        return (_jsx(Box, { sx: {
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: '100%',
+                color: 'fg.muted',
+            }, children: "Loading Simple services..." }));
+    }
+    return (_jsx(Notebook, { nbformat: NOTEBOOK_CONTENT, id: NOTEBOOK_ID, serviceManager: serviceManager, height: "100%", cellSidebarMargin: 120, startDefaultKernel: true }));
+}
+/**
+ * A compact, read-only summary of the selected loop specification.
+ */
+function LoopSummary({ loop }) {
+    return (_jsxs(Box, { sx: {
+            mt: 2,
+            p: 2,
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            bg: 'canvas.default',
+            fontSize: 0,
+        }, children: [_jsx(Box, { sx: { display: 'flex', flexWrap: 'wrap', gap: 2, mb: 1 }, children: loop.phases.map((phase, index) => (_jsxs(Box, { sx: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 1,
+                        px: 2,
+                        py: '2px',
+                        borderRadius: 6,
+                        bg: 'accent.subtle',
+                        color: 'accent.fg',
+                        fontWeight: 'bold',
+                    }, children: [index + 1, ". ", phase] }, phase))) }), loop.objective && (_jsxs(Box, { sx: { color: 'fg.muted' }, children: [_jsx("strong", { children: "Objective:" }), " ", loop.objective] })), loop.termination && (_jsxs(Box, { sx: { color: 'fg.muted', mt: 1 }, children: [_jsx("strong", { children: "Max iterations:" }), " ", loop.termination.maxIterations, " \u00B7", ' ', _jsx("strong", { children: "On blocked:" }), " ", loop.termination.onBlocked] }))] }));
+}
+export function AgentLoopExampleInner({ serviceManager, }) {
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const vercelAiEndpoint = `${baseUrl}/api/v1/vercel-ai/${DEFAULT_AGENT_ID}`;
+    const [createRequested, setCreateRequested] = useState(false);
+    // All available loops come from the generated loop catalogue.
+    const loops = useMemo(() => listLoops(), []);
+    const [selectedLoopId, setSelectedLoopId] = useState(DEFAULT_LOOP);
+    const selectedLoop = useMemo(() => getLoop(selectedLoopId) ?? loops[0], [selectedLoopId, loops]);
+    const jupyterSandboxUrl = useMemo(() => getJupyterSandboxUrl(serviceManager), [serviceManager]);
+    const systemPrompt = useMemo(() => buildLoopSystemPrompt(selectedLoop), [selectedLoop]);
+    const { agentId, isReady, status, error, createAgent } = useExampleAgentRuntime({
+        exampleId: 'AgentLoopExample',
+        agentName: DEFAULT_AGENT_ID,
+        autoCreateAgent: false,
+        agentConfig: {
+            name: DEFAULT_AGENT_ID,
+            description: `Loop agent (${selectedLoop.name}) for AgentLoopExample`,
+            protocol: 'vercel-ai',
+            model: DEFAULT_MODEL,
+            systemPrompt,
+            enableCodemode: false,
+            sandboxVariant: 'jupyter',
+            jupyterSandbox: jupyterSandboxUrl,
+        },
+    });
+    // Launch the loop agent once the sandbox is ready, using the loop that was
+    // selected at launch time.
+    useEffect(() => {
+        if (!jupyterSandboxUrl || createRequested || agentId) {
+            return;
+        }
+        setCreateRequested(true);
+        void createAgent({
+            name: DEFAULT_AGENT_ID,
+            description: `Loop agent (${selectedLoop.name}) for AgentLoopExample`,
+            protocol: 'vercel-ai',
+            model: DEFAULT_MODEL,
+            systemPrompt,
+            enableCodemode: false,
+            sandboxVariant: 'jupyter',
+            jupyterSandbox: jupyterSandboxUrl,
+        }).catch(() => {
+            setCreateRequested(false);
+        });
+    }, [
+        jupyterSandboxUrl,
+        createRequested,
+        agentId,
+        createAgent,
+        selectedLoop.name,
+        systemPrompt,
+    ]);
+    const effectiveReady = isReady || status === 'ready';
+    const isLoopSelectorDisabled = createRequested;
+    // Get notebook tools for ChatSidebar
+    const tools = useNotebookTools(NOTEBOOK_ID);
+    // Build Vercel AI protocol config
+    const protocolConfig = useMemo(() => {
+        return {
+            type: 'vercel-ai',
+            endpoint: vercelAiEndpoint,
+            agentId: DEFAULT_AGENT_ID,
+            enableConfigQuery: true,
+            configEndpoint: `${baseUrl}/api/v1/configure`,
+        };
+    }, [baseUrl, vercelAiEndpoint]);
+    // Chat suggestions derived from the selected loop.
+    const suggestions = useMemo(() => [
+        {
+            title: `${selectedLoop.emoji} Run the loop`,
+            message: selectedLoop.objective
+                ? `Run the ${selectedLoop.name}. ${selectedLoop.objective}`
+                : `Run the ${selectedLoop.name} against the data in this notebook.`,
+        },
+        {
+            title: '🔁 Next iteration',
+            message: 'Observe the current notebook state, then decide and execute the single best next step.',
+        },
+        {
+            title: '🎯 Check the goal',
+            message: 'Evaluate the latest result against the objective and success criteria. Are we done? If not, what is missing?',
+        },
+        {
+            title: '📊 Summarize findings',
+            message: 'Summarize the key findings and produce a final, decision-oriented report.',
+        },
+    ], [selectedLoop]);
+    return (_jsx(_Fragment, { children: _jsxs(Box, { sx: {
+                height: 'calc(100vh - 70px)',
+                width: '100vw',
+                display: 'flex',
+                overflow: 'hidden',
+            }, children: [_jsxs(Box, { sx: {
+                        flex: 1,
+                        display: 'flex',
+                        flexDirection: 'column',
+                        overflow: 'hidden',
+                    }, children: [_jsxs(Box, { sx: {
+                                p: 3,
+                                borderBottom: '1px solid',
+                                borderColor: 'border.default',
+                                bg: 'canvas.subtle',
+                            }, children: [_jsxs(Box, { sx: {
+                                        display: 'flex',
+                                        alignItems: 'center',
+                                        justifyContent: 'space-between',
+                                        gap: 3,
+                                        flexWrap: 'wrap',
+                                    }, children: [_jsxs(Box, { children: [_jsxs("h1", { style: { margin: 0, fontSize: '1.5rem' }, children: [selectedLoop.emoji, " Agent Loop Example"] }), _jsx("p", { style: { margin: '8px 0 0', color: 'var(--fgColor-muted)' }, children: "Define and launch an agent execution loop \u2014 observe, think, act, evaluate \u2014 over a live notebook." })] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, title: isLoopSelectorDisabled
+                                                ? 'Loop selector is temporarily disabled while launching the agent'
+                                                : 'Choose a loop', children: [_jsx(Box, { as: "label", sx: { fontSize: 1, fontWeight: 'bold' }, children: "Loop" }), _jsx(Box, { as: "select", value: selectedLoopId, onChange: (e) => setSelectedLoopId(e.target.value), disabled: isLoopSelectorDisabled, "aria-label": "Loop specification", sx: {
+                                                        px: 2,
+                                                        py: '6px',
+                                                        fontSize: 1,
+                                                        borderRadius: 2,
+                                                        border: '1px solid',
+                                                        borderColor: 'border.default',
+                                                        bg: 'canvas.default',
+                                                        color: 'fg.default',
+                                                    }, children: loops.map(loop => (_jsxs("option", { value: loop.id, children: [loop.emoji, " ", loop.name] }, loop.id))) })] })] }), _jsx(LoopSummary, { loop: selectedLoop })] }), _jsx(Box, { sx: {
+                                flex: 1,
+                                display: 'flex',
+                                overflow: 'hidden',
+                                bg: 'canvas.default',
+                                p: 3,
+                            }, children: _jsx(Box, { sx: {
+                                    flex: 1,
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    overflow: 'hidden',
+                                }, children: _jsx(NotebookUI, { serviceManager: serviceManager }) }) })] }), effectiveReady && (_jsx(ChatSidebar, { title: `${selectedLoop.emoji} ${selectedLoop.name}`, protocol: protocolConfig, position: "right", width: 400, clickOutsideToClose: false, showNewChatButton: true, showClearButton: true, showSettingsButton: true, defaultOpen: true, panelProps: {
+                        protocol: protocolConfig,
+                        frontendTools: tools,
+                        useStore: false,
+                        showModelSelector: true,
+                        showToolsMenu: true,
+                        showSkillsMenu: true,
+                        suggestions,
+                    } })), error && (_jsxs(Box, { sx: {
+                        position: 'fixed',
+                        bottom: 20,
+                        right: 20,
+                        padding: 3,
+                        backgroundColor: 'danger.subtle',
+                        color: 'danger.fg',
+                        borderRadius: 2,
+                        maxWidth: 320,
+                        zIndex: 999,
+                    }, children: [_jsx("strong", { children: "Error:" }), " ", error] }))] }) }));
+}
+/**
+ * Main example component with Jupyter provider wrapper.
+ */
+export function AgentLoopExample() {
+    return (_jsx(ThemedJupyterProvider, { children: _jsx(SimpleWrapper, {}) }));
+}
+function SimpleWrapper() {
+    const { serviceManager } = useJupyter();
+    return _jsx(AgentLoopExampleInner, { serviceManager: serviceManager });
+}
+export default AgentLoopExample;

package/lib/examples/AgentMCPExample.js

@@ -15,6 +15,7 @@ import { ThemedProvider } from './utils/themedProvider';
 import { uniqueAgentId } from './utils/agentId';
 import { Chat } from '../chat';
 import { useAIAgentsWebSocket } from '../hooks';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { parseAgentStreamMessage } from '../types/stream';
 import { MCP_STATUS_COLORS, MCP_STATUS_LABELS } from '../types/mcp';
 import { MCP_SERVER_LIBRARY } from '../specs/mcpServers';
@@ -22,7 +23,6 @@ const queryClient = new QueryClient();
 const AGENT_NAME = 'mcp-example-agent';
 // Must match agentspecs/agentspecs/agents/example-mcp.yaml `id`.
 const AGENTSPEC_ID = 'example-mcp';
-const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 /* ── Aggregate MCP status helpers ─────────────────────── */
 function deriveAggregate(servers) {
     if (!servers || servers.length === 0)
@@ -127,7 +127,7 @@ const AgentMCPInner = ({ onLogout }) => {
     const [liveMcpStatus, setLiveMcpStatus] = useState(undefined);
     // Pending approvals are now managed internally by ChatBase via the Zustand
     // agent-runtime store — no local state needed.
-    const agentBaseUrl = DEFAULT_LOCAL_BASE_URL;
+    const agentBaseUrl = useExampleAgentRuntimesUrl();
     const chatAuthToken = token === null ? undefined : token;
     const authFetch = useCallback((url, opts = {}) => fetch(url, {
         ...opts,
@@ -371,7 +371,7 @@ const AgentMCPInner = ({ onLogout }) => {
                 flexDirection: 'column',
                 alignItems: 'center',
                 justifyContent: 'center',
-                height: '100vh',
+                height: '100%',
                 gap: 3,
             }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Launching MCP example agent..." })] }));
     }
@@ -379,7 +379,7 @@ const AgentMCPInner = ({ onLogout }) => {
         return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
     }
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [isReconnectedAgent && (_jsx(Box, { sx: {
@@ -387,7 +387,7 @@ const AgentMCPInner = ({ onLogout }) => {
                     py: 1,
                     borderBottom: '1px solid',
                     borderColor: 'border.default',
-                }, children: _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "Agent already running - reconnected." }) })), _jsxs(Box, { sx: { flex: 1, minHeight: 0, display: 'flex' }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0 }, children: _jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, authToken: chatAuthToken, title: "MCP Demo Agent", brandIcon: _jsx(GlobeIcon, { size: 16 }), placeholder: "Ask the agent to search the web or explore GitHub...", showHeader: true, showNewChatButton: true, showClearButton: false, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${agentBaseUrl}/api/v1/history`, mcpStatusData: mcpStatusData, showToolApprovalBanner: true, headerActions: _jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: _jsxs(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: ["MCP Tools: ", totalTools] }) }), suggestions: [
+                }, children: _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "Agent already running - reconnected." }) })), _jsxs(Box, { sx: { flex: 1, minHeight: 0, display: 'flex' }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0 }, children: _jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, authToken: chatAuthToken, title: "MCP Demo Agent", brandIcon: _jsx(GlobeIcon, { size: 16 }), placeholder: "Ask the agent to search the web or explore GitHub...", showHeader: true, showNewChatButton: true, showClearButton: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${agentBaseUrl}/api/v1/history`, mcpStatusData: mcpStatusData, showToolApprovalBanner: true, headerActions: _jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: _jsxs(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: ["MCP Tools: ", totalTools] }) }), suggestions: [
                                 {
                                     title: '🔍 Search the web',
                                     message: 'Search the web for recent news about AI agents.',
@@ -453,7 +453,7 @@ const AgentMCPInner = ({ onLogout }) => {
                                                                 }, children: [_jsx(ToolsIcon, { size: 12 }), _jsxs(Text, { children: [_jsx("strong", { children: "Tools:" }), " Individual capabilities exposed by each server (search, fetch, etc.)"] })] })] })] })] }))] })] })] })] }));
 };
 const syncTokenToIamStore = (token) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token });
     });
 };
@@ -469,7 +469,7 @@ const AgentMCPExample = () => {
     const handleLogout = useCallback(() => {
         clearAuth();
         hasSynced.current = false;
-        import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        import('../state/substates').then(({ iamStore }) => {
             iamStore.setState({ token: undefined });
         });
     }, [clearAuth]);

package/lib/examples/AgentMemoryExample.js

@@ -162,7 +162,7 @@ const AgentMemoryInner = ({ onLogout }) => {
                 flexDirection: 'column',
                 alignItems: 'center',
                 justifyContent: 'center',
-                height: '100vh',
+                height: '100%',
                 gap: 3,
             }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Launching local memory-enabled agent\u2026" })] }));
     }
@@ -171,7 +171,7 @@ const AgentMemoryInner = ({ onLogout }) => {
     }
     // ── Main layout ──────────────────────────────────────────────────────────
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [_jsxs(Box, { sx: {
@@ -244,7 +244,7 @@ const AgentMemoryInner = ({ onLogout }) => {
 };
 // ─── Sync token to core IAM store ──────────────────────────────────────────
 const syncTokenToIamStore = (token) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token });
     });
 };
@@ -261,7 +261,7 @@ const AgentMemoryExample = () => {
     const handleLogout = useCallback(() => {
         clearAuth();
         hasSynced.current = false;
-        import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        import('../state/substates').then(({ iamStore }) => {
             iamStore.setState({ token: undefined });
         });
     }, [clearAuth]);