@datalayer/agent-runtimes 1.0.5 → 1.0.6

package/lib/examples/AgentHooksExample.js

@@ -5,16 +5,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useEffect, useState } 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 { ErrorView } from './components';
 import { Chat } from '../chat';
 setupPrimerPortals();
-const BASE_URL = 'http://localhost:8765';
-const AGENT_SPEC_ID = 'demo-hooks';
-const AGENT_NAME = 'hooks-demo';
+const AGENT_SPEC_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);
@@ -23,7 +25,7 @@ const AgentHooksExample = () => {
         const name = uniqueAgentId(AGENT_NAME);
         const createAgent = async () => {
             try {
-                const response = await fetch(`${BASE_URL}/api/v1/agents`, {
+                const response = await fetch(`${baseUrl}/api/v1/agents`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
                     body: JSON.stringify({
@@ -55,19 +57,19 @@ const AgentHooksExample = () => {
         return () => {
             cancelled = true;
         };
-    }, []);
+    }, [baseUrl]);
     useEffect(() => {
         return () => {
             if (!agentId) {
                 return;
             }
-            void fetch(`${BASE_URL}/api/v1/agents/${encodeURIComponent(agentId)}`, {
+            void fetch(`${baseUrl}/api/v1/agents/${encodeURIComponent(agentId)}`, {
                 method: 'DELETE',
             }).catch(() => {
                 // Ignore teardown failures in example mode.
             });
         };
-    }, [agentId]);
+    }, [agentId, baseUrl]);
     if (isCreating) {
         return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
                     display: 'flex',
@@ -82,14 +84,14 @@ const AgentHooksExample = () => {
     if (error || !agentId) {
         return (_jsx(ThemedProvider, { children: _jsx(ErrorView, { error: "Failed to start hooks agent", detail: error || 'No agent ID returned' }) }));
     }
-    return (_jsx(Chat, { protocol: "vercel-ai", baseUrl: BASE_URL, agentId: agentId, title: "Hooks Agent", placeholder: "Ask about lifecycle hooks...", description: "Pre-hook installed 'rich', wrote a marker file, and set hook_name / hook_ran_at / hook_env variables in the sandbox", showHeader: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, height: "100vh", runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+    return (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, title: "Hooks Agent", brandIcon: _jsx(SyncIcon, { size: 16 }), placeholder: "Ask about lifecycle hooks...", description: "Demonstrates lifecycle hooks and pydantic-style tool hooks: before_tool_execute, after_tool_execute, on_tool_execute_error, deferred_tool_calls", showHeader: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, height: "100vh", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, suggestions: [
             {
                 title: 'Read the pre-hook marker file',
                 message: 'Use execute_code to read /tmp/agent_runtimes_pre_hook_demo.txt and show its contents.',
             },
             {
                 title: 'Verify hook variables',
-                message: 'Use execute_code to run this verification:\n```python\nassert isinstance(hook_name, str) and hook_name == "demo-hooks:pre", f"❌ hook_name wrong: {hook_name!r}"\nassert isinstance(hook_ran_at, str) and len(hook_ran_at) > 0, f"❌ hook_ran_at wrong: {hook_ran_at!r}"\nassert isinstance(hook_env, dict) and len(hook_env) > 0, f"❌ hook_env wrong: {hook_env!r}"\nprint("✅ hook_name =", hook_name)\nprint("✅ hook_ran_at =", hook_ran_at)\nprint("✅ hook_env =", hook_env)\n```\nThrow an exception with a ❌ message if any variable is missing or has the wrong type, print ✅ lines if all pass.',
+                message: 'Use execute_code to run this verification:\n```python\nassert isinstance(hook_name, str) and hook_name == "example-hooks:pre", f"❌ hook_name wrong: {hook_name!r}"\nassert isinstance(hook_ran_at, str) and len(hook_ran_at) > 0, f"❌ hook_ran_at wrong: {hook_ran_at!r}"\nassert isinstance(hook_env, dict) and len(hook_env) > 0, f"❌ hook_env wrong: {hook_env!r}"\nprint("✅ hook_name =", hook_name)\nprint("✅ hook_ran_at =", hook_ran_at)\nprint("✅ hook_env =", hook_env)\n```\nThrow an exception with a ❌ message if any variable is missing or has the wrong type, print ✅ lines if all pass.',
             },
             {
                 title: "Verify 'rich' was installed",
@@ -99,6 +101,22 @@ const AgentHooksExample = () => {
                 title: 'Explain the hook lifecycle',
                 message: 'What pre-hooks and post-hooks are configured for this agent, and when does each run?',
             },
+            {
+                title: 'Trigger function + python tool hooks',
+                message: "Call runtime_sensitive_echo with text 'hello' and reason 'audit', then explain which before_tool_execute hooks ran (function and python).",
+            },
+            {
+                title: 'Trigger deny in python hook',
+                message: "Call runtime_sensitive_echo with text 'danger' and reason 'delete notebook', then explain why local Python policy denied it.",
+            },
+            {
+                title: 'Read tool approval audit log',
+                message: 'Use execute_code to show the latest entries from /tmp/agent_runtimes_tool_approvals_audit.jsonl and summarize decision and execution status.',
+            },
+            {
+                title: 'Explain deferred hook handling',
+                message: 'Explain how deferred_tool_calls works with approval-required tools and when inline resolution is used in this run.',
+            },
         ], submitOnSuggestionClick: true }));
 };
 export default AgentHooksExample;

package/lib/examples/AgentInferenceProviderExample.d.ts

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

package/lib/examples/AgentInferenceProviderExample.js

@@ -0,0 +1,329 @@
+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.
+ */
+/// <reference types="vite/client" />
+import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+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 { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
+import { Chat } from '../chat';
+import { useAIAgentsWebSocket } from '../hooks';
+const AGENT_SPEC_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);
+const stringifyPayload = (value) => {
+    if (typeof value === 'string') {
+        return value;
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+};
+const ProviderBadge = ({ provider, }) => (_jsx(Box, { sx: {
+        px: 2,
+        py: '2px',
+        borderRadius: 999,
+        border: '1px solid',
+        borderColor: 'border.default',
+        fontSize: 0,
+        color: 'fg.muted',
+        bg: 'canvas.inset',
+        textTransform: 'uppercase',
+        letterSpacing: '0.03em',
+    }, children: provider }));
+const AgentInferenceProviderExampleInner = () => {
+    const { token } = useSimpleAuthStore();
+    const [provider, setProvider] = useState('local');
+    const [agentId, setAgentId] = useState(null);
+    const [isLaunching, setIsLaunching] = useState(true);
+    const [error, setError] = useState(null);
+    const [providerEvents, setProviderEvents] = useState([]);
+    const [expandedEventIds, setExpandedEventIds] = useState(() => new Set());
+    const currentAgentRef = useRef(null);
+    const requestEpochRef = useRef(0);
+    const baseUrl = DEFAULT_LOCAL_BASE_URL;
+    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 ||
+            'https://prod1.datalayer.run');
+    }, [provider]);
+    const authFetch = useCallback((url, init = {}) => {
+        return fetch(url, {
+            ...init,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                ...(init.headers ?? {}),
+            },
+        });
+    }, [token]);
+    const appendProviderEvent = useCallback((type, summary, payload) => {
+        setProviderEvents(prev => [
+            {
+                id: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+                type,
+                summary,
+                payload: stringifyPayload(payload),
+                createdAt: nowIso(),
+            },
+            ...prev,
+        ]);
+    }, []);
+    const deleteAgent = useCallback(async (id) => {
+        await authFetch(`${baseUrl}/api/v1/agents/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        }).catch(() => {
+            // Best-effort cleanup in example mode.
+        });
+    }, [authFetch, baseUrl]);
+    const launchAgentForProvider = useCallback(async (nextProvider) => {
+        requestEpochRef.current += 1;
+        const requestEpoch = requestEpochRef.current;
+        setIsLaunching(true);
+        setError(null);
+        const previousAgentId = currentAgentRef.current;
+        if (previousAgentId) {
+            await deleteAgent(previousAgentId);
+        }
+        try {
+            const configureResponse = await authFetch(`${baseUrl}/api/v1/configure/inference/provider`, {
+                method: 'PUT',
+                body: JSON.stringify({ provider: nextProvider }),
+            });
+            appendProviderEvent('configure.provider', `Configured runtime inference provider to ${nextProvider}`, {
+                status: configureResponse.status,
+                provider: nextProvider,
+            });
+            const name = uniqueAgentId(`${AGENT_NAME}-${nextProvider}`);
+            const createResponse = await authFetch(`${baseUrl}/api/v1/agents`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    name,
+                    transport: 'vercel-ai',
+                    agent_spec_id: AGENT_SPEC_ID,
+                    inferenceProvider: nextProvider,
+                }),
+            });
+            if (!createResponse.ok) {
+                const detail = await createResponse.text();
+                throw new Error(detail || `Failed to create agent (${createResponse.status})`);
+            }
+            const payload = (await createResponse.json());
+            const nextAgentId = payload.id || name;
+            if (requestEpoch !== requestEpochRef.current) {
+                return;
+            }
+            currentAgentRef.current = nextAgentId;
+            setAgentId(nextAgentId);
+            appendProviderEvent('agent.created', 'Launched local agent runtime', {
+                agentId: nextAgentId,
+                agentSpecId: AGENT_SPEC_ID,
+                inferenceProvider: nextProvider,
+                baseUrl,
+            });
+        }
+        catch (launchError) {
+            if (requestEpoch !== requestEpochRef.current) {
+                return;
+            }
+            setAgentId(null);
+            currentAgentRef.current = null;
+            setError(toErrorMessage(launchError));
+            appendProviderEvent('agent.error', 'Failed to launch agent', {
+                provider: nextProvider,
+                error: toErrorMessage(launchError),
+            });
+        }
+        finally {
+            if (requestEpoch === requestEpochRef.current) {
+                setIsLaunching(false);
+            }
+        }
+    }, [appendProviderEvent, authFetch, baseUrl, deleteAgent]);
+    useEffect(() => {
+        void launchAgentForProvider(provider);
+    }, [launchAgentForProvider, provider]);
+    useEffect(() => {
+        return () => {
+            const existing = currentAgentRef.current;
+            if (existing) {
+                void deleteAgent(existing);
+            }
+        };
+    }, [deleteAgent]);
+    const onProviderChange = useCallback((next) => {
+        setProvider(next);
+    }, []);
+    useAIAgentsWebSocket({
+        enabled: Boolean(agentId) && !isLaunching,
+        baseUrl,
+        path: '/api/v1/tool-approvals/ws',
+        queryParams: agentId ? { agent_id: agentId } : undefined,
+        onMessage: message => {
+            const eventType = typeof message.type === 'string'
+                ? message.type
+                : typeof message.event === 'string'
+                    ? message.event
+                    : 'stream.message';
+            appendProviderEvent('provider.stream', `Received ${eventType}`, {
+                provider,
+                agentId,
+                message: message.raw ?? message,
+            });
+        },
+        reconnectDelayMs: attempt => Math.min(1000 * 2 ** Math.max(0, attempt - 1), 10000),
+    });
+    const orderedProviderEvents = useMemo(() => [...providerEvents].sort((a, b) => b.createdAt.localeCompare(a.createdAt)), [providerEvents]);
+    const toggleEventExpanded = useCallback((eventId) => {
+        setExpandedEventIds(prev => {
+            const next = new Set(prev);
+            if (next.has(eventId)) {
+                next.delete(eventId);
+            }
+            else {
+                next.add(eventId);
+            }
+            return next;
+        });
+    }, []);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
+                height: '100%',
+                minHeight: 0,
+                width: '100%',
+                display: 'grid',
+                gridTemplateColumns: ['1fr', '1fr', 'minmax(680px, 1fr) 420px'],
+                gridTemplateRows: 'minmax(0, 1fr)',
+                overflow: 'hidden',
+                bg: 'canvas.default',
+            }, children: [_jsxs(Box, { sx: {
+                        height: '100%',
+                        borderRight: ['none', 'none', '1px solid'],
+                        borderColor: 'border.default',
+                        p: 3,
+                        display: 'flex',
+                        flexDirection: 'column',
+                        gap: 3,
+                        minHeight: 0,
+                        overflow: 'hidden',
+                    }, children: [_jsxs(Box, { sx: {
+                                display: 'flex',
+                                justifyContent: 'space-between',
+                                alignItems: 'center',
+                                flexWrap: 'wrap',
+                                gap: 2,
+                            }, children: [_jsxs(Box, { children: [_jsx(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: "Agent Inference Provider Example" }), _jsxs(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: ["Launches a local agent runtime from ", AGENT_SPEC_ID, " and lets you switch between local and datalayer inference."] })] }), _jsx(ProviderBadge, { provider: provider })] }), _jsxs(SegmentedControl, { "aria-label": "Inference provider", fullWidth: true, children: [_jsx(SegmentedControl.Button, { selected: provider === 'local', onClick: () => onProviderChange('local'), children: "local" }), _jsx(SegmentedControl.Button, { selected: provider === 'datalayer', onClick: () => onProviderChange('datalayer'), children: "datalayer" })] }), _jsxs(Box, { sx: {
+                                display: 'flex',
+                                gap: 2,
+                                alignItems: 'center',
+                                flexWrap: 'wrap',
+                            }, children: [isLaunching ? _jsx(Spinner, { size: "small" }) : null, _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Runtime URL: ", baseUrl] }), _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Inference URL: ", inferenceUrl] }), _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Agent ID: ", agentId || 'launching...'] })] }), error ? (_jsx(Box, { sx: {
+                                p: 2,
+                                borderRadius: 2,
+                                border: '1px solid',
+                                borderColor: 'danger.emphasis',
+                                bg: 'danger.subtle',
+                                color: 'danger.fg',
+                                fontSize: 1,
+                            }, children: error })) : null, _jsx(Box, { sx: {
+                                flexGrow: 1,
+                                flexShrink: 1,
+                                flexBasis: 0,
+                                minHeight: 0,
+                                border: '1px solid',
+                                borderColor: 'border.default',
+                                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: ${AGENT_SPEC_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 => {
+                                    appendProviderEvent('provider.request', `Sent message via ${provider}`, {
+                                        provider,
+                                        agentId,
+                                        content,
+                                    });
+                                }, onMessageReceived: message => {
+                                    appendProviderEvent('provider.message', 'Received stream message', message);
+                                }, suggestions: [
+                                    {
+                                        title: 'Compare providers',
+                                        message: 'Give me a short 3-point comparison between local and datalayer inference providers.',
+                                    },
+                                ], submitOnSuggestionClick: true })) : (_jsxs(Box, { sx: {
+                                    height: '100%',
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    justifyContent: 'center',
+                                    gap: 2,
+                                    color: 'fg.muted',
+                                }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1 }, children: "Launching provider runtime\u2026" })] })) })] }), _jsxs(Box, { sx: {
+                        p: 3,
+                        display: ['none', 'none', 'flex'],
+                        flexDirection: 'column',
+                        gap: 2,
+                        minHeight: 0,
+                        overflow: 'hidden',
+                        bg: 'canvas.inset',
+                    }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2 }, children: "Provider Event Stream" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Low-level request/response events exchanged with the inference provider (newest first)." }), _jsx(Box, { sx: {
+                                flex: 1,
+                                minHeight: 0,
+                                overflowY: 'auto',
+                                display: 'flex',
+                                flexDirection: 'column',
+                                gap: 2,
+                            }, children: providerEvents.length === 0 ? (_jsx(Box, { sx: {
+                                    border: '1px dashed',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    p: 3,
+                                }, children: _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "No provider events yet." }) })) : (orderedProviderEvents.map(event => (_jsxs(Box, { sx: {
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    borderRadius: 2,
+                                    p: 2,
+                                    bg: 'canvas.default',
+                                }, children: [_jsx(Text, { sx: {
+                                            display: 'block',
+                                            fontSize: 0,
+                                            color: 'fg.muted',
+                                            textTransform: 'uppercase',
+                                            letterSpacing: '0.04em',
+                                        }, children: event.type }), _jsx(Text, { sx: {
+                                            display: 'block',
+                                            fontWeight: 600,
+                                            fontSize: 1,
+                                            mt: 1,
+                                        }, children: event.summary }), _jsx(Text, { sx: {
+                                            display: 'block',
+                                            color: 'fg.muted',
+                                            fontSize: 0,
+                                            mt: 1,
+                                        }, children: new Date(event.createdAt).toLocaleTimeString() }), _jsx(Box, { sx: { mt: 2 }, children: _jsx(Button, { size: "small", variant: "invisible", onClick: () => toggleEventExpanded(event.id), children: expandedEventIds.has(event.id)
+                                                ? 'Hide details'
+                                                : 'Show details' }) }), expandedEventIds.has(event.id) ? (_jsx(Text, { as: "pre", sx: {
+                                            mt: 2,
+                                            mb: 0,
+                                            p: 2,
+                                            borderRadius: 2,
+                                            bg: 'canvas.subtle',
+                                            fontSize: 0,
+                                            whiteSpace: 'pre-wrap',
+                                            fontFamily: 'mono',
+                                        }, children: event.payload })) : null] }, event.id)))) })] })] }) }));
+};
+const AgentInferenceProviderExample = () => {
+    return (_jsx(QueryClientProvider, { client: queryClient, children: _jsx(AgentInferenceProviderExampleInner, {}) }));
+};
+export default AgentInferenceProviderExample;

package/lib/examples/AgentMCPExample.js

@@ -19,8 +19,9 @@ import { parseAgentStreamMessage } from '../types/stream';
 import { MCP_STATUS_COLORS, MCP_STATUS_LABELS } from '../types/mcp';
 import { MCP_SERVER_LIBRARY } from '../specs/mcpServers';
 const queryClient = new QueryClient();
-const AGENT_NAME = 'mcp-demo-agent';
-const AGENT_SPEC_ID = 'demo-mcp';
+const AGENT_NAME = 'mcp-example-agent';
+// Must match agentspecs/agentspecs/agents/example-mcp.yaml `id`.
+const AGENT_SPEC_ID = 'example-mcp';
 const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 /* ── Aggregate MCP status helpers ─────────────────────── */
 function deriveAggregate(servers) {
@@ -149,7 +150,7 @@ const AgentMCPInner = ({ onLogout }) => {
                     method: 'POST',
                     body: JSON.stringify({
                         name: agentName,
-                        description: 'MCP demo agent – web crawling and research via Tavily',
+                        description: 'MCP example agent – web crawling and research via Tavily',
                         agent_library: 'pydantic-ai',
                         transport: 'vercel-ai',
                         agent_spec_id: AGENT_SPEC_ID,
@@ -372,7 +373,7 @@ const AgentMCPInner = ({ onLogout }) => {
                 justifyContent: 'center',
                 height: '100vh',
                 gap: 3,
-            }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Launching MCP demo agent..." })] }));
+            }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Launching MCP example agent..." })] }));
     }
     if (runtimeStatus === 'error' || hookError) {
         return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
@@ -386,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", 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: 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: [
                                 {
                                     title: '🔍 Search the web',
                                     message: 'Search the web for recent news about AI agents.',

package/lib/examples/AgentMemoryExample.d.ts

@@ -2,8 +2,7 @@
  * AgentMemoryExample
  *
  * Demonstrates the Mem0 memory backend for durable agents.
- * Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
- * Runtimes API, then deploys an agent with persistent memory on its sidecar.
+ * Creates a local agent-runtimes agent using the `example-memory` spec.
  *
  * The left panel shows a standard Chat. The right panel shows the
  * agent's memory contents (fetched from the runtime sidecar) and lets

package/lib/examples/AgentMemoryExample.js

@@ -7,8 +7,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * AgentMemoryExample
  *
  * Demonstrates the Mem0 memory backend for durable agents.
- * Creates a cloud agent runtime (environment: 'ai-agents-env') via the Datalayer
- * Runtimes API, then deploys an agent with persistent memory on its sidecar.
+ * Creates a local agent-runtimes agent using the `example-memory` spec.
  *
  * The left panel shows a standard Chat. The right panel shows the
  * agent's memory contents (fetched from the runtime sidecar) and lets
@@ -26,31 +25,24 @@ import { uniqueAgentId } from './utils/agentId';
 const queryClient = new QueryClient();
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { Chat } from '../chat';
-import { useAgentRuntimes } from '../hooks/useAgentRuntimes';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 // ─── Constants ─────────────────────────────────────────────────────────────
-const AGENT_NAME = 'memory-demo-agent';
-const AGENT_SPEC_ID = 'monitor-sales-kpis'; // uses mem0 memory
+const AGENT_NAME = 'memory-example-agent';
+const AGENT_SPEC_ID = 'example-memory';
 // ─── Inner component (rendered after auth) ─────────────────────────────────
 const AgentMemoryInner = ({ onLogout }) => {
     const { token } = useSimpleAuthStore();
     const agentName = useRef(uniqueAgentId(AGENT_NAME)).current;
-    const { runtime, status: runtimeStatus, isReady, error: hookError, } = useAgentRuntimes({
-        agentSpecId: AGENT_SPEC_ID,
-        autoStart: true,
-        agentConfig: {
-            name: agentName,
-            model: 'bedrock:us.anthropic.claude-3-5-haiku-20241022-v1:0',
-            protocol: 'vercel-ai',
-            description: 'Agent with Mem0 persistent memory',
-        },
-    });
+    const agentBaseUrl = useExampleAgentRuntimesUrl();
+    const [runtimeStatus, setRuntimeStatus] = useState('launching');
+    const [isReady, setIsReady] = useState(false);
+    const [hookError, setHookError] = useState(null);
+    const [agentId, setAgentId] = useState(agentName);
     const [memories, setMemories] = useState([]);
     const [searchQuery, setSearchQuery] = useState('');
     const [searchResults, setSearchResults] = useState([]);
     const [searching, setSearching] = useState(false);
-    const agentBaseUrl = runtime?.agentBaseUrl || '';
-    const agentId = runtime?.agentId || AGENT_NAME;
-    const podName = runtime?.podName || '(launching…)';
+    const podName = isReady ? `local:${agentId}` : '(launching…)';
     // Authenticated fetch helper (for sidecar endpoints)
     const authFetch = useCallback((url, opts = {}) => fetch(url, {
         ...opts,
@@ -60,6 +52,65 @@ const AgentMemoryInner = ({ onLogout }) => {
             ...(opts.headers ?? {}),
         },
     }), [token]);
+    useEffect(() => {
+        let isCancelled = false;
+        const createLocalAgent = async () => {
+            setRuntimeStatus('launching');
+            setIsReady(false);
+            setHookError(null);
+            try {
+                const response = await authFetch(`${agentBaseUrl}/api/v1/agents`, {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        name: agentName,
+                        description: 'Agent with Mem0 persistent memory',
+                        agent_library: 'pydantic-ai',
+                        transport: 'vercel-ai',
+                        agent_spec_id: AGENT_SPEC_ID,
+                        enable_skills: true,
+                        tools: [],
+                    }),
+                });
+                let resolvedAgentId = agentName;
+                if (response.ok) {
+                    const data = await response.json();
+                    resolvedAgentId = data?.id || agentName;
+                }
+                else {
+                    const contentType = response.headers.get('content-type') || '';
+                    let detail = '';
+                    if (contentType.includes('application/json')) {
+                        const data = await response.json().catch(() => null);
+                        detail =
+                            (typeof data?.detail === 'string' && data.detail) ||
+                                (typeof data?.message === 'string' && data.message) ||
+                                '';
+                    }
+                    else {
+                        detail = await response.text();
+                    }
+                    if (!(response.status === 409 || /already exists/i.test(detail))) {
+                        throw new Error(detail || `Failed to create local agent: ${response.status}`);
+                    }
+                }
+                if (!isCancelled) {
+                    setAgentId(resolvedAgentId);
+                    setIsReady(true);
+                    setRuntimeStatus('ready');
+                }
+            }
+            catch (error) {
+                if (!isCancelled) {
+                    setHookError(error instanceof Error ? error.message : 'Agent failed to start');
+                    setRuntimeStatus('error');
+                }
+            }
+        };
+        void createLocalAgent();
+        return () => {
+            isCancelled = true;
+        };
+    }, [agentBaseUrl, agentName, authFetch]);
     // ── Fetch memory list ────────────────────────────────────────────────────
     const fetchMemories = useCallback(async () => {
         if (!isReady || !agentBaseUrl)
@@ -113,9 +164,7 @@ const AgentMemoryInner = ({ onLogout }) => {
                 justifyContent: 'center',
                 height: '100vh',
                 gap: 3,
-            }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: runtimeStatus === 'launching'
-                        ? 'Launching runtime for memory agent…'
-                        : 'Creating memory-enabled agent…' })] }));
+            }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: "Launching local memory-enabled agent\u2026" })] }));
     }
     if (runtimeStatus === 'error' || hookError) {
         return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
@@ -139,7 +188,7 @@ const AgentMemoryInner = ({ onLogout }) => {
                             minWidth: 0,
                             borderRight: '1px solid',
                             borderColor: 'border.default',
-                        }, children: _jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, title: "Memory Agent", placeholder: "Chat \u2014 the agent remembers you across sessions\u2026", description: "Agent with Mem0 persistent memory", showHeader: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
+                        }, children: _jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, title: "Memory Agent", brandIcon: _jsx(DatabaseIcon, { size: 16 }), placeholder: "Chat \u2014 the agent remembers you across sessions\u2026", description: "Agent with Mem0 persistent memory", showHeader: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
                                 {
                                     title: 'Remember',
                                     message: 'My favourite colour is midnight blue.',