@datalayer/agent-runtimes 1.0.10 → 1.0.17

package/lib/examples/AgUiHumanInTheLoopExample.d.ts

@@ -5,22 +5,11 @@
  * Human in the Loop example backend. This shows how to implement
  * approval workflows where the human must approve generated plans.
  *
- * Backend: /api/v1/examples/human_in_the_loop/
+ * Backend: managed AG-UI agent runtime (agentspec: example-human-in-the-loop)
  *
  * Pattern: Uses renderToolResult with respond callback for human-in-the-loop
  * interactions, matching the CopilotKit useHumanInTheLoop pattern.
  */
 import React from 'react';
-/**
- * AgUiHumanInTheLoopExample Component
- *
- * Demonstrates human-in-the-loop approval patterns with AG-UI.
- * The agent generates task steps that require human approval before proceeding.
- *
- * Features demonstrated:
- * - Tool call rendering with Reject/Confirm buttons
- * - respond callback for sending user decisions back to the agent
- * - UI state changes based on user actions
- */
 declare const AgUiHumanInTheLoopExample: React.FC;
 export default AgUiHumanInTheLoopExample;

package/lib/examples/AgUiHumanInTheLoopExample.js

@@ -10,19 +10,20 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Human in the Loop example backend. This shows how to implement
  * approval workflows where the human must approve generated plans.
  *
- * Backend: /api/v1/examples/human_in_the_loop/
+ * Backend: managed AG-UI agent runtime (agentspec: example-human-in-the-loop)
  *
  * Pattern: Uses renderToolResult with respond callback for human-in-the-loop
  * interactions, matching the CopilotKit useHumanInTheLoop pattern.
  */
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useMemo } from 'react';
 import { Text, Checkbox, FormControl, Label, ProgressBar, Button, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { TasklistIcon, CheckCircleFillIcon, XCircleFillIcon, } from '@primer/octicons-react';
-// AG-UI endpoint for human in the loop example
-const HUMAN_IN_THE_LOOP_ENDPOINT = 'http://localhost:8765/api/v1/examples/human_in_the_loop/';
 /**
  * StepsFeedback Component
  *
@@ -177,8 +178,22 @@ const renderTaskStepsTool = (context) => {
  * - respond callback for sending user decisions back to the agent
  * - UI state changes based on user actions
  */
+const AGENT_NAME = 'ag-ui-human-in-the-loop';
+const AGENTSPEC_ID = 'example-human-in-the-loop';
 const AgUiHumanInTheLoopExample = () => {
     const brandColor = useThemeBrandColor();
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const { agentId } = useExampleAgentRuntime({
+        exampleId: 'AgUiHumanInTheLoopExample',
+        agentName,
+        specId: AGENTSPEC_ID,
+        agentConfig: {
+            protocol: 'ag-ui',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
+    const humanInTheLoopEndpoint = agentId != null ? `${baseUrl}/api/v1/ag-ui/${agentId}/` : undefined;
     return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: {
                 minHeight: '100vh',
                 backgroundColor: 'canvas.default',
@@ -207,7 +222,7 @@ const AgUiHumanInTheLoopExample = () => {
                                 borderRadius: 2,
                                 border: '1px solid',
                                 borderColor: 'accent.muted',
-                            }, children: [_jsx(Text, { as: "h2", sx: { fontSize: 2, fontWeight: 'semibold', marginBottom: 2 }, children: "Key Concept: respond() Callback" }), _jsxs(Text, { as: "p", sx: { fontSize: 1, color: 'fg.default' }, children: ["The ", _jsx("code", { children: "renderToolResult" }), " function receives a", ' ', _jsx("code", { children: "respond" }), " callback when the tool status is \"executing\". Calling ", _jsxs("code", { children: ["respond(", '{ accepted: true, steps: [...] }', ")"] }), ' ', "sends the user's decision back to the agent, completing the human-in-the-loop interaction."] })] })] }), _jsx(ChatFloating, { protocol: "ag-ui", endpoint: HUMAN_IN_THE_LOOP_ENDPOINT, title: "Task Planner", description: "I can help you plan tasks. I'll generate steps for your review.", position: "bottom-right", brandColor: brandColor, renderToolResult: renderTaskStepsTool, hideMessagesAfterToolUI: true, suggestions: [
+                            }, children: [_jsx(Text, { as: "h2", sx: { fontSize: 2, fontWeight: 'semibold', marginBottom: 2 }, children: "Key Concept: respond() Callback" }), _jsxs(Text, { as: "p", sx: { fontSize: 1, color: 'fg.default' }, children: ["The ", _jsx("code", { children: "renderToolResult" }), " function receives a", ' ', _jsx("code", { children: "respond" }), " callback when the tool status is \"executing\". Calling ", _jsxs("code", { children: ["respond(", '{ accepted: true, steps: [...] }', ")"] }), ' ', "sends the user's decision back to the agent, completing the human-in-the-loop interaction."] })] })] }), humanInTheLoopEndpoint && (_jsx(ChatFloating, { protocol: "ag-ui", endpoint: humanInTheLoopEndpoint, title: "Task Planner", description: "I can help you plan tasks. I'll generate steps for your review.", position: "bottom-right", brandColor: brandColor, renderToolResult: renderTaskStepsTool, hideMessagesAfterToolUI: true, suggestions: [
                         {
                             title: 'Plan a trip',
                             message: 'Plan a weekend trip to Paris.',
@@ -216,6 +231,6 @@ const AgUiHumanInTheLoopExample = () => {
                             title: 'Organize party',
                             message: 'Plan a birthday party for next Saturday.',
                         },
-                    ] })] }) }));
+                    ] }))] }) }));
 };
 export default AgUiHumanInTheLoopExample;

package/lib/examples/AgUiSharedStateExample.d.ts

@@ -5,21 +5,8 @@
  * and the AI agent using AG-UI. This example shows a recipe builder where
  * both the user and the AI can modify the shared state.
  *
- * Backend: /api/v1/examples/shared_state/
+ * Backend: managed AG-UI agent runtime (agentspec: example-shared-state)
  */
 import React from 'react';
-/**
- * AgUiSharedStateExample Component
- *
- * Demonstrates bidirectional shared state with AG-UI.
- * Both the frontend and the AI agent can modify the recipe state,
- * with changes synchronized via STATE_SNAPSHOT events.
- *
- * Features demonstrated:
- * - Bidirectional state synchronization
- * - StateDeps for passing state to agent
- * - STATE_SNAPSHOT for receiving state from agent
- * - Editable UI that updates shared state
- */
 declare const AgUiSharedStateExample: React.FC;
 export default AgUiSharedStateExample;

package/lib/examples/AgUiSharedStateExample.js

@@ -10,16 +10,17 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * and the AI agent using AG-UI. This example shows a recipe builder where
  * both the user and the AI can modify the shared state.
  *
- * Backend: /api/v1/examples/shared_state/
+ * Backend: managed AG-UI agent runtime (agentspec: example-shared-state)
  */
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useMemo } from 'react';
 import { Text, Button, TextInput, Label } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { PlusIcon, XIcon, BeakerIcon, ClockIcon, PersonIcon, } from '@primer/octicons-react';
-// AG-UI endpoint for shared state example
-const SHARED_STATE_ENDPOINT = 'http://localhost:8765/api/v1/examples/shared_state/';
 const DEFAULT_RECIPE = {
     title: '',
     description: '',
@@ -103,8 +104,22 @@ const RecipeDisplay = ({ recipe, onUpdate }) => {
  * - STATE_SNAPSHOT for receiving state from agent
  * - Editable UI that updates shared state
  */
+const AGENT_NAME = 'ag-ui-shared-state';
+const AGENTSPEC_ID = 'example-shared-state';
 const AgUiSharedStateExample = () => {
     const brandColor = useThemeBrandColor();
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const { agentId } = useExampleAgentRuntime({
+        exampleId: 'AgUiSharedStateExample',
+        agentName,
+        specId: AGENTSPEC_ID,
+        agentConfig: {
+            protocol: 'ag-ui',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
+    const sharedStateEndpoint = agentId != null ? `${baseUrl}/api/v1/ag-ui/${agentId}/` : undefined;
     const [recipe, setRecipe] = useState(DEFAULT_RECIPE);
     // Handle state updates from AG-UI
     const handleStateUpdate = useCallback((state) => {
@@ -169,7 +184,7 @@ const AgUiSharedStateExample = () => {
                                                 marginTop: 1,
                                                 fontSize: 1,
                                                 color: 'fg.muted',
-                                            }, children: [_jsx("li", { children: "\"Create a recipe for chocolate chip cookies\"" }), _jsx("li", { children: "\"Add butter and sugar to the ingredients\"" }), _jsx("li", { children: "\"Update the prep time to 20 minutes\"" }), _jsx("li", { children: "\"Suggest 3 more ingredients for my recipe\"" })] })] })] })] }), _jsx(ChatFloating, { protocol: "ag-ui", endpoint: SHARED_STATE_ENDPOINT, title: "Recipe Assistant", description: "Let's build a recipe together! I can add ingredients, instructions, and more.", position: "bottom-right", brandColor: brandColor, onStateUpdate: handleStateUpdate, suggestions: [
+                                            }, children: [_jsx("li", { children: "\"Create a recipe for chocolate chip cookies\"" }), _jsx("li", { children: "\"Add butter and sugar to the ingredients\"" }), _jsx("li", { children: "\"Update the prep time to 20 minutes\"" }), _jsx("li", { children: "\"Suggest 3 more ingredients for my recipe\"" })] })] })] })] }), sharedStateEndpoint && (_jsx(ChatFloating, { protocol: "ag-ui", endpoint: sharedStateEndpoint, title: "Recipe Assistant", description: "Let's build a recipe together! I can add ingredients, instructions, and more.", position: "bottom-right", brandColor: brandColor, onStateUpdate: handleStateUpdate, suggestions: [
                         {
                             title: 'Pasta recipe',
                             message: 'Help me create a simple pasta recipe.',
@@ -178,6 +193,6 @@ const AgUiSharedStateExample = () => {
                             title: 'Add ingredient',
                             message: 'Add tomatoes to the recipe.',
                         },
-                    ] })] }) }));
+                    ] }))] }) }));
 };
 export default AgUiSharedStateExample;

package/lib/examples/AgUiToolsBasedGenUiExample.d.ts

@@ -5,21 +5,8 @@
  * that render UI components. Unlike frontend tools, these are backend
  * tools that return structured data to be rendered on the frontend.
  *
- * Backend: /api/v1/examples/agentic_generative_ui/
+ * Backend: managed AG-UI agent runtime (agentspec: example-agentic-generative-ui)
  */
 import React from 'react';
-/**
- * AgUiToolsBasedGenUiExample Component
- *
- * Demonstrates tool-based generative UI with AG-UI.
- * The agent uses tools (create_plan, update_plan_step) that emit
- * STATE_SNAPSHOT and STATE_DELTA events to update the UI.
- *
- * Features demonstrated:
- * - STATE_SNAPSHOT events for full state updates
- * - STATE_DELTA events with JSON Patch for incremental updates
- * - Real-time UI updates as agent works
- * - Interactive step selection with Confirm/Reject buttons
- */
 declare const AgUiToolsBasedGenUiExample: React.FC;
 export default AgUiToolsBasedGenUiExample;

package/lib/examples/AgUiToolsBasedGenUiExample.js

@@ -10,16 +10,17 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * that render UI components. Unlike frontend tools, these are backend
  * tools that return structured data to be rendered on the frontend.
  *
- * Backend: /api/v1/examples/agentic_generative_ui/
+ * Backend: managed AG-UI agent runtime (agentspec: example-agentic-generative-ui)
  */
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useMemo } from 'react';
 import { Text, ProgressBar, Button } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider, useThemeBrandColor } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
 import { CheckCircleIcon, CircleIcon, DotFillIcon, CheckIcon, XIcon, } from '@primer/octicons-react';
-// AG-UI endpoint for agentic generative UI example
-const AGENTIC_GENERATIVE_UI_ENDPOINT = 'http://localhost:8765/api/v1/examples/agentic_generative_ui/';
 /**
  * PlanStepItem Component
  * Renders a single plan step with status indicator and optional click handler
@@ -168,8 +169,22 @@ const PlanDisplay = ({ plan, isInteractive = true, onStepToggle, onConfirm, onRe
  * - Real-time UI updates as agent works
  * - Interactive step selection with Confirm/Reject buttons
  */
+const AGENT_NAME = 'ag-ui-generative-ui';
+const AGENTSPEC_ID = 'example-agentic-generative-ui';
 const AgUiToolsBasedGenUiExample = () => {
     const brandColor = useThemeBrandColor();
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const agentName = useMemo(() => uniqueAgentId(AGENT_NAME), []);
+    const { agentId } = useExampleAgentRuntime({
+        exampleId: 'AgUiToolsBasedGenUiExample',
+        agentName,
+        specId: AGENTSPEC_ID,
+        agentConfig: {
+            protocol: 'ag-ui',
+            agentSpecId: AGENTSPEC_ID,
+        },
+    });
+    const agenticGenerativeUiEndpoint = agentId != null ? `${baseUrl}/api/v1/ag-ui/${agentId}/` : undefined;
     const [plan, setPlan] = useState(null);
     const [decision, setDecision] = useState(null);
     // Handle state updates from AG-UI events
@@ -244,7 +259,7 @@ const AgUiToolsBasedGenUiExample = () => {
                                                 marginTop: 1,
                                                 fontSize: 1,
                                                 color: 'fg.muted',
-                                            }, children: [_jsx("li", { children: "STATE_SNAPSHOT - Full state replacement" }), _jsx("li", { children: "STATE_DELTA - Incremental JSON Patch updates (RFC 6902)" }), _jsx("li", { children: "TOOL_CALL_START / TOOL_CALL_END - Tool execution tracking" })] })] })] })] }), _jsx(ChatFloating, { protocol: "ag-ui", endpoint: AGENTIC_GENERATIVE_UI_ENDPOINT, title: "Plan Generator", description: "I can create detailed plans and update them in real-time.", position: "bottom-right", brandColor: brandColor, onStateUpdate: handleStateUpdate, suggestions: [
+                                            }, children: [_jsx("li", { children: "STATE_SNAPSHOT - Full state replacement" }), _jsx("li", { children: "STATE_DELTA - Incremental JSON Patch updates (RFC 6902)" }), _jsx("li", { children: "TOOL_CALL_START / TOOL_CALL_END - Tool execution tracking" })] })] })] })] }), agenticGenerativeUiEndpoint && (_jsx(ChatFloating, { protocol: "ag-ui", endpoint: agenticGenerativeUiEndpoint, title: "Plan Generator", description: "I can create detailed plans and update them in real-time.", position: "bottom-right", brandColor: brandColor, onStateUpdate: handleStateUpdate, suggestions: [
                         {
                             title: 'Project plan',
                             message: 'Create a project plan for building a mobile app.',
@@ -253,6 +268,6 @@ const AgUiToolsBasedGenUiExample = () => {
                             title: 'Marketing strategy',
                             message: 'Generate a marketing strategy for a new product launch.',
                         },
-                    ] })] }) }));
+                    ] }))] }) }));
 };
 export default AgUiToolsBasedGenUiExample;

package/lib/examples/AgentCheckpointsExample.d.ts

@@ -11,7 +11,7 @@
  *   3. Provides pause/resume/terminate lifecycle backed by CRIU
  *
  * Prerequisites:
- *   - Datalayer core configuration (runtimesRunUrl, aiagentsRunUrl)
+ *   - Datalayer core configuration (runtimesUrl, aiAgentsUrl)
  *   - Valid IAM token (set via SignInSimple or iamStore)
  */
 import React from 'react';

package/lib/examples/AgentCheckpointsExample.js

@@ -16,7 +16,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  *   3. Provides pause/resume/terminate lifecycle backed by CRIU
  *
  * Prerequisites:
- *   - Datalayer core configuration (runtimesRunUrl, aiagentsRunUrl)
+ *   - Datalayer core configuration (runtimesUrl, aiAgentsUrl)
  *   - Valid IAM token (set via SignInSimple or iamStore)
  */
 /// <reference types="vite/client" />
@@ -29,7 +29,7 @@ import { AuthRequiredView, ErrorView } from './components';
 import { ThemedProvider } from './utils/themedProvider';
 import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { Chat } from '../chat';
-import { useAgentRuntimes, useAgentRuntimesQuery, useRefreshAgentRuntimes, useDeleteAgentRuntime, } from '../hooks/useAgentRuntimes';
+import { useAgentsRuntimes, useAgentRuntimes, useAgentRuntimesQuery, useRefreshAgentRuntimes, } from '../hooks/useAgentRuntimes';
 import { useAgentLifecycle } from '../hooks/useCheckpoints';
 import { useDeletePausedAgentRuntime } from '../hooks/useCheckpoints';
 import { AGENT_STATUS_COLORS } from '../types/agents';
@@ -106,10 +106,9 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
     });
     // Agent runtimes from the focused hook
     const { data: agentRuntimes } = useAgentRuntimesQuery();
+    const { terminateRuntimeByPod } = useAgentsRuntimes();
     const refetchRuntimes = useRefreshAgentRuntimes();
-    const deleteRuntimeMutation = useDeleteAgentRuntime();
     const deletePausedRuntimeMutation = useDeletePausedAgentRuntime();
-    const deleteRuntimeByPod = deleteRuntimeMutation.mutateAsync;
     const deletePausedRuntimeByPod = deletePausedRuntimeMutation.mutateAsync;
     const [isStarting, setIsStarting] = useState(false);
     const [sidebarOpen, setSidebarOpen] = useState(true);
@@ -246,7 +245,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
                 await deletePausedRuntimeByPod(agent.podName);
             }
             else {
-                await deleteRuntimeByPod(agent.podName);
+                await terminateRuntimeByPod(agent.podName);
             }
             // Ensure sidebar terminate resets to the home state like header terminate.
             if (isCurrentRuntime || isLastKnownRuntime) {
@@ -262,7 +261,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
         }
     }, [
         deletePausedRuntimeByPod,
-        deleteRuntimeByPod,
+        terminateRuntimeByPod,
         refreshAgents,
         refreshCheckpoints,
         runningAgents,
@@ -286,7 +285,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
     }
     // ── Running / Paused ─────────────────────────────────────────────────────
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [_jsxs(Box, { sx: {
@@ -436,7 +435,7 @@ const AgentCheckpointsInner = ({ onLogout, }) => {
                                 gap: 3,
                                 px: 3,
                             }, children: [_jsx(AgentIcon, { size: 48 }), _jsx(Heading, { as: "h2", sx: { fontSize: 3 }, children: "Checkpoint Agent" }), _jsxs(Text, { sx: { color: 'fg.muted', textAlign: 'center', maxWidth: 560 }, children: ["Launch a cloud agent runtime with pause/resume checkpointing. The agent will be deployed from the", ' ', _jsx("strong", { children: AGENTSPEC_ID }), " spec."] }), displayError && (_jsx(Flash, { variant: "danger", sx: { maxWidth: 560, width: '100%' }, children: displayError })), _jsx(Button, { variant: "primary", size: "large", leadingVisual: PlayIcon, onClick: handleLaunch, children: "Launch Agent" })] })) : (isReady || runtimeStatus === 'resumed') &&
-                            runtimeStatus !== 'paused' ? (_jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, title: "Monitor Sales KPI Agent", brandIcon: _jsx(AgentIcon, { size: 16 }), placeholder: "Ask about sales KPIs\u2026", description: "Monitor Sales KPI agent with pause/resume checkpointing", showHeader: false, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
+                            runtimeStatus !== 'paused' ? (_jsx(Chat, { protocol: "vercel-ai", baseUrl: agentBaseUrl, agentId: agentId, title: "Monitor Sales KPI Agent", brandIcon: _jsx(AgentIcon, { size: 16 }), placeholder: "Ask about sales KPIs\u2026", description: "Monitor Sales KPI agent with pause/resume checkpointing", showHeader: true, showTokenUsage: true, autoFocus: true, height: "100%", runtimeId: podName, historyEndpoint: `${agentBaseUrl}/api/v1/history`, suggestions: [
                                 {
                                     title: 'KPIs',
                                     message: "Show me today's sales KPI dashboard",
@@ -464,7 +463,7 @@ const AgentCheckpointsExample = () => {
     useEffect(() => {
         if (token && !hasSynced.current) {
             hasSynced.current = true;
-            import('@datalayer/core/lib/state').then(({ iamStore }) => {
+            import('../state/substates').then(({ iamStore }) => {
                 iamStore.setState({ token });
             });
         }
@@ -474,7 +473,7 @@ const AgentCheckpointsExample = () => {
     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/AgentCodemodeExample.js

@@ -529,7 +529,7 @@ const AgentCodemodeInner = ({ onLogout, }) => {
         return null;
     }
     return (_jsxs(Box, { sx: {
-            height: 'calc(100vh - 60px)',
+            height: '100%',
             display: 'flex',
             flexDirection: 'column',
         }, children: [_jsxs(Box, { sx: {
@@ -662,7 +662,7 @@ const AgentCodemodeInner = ({ onLogout, }) => {
                     })())] })] }));
 };
 const syncTokenToIamStore = (token) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token });
     });
 };
@@ -678,7 +678,7 @@ const AgentCodemodeExample = () => {
     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/AgentEvalsExample.js

@@ -80,7 +80,7 @@ const AgentEvalsInner = ({ onLogout, executionTarget, onExecutionTargetChange })
     const cloudRuntimeBaseUrl = useMemo(() => {
         const envRuntimesUrl = normalizeHttpUrl(import.meta.env.VITE_DATALAYER_RUNTIMES_URL);
         const envAgentRuntimesUrl = normalizeHttpUrl(import.meta.env.VITE_DATALAYER_AGENT_RUNTIMES_URL);
-        const configuredRuntimesUrl = normalizeHttpUrl(configuration?.runtimesRunUrl);
+        const configuredRuntimesUrl = normalizeHttpUrl(configuration?.runtimesUrl);
         if (envRuntimesUrl && !isLocalhostUrl(envRuntimesUrl)) {
             return envRuntimesUrl;
         }
@@ -91,7 +91,7 @@ const AgentEvalsInner = ({ onLogout, executionTarget, onExecutionTargetChange })
             return envAgentRuntimesUrl;
         }
         return 'https://r1.datalayer.run';
-    }, [configuration?.runtimesRunUrl]);
+    }, [configuration?.runtimesUrl]);
     const { runtime, status: runtimeStatus, isReady, error: hookError, runtimeCreationBaseUrl, } = useAgentRuntimes({
         agentSpecId: AGENTSPEC_ID,
         autoStart: executionTarget === 'cloud',
@@ -123,7 +123,7 @@ const AgentEvalsInner = ({ onLogout, executionTarget, onExecutionTargetChange })
         ? `local:${agentId}`
         : runtime?.podName || '(launching…)';
     const controlPlaneBaseUrl = import.meta.env.VITE_RUN_URL ||
-        configuration?.runUrl ||
+        configuration?.datalayerUrl ||
         (cloudAgentBaseUrl ? new URL(cloudAgentBaseUrl).origin : '');
     const isAgentReady = executionTarget === 'local' ? localStatus === 'ready' : isReady;
     const agentStatus = executionTarget === 'local' ? localStatus : runtimeStatus;
@@ -466,7 +466,7 @@ const AgentEvalsInner = ({ onLogout, executionTarget, onExecutionTargetChange })
 };
 // ─── Sync token to core IAM store ──────────────────────────────────────────
 const syncTokenToIamStore = (token) => {
-    import('@datalayer/core/lib/state').then(({ iamStore }) => {
+    import('../state/substates').then(({ iamStore }) => {
         iamStore.setState({ token });
     });
 };
@@ -484,7 +484,7 @@ const AgentEvalsExample = () => {
     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/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, "..."] })] }) }));