@datalayer/agent-runtimes 1.0.10 → 1.0.18

package/lib/examples/AgentMonitoringExample.js

@@ -30,15 +30,18 @@ import { GraphFlowChart } from '../context/GraphFlowChart';
 import { TurnGraphChart } from '../context/TurnGraphChart';
 import { useAIAgentsWebSocket } from '../hooks';
 import { parseAgentStreamMessage } from '../types/stream';
-import { useCoreStore } from '@datalayer/core/lib/state';
+import { useCoreStore } from '../state/substates';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 const queryClient = new QueryClient();
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { Chat } from '../chat';
 const AGENT_NAME = 'monitoring-example-agent';
 const AGENTSPEC_ID = 'example-monitoring';
-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 AgentMonitoringInner = ({ onLogout, }) => {
     const { token } = useSimpleAuthStore();
     const agentName = useRef(uniqueAgentId(AGENT_NAME)).current;
@@ -55,11 +58,13 @@ const AgentMonitoringInner = ({ onLogout, }) => {
     const [liveMcpStatus, setLiveMcpStatus] = useState(undefined);
     const [monitorLastSnapshotAt, setMonitorLastSnapshotAt] = useState(null);
     const [liveGraphTelemetry, setLiveGraphTelemetry] = useState(undefined);
-    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;
     // The OTEL service_name resource attribute is 'agent-runtimes' (the
@@ -139,54 +144,119 @@ const AgentMonitoringInner = ({ onLogout, }) => {
         return () => {
             isCancelled = true;
         };
-    }, [agentBaseUrl, authFetch]);
+    }, [agentBaseUrl, agentName, authFetch]);
     const handleMonitoringStreamMessage = useCallback((message) => {
         try {
             const stream = parseAgentStreamMessage(message?.raw ?? message);
             if (!stream || stream.type !== 'agent.snapshot') {
                 return;
             }
+            // Snapshot payloads may arrive with camelCase (TS types) or snake_case
+            // (Python backend) keys. Read both for consistency with the UI.
+            const asRecord = (value) => value && typeof value === 'object'
+                ? value
+                : {};
+            const pick = (source, keys) => {
+                for (const key of keys) {
+                    const value = source[key];
+                    if (value !== undefined && value !== null) {
+                        return value;
+                    }
+                }
+                return undefined;
+            };
+            const pickNumber = (source, keys, fallback = 0) => {
+                const value = pick(source, keys);
+                const parsed = Number(value);
+                return Number.isFinite(parsed) ? parsed : fallback;
+            };
+            const pickOptionalNumber = (source, keys) => {
+                const value = pick(source, keys);
+                if (value === undefined || value === null) {
+                    return null;
+                }
+                const parsed = Number(value);
+                return Number.isFinite(parsed) ? parsed : null;
+            };
+            const payloadRecord = asRecord(stream.payload);
             const payload = stream.payload;
-            if (payload.contextSnapshot) {
-                setLiveContext(payload.contextSnapshot);
-                setLiveContextSnapshot(payload.contextSnapshot);
+            const contextSnapshot = pick(payloadRecord, [
+                'contextSnapshot',
+                'context_snapshot',
+            ]);
+            if (contextSnapshot) {
+                setLiveContext(contextSnapshot);
+                setLiveContextSnapshot(contextSnapshot);
                 setMonitorLastSnapshotAt(Date.now());
             }
-            if (payload.mcpStatus !== undefined) {
-                setLiveMcpStatus(payload.mcpStatus ?? undefined);
+            const mcpStatus = pick(payloadRecord, ['mcpStatus', 'mcp_status']);
+            if (mcpStatus !== undefined) {
+                setLiveMcpStatus(mcpStatus ?? undefined);
             }
             if (payload.graphTelemetry) {
                 setLiveGraphTelemetry(payload.graphTelemetry);
             }
-            const snapshotCost = payload.contextSnapshot?.costUsage ?? payload.costUsage;
-            if (!snapshotCost) {
+            const snapshotCost = asRecord(pick(asRecord(contextSnapshot), ['costUsage', 'cost_usage']) ??
+                pick(payloadRecord, ['costUsage', 'cost_usage']));
+            if (!snapshotCost || Object.keys(snapshotCost).length === 0) {
                 return;
             }
+            const modelBreakdown = pick(snapshotCost, [
+                'modelBreakdown',
+                'model_breakdown',
+            ]);
+            const runs = pick(snapshotCost, ['runs']);
             setLiveCost({
                 agentId,
-                lastTurnCostUsd: Number(snapshotCost.lastTurnCostUsd ?? 0),
-                cumulativeCostUsd: Number(snapshotCost.cumulativeCostUsd ?? 0),
-                perRunBudgetUsd: snapshotCost.perRunBudgetUsd == null
-                    ? null
-                    : Number(snapshotCost.perRunBudgetUsd),
-                cumulativeBudgetUsd: snapshotCost.cumulativeBudgetUsd == null
-                    ? null
-                    : Number(snapshotCost.cumulativeBudgetUsd),
-                requestCount: Number(snapshotCost.requestCount ?? 0),
-                totalTokensUsed: Number(snapshotCost.totalTokensUsed ?? 0),
-                modelBreakdown: Array.isArray(snapshotCost.modelBreakdown)
-                    ? snapshotCost.modelBreakdown.map(item => ({
-                        model: String(item.model ?? 'unknown'),
-                        inputTokens: Number(item.inputTokens ?? 0),
-                        outputTokens: Number(item.outputTokens ?? 0),
-                        costUsd: Number(item.costUsd ?? 0),
-                        requests: Number(item.requests ?? 0),
-                    }))
+                lastTurnCostUsd: pickNumber(snapshotCost, [
+                    'lastTurnCostUsd',
+                    'last_turn_cost_usd',
+                ]),
+                cumulativeCostUsd: pickNumber(snapshotCost, [
+                    'cumulativeCostUsd',
+                    'cumulative_cost_usd',
+                ]),
+                perRunBudgetUsd: pickOptionalNumber(snapshotCost, [
+                    'perRunBudgetUsd',
+                    'per_run_budget_usd',
+                ]),
+                cumulativeBudgetUsd: pickOptionalNumber(snapshotCost, [
+                    'cumulativeBudgetUsd',
+                    'cumulative_budget_usd',
+                ]),
+                requestCount: pickNumber(snapshotCost, [
+                    'requestCount',
+                    'request_count',
+                ]),
+                totalTokensUsed: pickNumber(snapshotCost, [
+                    'totalTokensUsed',
+                    'total_tokens_used',
+                ]),
+                modelBreakdown: Array.isArray(modelBreakdown)
+                    ? modelBreakdown.map(entry => {
+                        const item = asRecord(entry);
+                        return {
+                            model: String(pick(item, ['model']) ?? 'unknown'),
+                            inputTokens: pickNumber(item, [
+                                'inputTokens',
+                                'input_tokens',
+                            ]),
+                            outputTokens: pickNumber(item, [
+                                'outputTokens',
+                                'output_tokens',
+                            ]),
+                            costUsd: pickNumber(item, ['costUsd', 'cost_usd']),
+                            requests: pickNumber(item, ['requests']),
+                        };
+                    })
                     : [],
-                runs: Array.isArray(snapshotCost.runs)
-                    ? snapshotCost.runs.map(item => ({
-                        pricingResolved: Boolean(item.pricingResolved),
-                    }))
+                runs: Array.isArray(runs)
+                    ? runs.map(entry => {
+                        const item = asRecord(entry);
+                        return {
+                            pricingResolved: Boolean(pick(item, ['pricingResolved', 'pricing_resolved'])),
+                        };
+                    })
                     : undefined,
             });
         }
@@ -213,7 +283,7 @@ const AgentMonitoringInner = ({ 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 monitoring example agent..." })] }));
     }
@@ -221,7 +291,7 @@ const AgentMonitoringInner = ({ onLogout, }) => {
         return _jsx(ErrorView, { error: hookError, onLogout: onLogout });
     }
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [_jsxs(Box, { sx: {
@@ -254,11 +324,11 @@ const AgentMonitoringInner = ({ onLogout, }) => {
                                     p: 3,
                                     borderBottom: '1px solid',
                                     borderColor: 'border.default',
-                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Token Usage" }), _jsx(TokenUsageChart, { serviceName: otelServiceName, agentId: agentId, apiKey: token ?? undefined, runUrl: otelBaseUrl, liveSystemPromptTokens: liveContextSnapshot?.systemPromptTokens, liveUserMessageTokens: liveContextSnapshot?.userMessageTokens, liveAgentMessageTokens: liveContextSnapshot?.assistantMessageTokens, liveToolsUsageTokens: liveContextSnapshot?.toolTokens, liveTimestampMs: monitorLastSnapshotAt, height: 180 })] }), _jsxs(Box, { sx: {
+                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Token Usage" }), _jsx(TokenUsageChart, { serviceName: otelServiceName, agentId: agentId, apiKey: token ?? undefined, datalayerUrl: otelBaseUrl, liveSystemPromptTokens: liveContextSnapshot?.systemPromptTokens, liveUserMessageTokens: liveContextSnapshot?.userMessageTokens, liveAgentMessageTokens: liveContextSnapshot?.assistantMessageTokens, liveToolsUsageTokens: liveContextSnapshot?.toolTokens, liveTimestampMs: monitorLastSnapshotAt, height: 180 })] }), _jsxs(Box, { sx: {
                                     p: 3,
                                     borderBottom: '1px solid',
                                     borderColor: 'border.default',
-                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Cost" }), _jsx(CostUsageChart, { serviceName: otelServiceName, agentId: agentId, apiKey: token ?? undefined, runUrl: otelBaseUrl, liveCumulativeUsd: liveCost?.cumulativeCostUsd, liveTimestampMs: monitorLastSnapshotAt, height: 180 })] }), _jsxs(Box, { sx: {
+                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Cost" }), _jsx(CostUsageChart, { serviceName: otelServiceName, agentId: agentId, apiKey: token ?? undefined, datalayerUrl: otelBaseUrl, liveCumulativeUsd: liveCost?.cumulativeCostUsd, liveTimestampMs: monitorLastSnapshotAt, height: 180 })] }), _jsxs(Box, { sx: {
                                     p: 3,
                                     borderBottom: '1px solid',
                                     borderColor: 'border.default',
@@ -335,10 +405,10 @@ const AgentMonitoringInner = ({ onLogout, }) => {
                                     p: 3,
                                     borderBottom: '1px solid',
                                     borderColor: 'border.default',
-                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Turn Execution Graph (OTEL traces)" }), _jsx(TurnGraphChart, { serviceName: otelServiceName, agentId: agentId, runUrl: otelBaseUrl, apiKey: token ?? undefined, autoRefreshMs: 10_000, height: 280 })] })] })] })] }));
+                                }, children: [_jsx(Heading, { as: "h4", sx: { fontSize: 1, mb: 2 }, children: "Turn Execution Graph (OTEL traces)" }), _jsx(TurnGraphChart, { serviceName: otelServiceName, agentId: agentId, datalayerUrl: otelBaseUrl, apiKey: token ?? undefined, autoRefreshMs: 10_000, height: 280 })] })] })] })] }));
 };
 const syncTokenToIamStore = (token) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token });
     });
 };
@@ -354,7 +424,7 @@ const AgentMonitoringExample = () => {
     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/AgentNotificationsExample.js

@@ -213,7 +213,7 @@ const AgentNotificationsInner = ({ 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 notification agent\u2026" })] }));
     }
@@ -238,7 +238,7 @@ const AgentNotificationsInner = ({ onLogout, }) => {
         }
     };
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [_jsxs(Box, { sx: {
@@ -319,7 +319,7 @@ const AgentNotificationsInner = ({ 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 });
     });
 };
@@ -336,7 +336,7 @@ const AgentNotificationsExample = () => {
     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/AgentOtelExample.d.ts

@@ -7,9 +7,9 @@
  * is a ChatSidebar whose agent is selected from the agent-runtimes library spec
  * list and launched on demand.
  *
- * The OTEL backend is configured via `configuration.otelRunUrl` when available
- * (falling back to `configuration.runUrl`, then `VITE_OTEL_BASE_URL`, then
- * `VITE_DATALAYER_RUN_URL`, then https://prod1.datalayer.run).
+ * The OTEL backend is configured via `configuration.otelUrl` when available
+ * (falling back to `configuration.datalayerUrl`, then `VITE_OTEL_BASE_URL`, then
+ * `VITE_DATALAYER_URL`, then https://prod1.datalayer.run).
  * Agent routes use `VITE_BASE_URL` when provided, otherwise the same resolved
  * direct run URL to avoid proxy-relative calls.
  *

package/lib/examples/AgentOtelExample.js

@@ -12,9 +12,9 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * is a ChatSidebar whose agent is selected from the agent-runtimes library spec
  * list and launched on demand.
  *
- * The OTEL backend is configured via `configuration.otelRunUrl` when available
- * (falling back to `configuration.runUrl`, then `VITE_OTEL_BASE_URL`, then
- * `VITE_DATALAYER_RUN_URL`, then https://prod1.datalayer.run).
+ * The OTEL backend is configured via `configuration.otelUrl` when available
+ * (falling back to `configuration.datalayerUrl`, then `VITE_OTEL_BASE_URL`, then
+ * `VITE_DATALAYER_URL`, then https://prod1.datalayer.run).
  * Agent routes use `VITE_BASE_URL` when provided, otherwise the same resolved
  * direct run URL to avoid proxy-relative calls.
  *
@@ -34,7 +34,10 @@ import { AuthRequiredView } from './components';
 import { ChatSidebar } from '../chat';
 // ─── Environment / defaults ────────────────────────────────────────────────
 const OTEL_BASE_URL_ENV = import.meta.env.VITE_OTEL_BASE_URL ?? '';
-const DATALAYER_RUN_URL_ENV = import.meta.env.VITE_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 ?? '';
 /**
  * Base URL of the agent-runtimes server.
  * Defaults to proxy-relative calls when VITE_BASE_URL is unset.
@@ -136,12 +139,14 @@ const TAB_SX = (active) => ({
 });
 const AgentOtelExampleInner = ({ token }) => {
     const { configuration } = useCoreStore();
-    const resolvedRunUrl = configuration?.otelRunUrl ||
-        configuration?.runUrl ||
+    const resolvedUrl = 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 otelBaseUrl = resolvedRunUrl;
+    const otelBaseUrl = resolvedUrl;
     const agentBaseUrl = AGENT_BASE_URL_ENV;
     // ── OTEL view state ─────────────────────────────────────────────
     const [view, setView] = useState('dashboard');
@@ -180,7 +185,7 @@ const AgentOtelExampleInner = ({ token }) => {
         if (connectedAgentTransport === 'ag-ui') {
             return {
                 type: 'ag-ui',
-                endpoint: `${agentBaseUrl}/api/v1/examples/${connectedAgentId}/`,
+                endpoint: `${agentBaseUrl}/api/v1/ag-ui/${connectedAgentId}/`,
                 agentId: connectedAgentId,
             };
         }
@@ -208,7 +213,7 @@ const AgentOtelExampleInner = ({ token }) => {
     return (_jsxs(Box, { sx: {
             display: 'flex',
             flexDirection: 'column',
-            height: 'calc(100vh - 90px)',
+            height: '100%',
             overflow: 'hidden',
             bg: 'canvas.default',
             color: 'fg.default',

package/lib/examples/AgentOutputsExample.js

@@ -31,11 +31,11 @@ import { ThemedProvider } from './utils/themedProvider';
 import { uniqueAgentId } from './utils/agentId';
 import { Chat } from '../chat';
 import { useChatStore } from '../stores/chatStore';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 const queryClient = new QueryClient();
 // ─── Constants ─────────────────────────────────────────────────────────────
 const AGENT_NAME = 'outputs-example-agent';
 const AGENTSPEC_ID = 'demo-outputs';
-const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 // ─── Output detection ──────────────────────────────────────────────────────
 const FENCE_RE = /```([a-zA-Z0-9_+-]*)\n([\s\S]*?)```/g;
 const MD_TABLE_RE = /(^|\n)\s*\|[^\n]+\|\s*\n\s*\|[\s:|-]+\|\s*\n(\s*\|[^\n]+\|\s*\n?)+/;
@@ -281,7 +281,7 @@ const AgentOutputsInner = ({ onLogout, }) => {
     const [hookError, setHookError] = useState(null);
     const [agentId, setAgentId] = useState(agentName);
     const [isReconnectedAgent, setIsReconnectedAgent] = useState(false);
-    const agentBaseUrl = DEFAULT_LOCAL_BASE_URL;
+    const agentBaseUrl = useExampleAgentRuntimesUrl();
     const chatAuthToken = token === null ? undefined : token;
     const authFetch = useCallback((url, opts = {}) => fetch(url, {
         ...opts,
@@ -399,7 +399,7 @@ const AgentOutputsInner = ({ 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: runtimeStatus === 'launching'
                         ? 'Launching outputs example agent...'
@@ -422,7 +422,7 @@ const AgentOutputsInner = ({ onLogout, }) => {
         URL.revokeObjectURL(url);
     };
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [isReconnectedAgent && (_jsx(Box, { sx: {
@@ -528,7 +528,7 @@ const AgentOutputsInner = ({ 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 });
     });
 };
@@ -545,7 +545,7 @@ const AgentOutputsExample = () => {
     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/AgentParametersExample.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { Box, setupPrimerPortals } from '@datalayer/primer-addons';
 import { Button, Heading, Label, Spinner, Text } from '@primer/react';
 import { FileIcon } from '@primer/octicons-react';
@@ -12,6 +12,7 @@ import { Form, yamlSchemaToJsonSchema } from '@datalayer/primer-rjsf';
 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();
@@ -103,14 +104,24 @@ function hasRequiredValues(schema, formData) {
 }
 const AgentParametersExample = () => {
     const baseUrl = useExampleAgentRuntimesUrl();
+    const [agentName] = useState(() => uniqueAgentId(AGENT_NAME));
     const [showSchemaForm, setShowSchemaForm] = useState(false);
     const [isSchemaLoading, setIsSchemaLoading] = useState(false);
     const [schema, setSchema] = useState(null);
     const [formData, setFormData] = useState({});
-    const [agentId, setAgentId] = useState(null);
     const [isCreating, setIsCreating] = useState(false);
     const [error, setError] = useState(null);
     const [formTouched, setFormTouched] = useState(false);
+    const { agentId, error: runtimeError, createAgent, } = useExampleAgentRuntime({
+        exampleId: 'AgentParametersExample',
+        agentName,
+        specId: AGENTSPEC_ID,
+        autoCreateAgent: false,
+        agentConfig: {
+            protocol: 'vercel-ai',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
     const hasRequired = useMemo(() => hasRequiredValues(schema, formData), [schema, formData]);
     const canLaunch = useMemo(() => {
         return showSchemaForm && schema !== null && !isSchemaLoading && hasRequired;
@@ -148,25 +159,14 @@ const AgentParametersExample = () => {
         setIsCreating(true);
         setError(null);
         try {
-            const name = uniqueAgentId(AGENT_NAME);
-            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',
+            await createAgent({
+                name: agentName,
+                protocol: 'vercel-ai',
+                agentSpecId: AGENTSPEC_ID,
+                createPayload: {
                     agent_parameters: formData,
-                }),
+                },
             });
-            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();
-            setAgentId(data.id);
         }
         catch (err) {
             setError(err instanceof Error ? err.message : 'Failed to launch agent');
@@ -175,18 +175,7 @@ const AgentParametersExample = () => {
             setIsCreating(false);
         }
     };
-    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 effectiveError = error || runtimeError;
     if (!agentId) {
         return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
                     maxWidth: 760,
@@ -231,8 +220,7 @@ const AgentParametersExample = () => {
                             }, onSubmit: (_, event) => {
                                 event?.preventDefault();
                                 event?.stopPropagation();
-                                // Prevent implicit form submission; launching is click-only.
-                            }, noHtml5Validate: true }) })), _jsx(Button, { variant: "primary", size: "small", type: "button", onClick: launchAgent, disabled: !canLaunch || isCreating, sx: { width: '100%' }, children: isCreating ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "small" }), " Launching..."] })) : ('Launch Agent') }), schema && formTouched && (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Parameters are sent as agent_parameters in the create-agent request." })), error && _jsx(ErrorView, { error: "Launch failed", detail: error })] }) }));
+                            }, noHtml5Validate: true }) })), _jsx(Button, { variant: "primary", size: "small", type: "button", onClick: launchAgent, disabled: !canLaunch || isCreating, sx: { width: '100%' }, children: isCreating ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "small" }), " Launching..."] })) : ('Launch Agent') }), schema && formTouched && (_jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Parameters are sent as agent_parameters in the create-agent request." })), effectiveError && (_jsx(ErrorView, { error: "Launch failed", detail: effectiveError }))] }) }));
     }
     return (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, title: `Parameterized Agent: ${String(formData.project ?? 'Project')}`, brandIcon: _jsx(FileIcon, { size: 16 }), placeholder: "Ask something about your configured project...", description: `Role: ${String(formData.role ?? 'n/a')} · Tone: ${String(formData.tone ?? 'n/a')}`, showHeader: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, height: "100vh", runtimeId: agentId, historyEndpoint: `${baseUrl}/api/v1/history`, suggestions: [
             {

package/lib/examples/AgentSandboxExample.js

@@ -27,13 +27,13 @@ import { CodeIcon, StopIcon, TerminalIcon } from '@primer/octicons-react';
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { ThemedProvider } from './utils/themedProvider';
 import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { Chat } from '../chat';
 import { SANDBOX_STATUS_COLORS, SANDBOX_STATUS_LABELS } from '../types/sandbox';
 // ─── Constants ─────────────────────────────────────────────────────────────
 const queryClient = new QueryClient();
 const AGENT_NAME = 'sandbox-example-agent';
 const AGENTSPEC_ID = 'example-full';
-const DEFAULT_LOCAL_BASE_URL = import.meta.env.VITE_BASE_URL || 'http://localhost:8765';
 let _logId = 0;
 function tsNow() {
     return new Date().toISOString().slice(11, 23); // HH:MM:SS.mmm
@@ -63,7 +63,7 @@ const AgentSandboxInner = ({ onLogout, }) => {
     const { token } = useSimpleAuthStore();
     const agentName = useRef(uniqueAgentId(AGENT_NAME)).current;
     const chatAuthToken = token === null ? undefined : token;
-    const agentBaseUrl = DEFAULT_LOCAL_BASE_URL;
+    const agentBaseUrl = useExampleAgentRuntimesUrl();
     // ── Agent lifecycle ──
     const [runtimeStatus, setRuntimeStatus] = useState('launching');
     const [isReady, setIsReady] = useState(false);
@@ -463,7 +463,7 @@ const AgentSandboxInner = ({ onLogout, }) => {
                     py: 1,
                     borderBottom: '1px solid',
                     borderColor: 'border.default',
-                }, children: _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "Agent already running \u2014 reconnected." }) })), _jsxs(Box, { sx: { flex: 1, minHeight: 0, display: 'flex' }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0 }, children: _jsxs(Box, { sx: { position: 'relative', height: '100%' }, children: [_jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, authToken: chatAuthToken, title: "Sandbox Agent", brandIcon: _jsx(TerminalIcon, { size: 16 }), placeholder: "Ask the agent to write and run code\u2026", showHeader: true, showNewChatButton: true, showClearButton: false, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${agentBaseUrl}/api/v1/history`, headerActions: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsxs(SegmentedControl, { "aria-label": "Sandbox variant", size: "small", onChange: index => {
+                }, children: _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: "Agent already running \u2014 reconnected." }) })), _jsxs(Box, { sx: { flex: 1, minHeight: 0, display: 'flex' }, children: [_jsx(Box, { sx: { flex: 1, minWidth: 0 }, children: _jsxs(Box, { sx: { position: 'relative', height: '100%' }, children: [_jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, authToken: chatAuthToken, title: "Sandbox Agent", brandIcon: _jsx(TerminalIcon, { size: 16 }), placeholder: "Ask the agent to write and run code\u2026", showHeader: true, showNewChatButton: true, showClearButton: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: agentId, historyEndpoint: `${agentBaseUrl}/api/v1/history`, headerActions: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsxs(SegmentedControl, { "aria-label": "Sandbox variant", size: "small", onChange: index => {
                                                     if (isTransitionLocked)
                                                         return;
                                                     void switchVariant(index === 0 ? 'eval' : 'jupyter');
@@ -491,7 +491,7 @@ const AgentSandboxInner = ({ onLogout, }) => {
 };
 // ─── Auth wrapper ──────────────────────────────────────────────────────────
 const syncTokenToIamStore = (newToken) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token: newToken });
     });
 };
@@ -507,7 +507,7 @@ const AgentSandboxExample = () => {
     const handleLogout = useCallback(() => {
         clearAuth();
         hasSynced.current = false;
-        import('@datalayer/core/lib/state').then(({ iamStore }) => {
+        import('../state/substates').then(({ iamStore }) => {
             iamStore.setState({ token: undefined });
         });
     }, [clearAuth]);