@datalayer/agent-runtimes 1.0.17 → 1.0.18

package/lib/examples/AgentCodeSandboxesExample.d.ts

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

package/lib/examples/AgentCodeSandboxesExample.js

@@ -0,0 +1,192 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/// <reference types="vite/client" />
+import { useCallback, useMemo, useState } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { Button, Heading, Label, Spinner, Text } from '@primer/react';
+import { PackageIcon } from '@primer/octicons-react';
+import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
+import { ThemedProvider } from './utils/themedProvider';
+import { AuthRequiredView, ErrorView } from './components';
+import { uniqueAgentId } from './utils/agentId';
+import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { Chat } from '../chat';
+const SANDBOX_SPEC_OPTIONS = [
+    {
+        variant: 'eval',
+        specId: 'example-sandbox-eval',
+        title: 'Eval Sandbox',
+        description: 'In-process Python execution for quick local iteration.',
+    },
+    {
+        variant: 'jupyter',
+        specId: 'example-sandbox-jupyter',
+        title: 'Jupyter Sandbox',
+        description: 'Kernel-backed execution with notebook-compatible behavior.',
+    },
+    {
+        variant: 'docker',
+        specId: 'example-sandbox-docker',
+        title: 'Docker Sandbox',
+        description: 'Containerized execution for stronger process isolation.',
+    },
+    {
+        variant: 'datalayer',
+        specId: 'example-sandbox-datalayer',
+        title: 'Datalayer Sandbox',
+        description: 'Cloud sandbox runtime powered by Datalayer environments.',
+    },
+    {
+        variant: 'colab',
+        specId: 'example-sandbox-colab',
+        title: 'Colab Sandbox',
+        description: 'Google Colab runtime connector (reuse an already-running kernel).',
+    },
+    {
+        variant: 'kaggle',
+        specId: 'example-sandbox-kaggle',
+        title: 'Kaggle Sandbox',
+        description: 'Kaggle runtime connector (create kernel with API token or attach existing).',
+    },
+    {
+        variant: 'monty',
+        specId: 'example-sandbox-monty',
+        title: 'Monty Sandbox',
+        description: 'Secure in-process interpreter focused on safe snippets.',
+    },
+    {
+        variant: 'modal',
+        specId: 'example-sandbox-modal',
+        title: 'Modal Sandbox',
+        description: 'Modal cloud sandbox for scalable remote code execution.',
+    },
+];
+const AgentCodeSandboxesInner = ({ onLogout, }) => {
+    const { token } = useSimpleAuthStore();
+    const baseUrl = useExampleAgentRuntimesUrl();
+    const [selectedSpecId, setSelectedSpecId] = useState(SANDBOX_SPEC_OPTIONS[0].specId);
+    const [agentId, setAgentId] = useState(null);
+    const [activeSpecId, setActiveSpecId] = useState(null);
+    const [isLaunching, setIsLaunching] = useState(false);
+    const [error, setError] = useState(null);
+    const selectedOption = useMemo(() => SANDBOX_SPEC_OPTIONS.find(option => option.specId === selectedSpecId) ??
+        SANDBOX_SPEC_OPTIONS[0], [selectedSpecId]);
+    const activeOption = useMemo(() => SANDBOX_SPEC_OPTIONS.find(option => option.specId === activeSpecId) ??
+        selectedOption, [activeSpecId, selectedOption]);
+    const authFetch = useCallback((url, opts = {}) => fetch(url, {
+        ...opts,
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            ...(opts.headers ?? {}),
+        },
+    }), [token]);
+    const launchAgent = useCallback(async () => {
+        setIsLaunching(true);
+        setError(null);
+        try {
+            if (agentId) {
+                await authFetch(`${baseUrl}/api/v1/agents/${agentId}`, {
+                    method: 'DELETE',
+                }).catch(() => {
+                    // Ignore teardown errors while switching specs.
+                });
+            }
+            const agentName = uniqueAgentId(`code-sandbox-${selectedOption.variant}`);
+            const response = await authFetch(`${baseUrl}/api/v1/agents`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    name: agentName,
+                    description: `Code sandbox demo (${selectedOption.variant})`,
+                    agent_library: 'pydantic-ai',
+                    transport: 'vercel-ai',
+                    agent_spec_id: selectedOption.specId,
+                    enable_codemode: true,
+                    enable_skills: true,
+                    tools: [],
+                }),
+            });
+            if (!response.ok) {
+                const contentType = response.headers.get('content-type') || '';
+                let detail = '';
+                if (contentType.includes('application/json')) {
+                    const payload = await response.json().catch(() => null);
+                    detail =
+                        (typeof payload?.detail === 'string' && payload.detail) ||
+                            (typeof payload?.message === 'string' && payload.message) ||
+                            '';
+                }
+                else {
+                    detail = await response.text().catch(() => '');
+                }
+                throw new Error(detail || `Failed to create agent (${response.status})`);
+            }
+            const payload = await response.json();
+            const createdAgentId = payload?.id || agentName;
+            setAgentId(createdAgentId);
+            setActiveSpecId(selectedOption.specId);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : 'Failed to launch agent');
+        }
+        finally {
+            setIsLaunching(false);
+        }
+    }, [agentId, authFetch, baseUrl, selectedOption]);
+    if (!agentId) {
+        return (_jsxs(Box, { sx: {
+                maxWidth: 840,
+                mx: 'auto',
+                mt: 6,
+                px: 3,
+                py: 3,
+                border: '1px solid',
+                borderColor: 'border.default',
+                borderRadius: 2,
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 3,
+                bg: 'canvas.subtle',
+            }, children: [_jsx(Text, { sx: { fontSize: 0, fontWeight: 'bold', color: 'fg.muted' }, children: "SANDBOX VARIANT DEMO" }), _jsx(Heading, { as: "h2", sx: { fontSize: 3 }, children: "Agent Code Sandboxes" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Choose a sandbox variant-backed spec, launch the agent, then run code from chat to compare behavior across sandboxes." }), _jsxs(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: [_jsxs(Label, { variant: "accent", children: ["Spec: ", selectedOption.specId] }), _jsxs(Label, { variant: "secondary", children: ["Variant: ", selectedOption.variant] }), _jsx(Label, { variant: "success", children: "Codemode: enabled" })] }), _jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 600 }, children: "Sandbox Variant" }), _jsx("select", { value: selectedSpecId, onChange: event => {
+                                setSelectedSpecId(event.target.value);
+                            }, style: {
+                                width: '100%',
+                                maxWidth: 420,
+                                padding: '8px 10px',
+                                borderRadius: '6px',
+                                border: '1px solid var(--borderColor-default)',
+                                background: 'var(--bgColor-default)',
+                                color: 'var(--fgColor-default)',
+                            }, children: SANDBOX_SPEC_OPTIONS.map(option => (_jsxs("option", { value: option.specId, children: [option.title, " (", option.variant, ")"] }, option.specId))) }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 0 }, children: selectedOption.description })] }), _jsx(Button, { variant: "primary", onClick: () => {
+                        void launchAgent();
+                    }, disabled: isLaunching, sx: { width: '100%', maxWidth: 420 }, children: isLaunching ? (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "small" }), " Launching..."] })) : (`Launch ${selectedOption.title}`) }), error && _jsx(ErrorView, { error: error, onLogout: onLogout })] }));
+    }
+    return (_jsx(Chat, { protocol: "vercel-ai", baseUrl: baseUrl, agentId: agentId, runtimeId: agentId, title: `Code Sandboxes: ${activeOption.title}`, description: `Spec ${activeOption.specId} (${activeOption.variant})`, brandIcon: _jsx(PackageIcon, { size: 16 }), showHeader: true, showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, height: "100vh", historyEndpoint: `${baseUrl}/api/v1/history`, suggestions: [
+            {
+                title: 'Identify sandbox variant',
+                message: 'Use execute_code to print(os.getenv("DATALAYER_CODE_SANDBOX_VARIANT")) and summarize the result.',
+            },
+            {
+                title: 'Run numeric workload',
+                message: 'Use execute_code to compute sum(i*i for i in range(10000)) and report timing and result.',
+            },
+            {
+                title: 'Check package availability',
+                message: 'Use execute_code to import pandas and print(pandas.__version__).',
+            },
+        ], submitOnSuggestionClick: true }));
+};
+const AgentCodeSandboxesExample = () => {
+    const { token, clearAuth } = useSimpleAuthStore();
+    const handleLogout = useCallback(() => {
+        clearAuth();
+    }, [clearAuth]);
+    if (!token) {
+        return _jsx(AuthRequiredView, {});
+    }
+    return (_jsx(ThemedProvider, { children: _jsx(AgentCodeSandboxesInner, { onLogout: handleLogout }) }));
+};
+export default AgentCodeSandboxesExample;

package/lib/examples/example-selector.js

@@ -84,6 +84,7 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('CopilotKitNotebookExample', () => import('./CopilotKitNotebookExample'), 'CopilotKit integration with notebook workflows.'),
     makeEntry('AgentCheckpointsExample', () => import('./AgentCheckpointsExample'), 'Checkpoint and resume lifecycle for agents.'),
     makeEntry('AgentCodemodeExample', () => import('./AgentCodemodeExample'), 'Code mode execution and tool orchestration example.'),
+    makeEntry('AgentCodeSandboxesExample', () => import('./AgentCodeSandboxesExample'), 'Launch sandbox-variant agent specs and compare code execution across backends.', ['example', 'agent', 'sandbox', 'codemode']),
     makeEntry('AgentEvalsExample', () => import('./AgentEvalsExample'), 'Evaluation workflows for agent outputs.'),
     makeEntry('AgentGuardrailsExample', () => import('./AgentGuardrailsExample'), 'Guardrails and safety checks for agent runs.'),
     makeEntry('AgentHooksExample', () => import('./AgentHooksExample'), 'Pre-hooks and post-hooks lifecycle execution example.'),

package/lib/examples/index.d.ts

@@ -18,6 +18,7 @@ export { default as CustomExample } from './ChatCustomExample';
 export { default as NotebookCollaborationExample } from './NotebookCollaborationExample';
 export { default as AgentCheckpointsExample } from './AgentCheckpointsExample';
 export { default as AgentCodemodeExample } from './AgentCodemodeExample';
+export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
 export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';

package/lib/examples/index.js

@@ -22,6 +22,7 @@ export { default as CustomExample } from './ChatCustomExample';
 export { default as NotebookCollaborationExample } from './NotebookCollaborationExample';
 export { default as AgentCheckpointsExample } from './AgentCheckpointsExample';
 export { default as AgentCodemodeExample } from './AgentCodemodeExample';
+export { default as AgentCodeSandboxesExample } from './AgentCodeSandboxesExample';
 export { default as AgentEvalsExample } from './AgentEvalsExample';
 export { default as AgentGuardrailsExample } from './AgentGuardrailsExample';
 export { default as AgentHooksExample } from './AgentHooksExample';

package/lib/specs/agents/agents.d.ts

@@ -29,6 +29,14 @@ export declare const EXAMPLE_ONE_TRIGGER_AGENTSPEC_0_0_1: Agentspec;
 export declare const EXAMPLE_OTEL_AGENTSPEC_0_0_1: Agentspec;
 export declare const EXAMPLE_OUTPUT_AGENTSPEC_0_0_1: Agentspec;
 export declare const EXAMPLE_PARAMETERS_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_COLAB_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_DATALAYER_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_DOCKER_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_EVAL_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_JUPYTER_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_KAGGLE_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_MODAL_AGENTSPEC_0_0_1: Agentspec;
+export declare const EXAMPLE_SANDBOX_MONTY_AGENTSPEC_0_0_1: Agentspec;
 export declare const EXAMPLE_SHARED_STATE_AGENTSPEC_0_0_1: Agentspec;
 export declare const EXAMPLE_SIMPLE_AGENTSPEC_0_0_1: Agentspec;
 export declare const EXAMPLE_SKILLS_AGENTSPEC_0_0_1: Agentspec;

package/lib/specs/agents/agents.js

@@ -1521,6 +1521,438 @@ export const EXAMPLE_PARAMETERS_AGENTSPEC_0_0_1 = {
     },
     subagents: undefined,
 };
+export const EXAMPLE_SANDBOX_COLAB_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-colab',
+    version: '0.0.1',
+    name: 'Example Sandbox Colab Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'colab' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'colab'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'E',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: colab')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the colab sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'colab',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_DATALAYER_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-datalayer',
+    version: '0.0.1',
+    name: 'Example Sandbox Datalayer Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'datalayer' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'datalayer'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'D',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: datalayer')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the datalayer sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'datalayer',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_DOCKER_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-docker',
+    version: '0.0.1',
+    name: 'Example Sandbox Docker Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'docker' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'docker'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'C',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: docker')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the docker sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'docker',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_EVAL_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-eval',
+    version: '0.0.1',
+    name: 'Example Sandbox Eval Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'eval' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'eval'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'A',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: eval')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the eval sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'eval',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_JUPYTER_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-jupyter',
+    version: '0.0.1',
+    name: 'Example Sandbox Jupyter Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'jupyter' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'jupyter'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'B',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: jupyter')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the jupyter sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'jupyter',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_KAGGLE_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-kaggle',
+    version: '0.0.1',
+    name: 'Example Sandbox Kaggle Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'kaggle' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'kaggle'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'H',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: kaggle')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the kaggle sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'kaggle',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_MODAL_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-modal',
+    version: '0.0.1',
+    name: 'Example Sandbox Modal Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'modal' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'modal'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'G',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: modal')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the modal sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'modal',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
+export const EXAMPLE_SANDBOX_MONTY_AGENTSPEC_0_0_1 = {
+    id: 'example-sandbox-monty',
+    version: '0.0.1',
+    name: 'Example Sandbox Monty Agent',
+    description: `Demonstration agent configured to run codemode code execution with the 'monty' sandbox variant.`,
+    tags: ['sandbox', 'codemode', 'monty'],
+    enabled: true,
+    model: 'bedrock:us.anthropic.claude-opus-4-8',
+    mcpServers: [MCP_SERVER_MAP['tavily:0.0.1']],
+    skills: [
+        SKILL_MAP['events:0.0.1']
+            ? toAgentSkillSpec(SKILL_MAP['events:0.0.1'])
+            : undefined,
+    ].filter(Boolean),
+    tools: [TOOL_MAP['runtime-echo:0.0.1']],
+    frontendTools: [
+        FRONTEND_TOOL_MAP['jupyter-notebook:0.0.1'],
+        FRONTEND_TOOL_MAP['lexical-document:0.0.1'],
+    ],
+    environmentName: 'ai-agents-env',
+    icon: 'package',
+    emoji: 'F',
+    color: '#1F6FEB',
+    suggestions: [
+        "Use execute_code to print('sandbox variant: monty')",
+        'Use execute_code to compute sum(i*i for i in range(20))',
+        'Use execute_code to load pandas and build a small DataFrame',
+    ],
+    welcomeMessage: "You're connected to the monty sandbox variant demo. Ask me to run Python code and I will use execute_code in codemode.",
+    welcomeNotebook: undefined,
+    welcomeDocument: undefined,
+    sandboxVariant: 'monty',
+    systemPrompt: `You are a sandbox-variant demonstration assistant. Prefer executing Python code via execute_code for computations, data checks, and quick experiments, then summarize results clearly.`,
+    systemPromptCodemodeAddons: `Always use execute_code when the user requests calculations, scripts, DataFrame operations, package checks, or shell-style diagnostics.`,
+    goal: undefined,
+    protocol: undefined,
+    uiExtension: undefined,
+    trigger: undefined,
+    modelConfig: undefined,
+    mcpServerTools: undefined,
+    guardrails: undefined,
+    evals: undefined,
+    codemode: { enabled: true, token_reduction: '~80%', speedup: '~1.5x' },
+    output: undefined,
+    advanced: undefined,
+    authorizationPolicy: undefined,
+    notifications: undefined,
+    memory: 'ephemeral',
+    preHooks: undefined,
+    postHooks: undefined,
+    toolHooks: undefined,
+    parameters: undefined,
+    subagents: undefined,
+};
 export const EXAMPLE_SHARED_STATE_AGENTSPEC_0_0_1 = {
     id: 'example-shared-state',
     version: '0.0.1',
@@ -6301,6 +6733,14 @@ export const AGENTSPECS = {
     'example-otel': EXAMPLE_OTEL_AGENTSPEC_0_0_1,
     'example-output': EXAMPLE_OUTPUT_AGENTSPEC_0_0_1,
     'example-parameters': EXAMPLE_PARAMETERS_AGENTSPEC_0_0_1,
+    'example-sandbox-colab': EXAMPLE_SANDBOX_COLAB_AGENTSPEC_0_0_1,
+    'example-sandbox-datalayer': EXAMPLE_SANDBOX_DATALAYER_AGENTSPEC_0_0_1,
+    'example-sandbox-docker': EXAMPLE_SANDBOX_DOCKER_AGENTSPEC_0_0_1,
+    'example-sandbox-eval': EXAMPLE_SANDBOX_EVAL_AGENTSPEC_0_0_1,
+    'example-sandbox-jupyter': EXAMPLE_SANDBOX_JUPYTER_AGENTSPEC_0_0_1,
+    'example-sandbox-kaggle': EXAMPLE_SANDBOX_KAGGLE_AGENTSPEC_0_0_1,
+    'example-sandbox-modal': EXAMPLE_SANDBOX_MODAL_AGENTSPEC_0_0_1,
+    'example-sandbox-monty': EXAMPLE_SANDBOX_MONTY_AGENTSPEC_0_0_1,
     'example-shared-state': EXAMPLE_SHARED_STATE_AGENTSPEC_0_0_1,
     'example-simple': EXAMPLE_SIMPLE_AGENTSPEC_0_0_1,
     'example-skills': EXAMPLE_SKILLS_AGENTSPEC_0_0_1,

package/lib/types/agentspecs.d.ts

@@ -63,7 +63,7 @@ export interface Agentspec {
     welcomeNotebook?: string;
     /** Path to Lexical document to show on agent creation */
     welcomeDocument?: string;
-    /** Sandbox variant to use for this agent ('eval', 'jupyter') */
+    /** Sandbox variant to use for this agent (e.g. 'eval', 'jupyter', 'kaggle'). */
     sandboxVariant?: string;
     /** User-facing objective for the agent */
     goal?: string;

package/lib/types/config.d.ts

@@ -33,7 +33,7 @@ export interface AgentConfig {
     inferenceProvider?: string;
     /** Enable codemode if supported by the selected spec/runtime. */
     enableCodemode?: boolean;
-    /** Optional sandbox variant (e.g. eval, jupyter). */
+    /** Optional sandbox variant (e.g. eval, jupyter, kaggle). */
     sandboxVariant?: string;
     /** Optional Jupyter sandbox URL for jupyter-backed sandbox mode. */
     jupyterSandbox?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/agent-runtimes",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "type": "module",
   "workspaces": [
     ".",

package/scripts/codegen/generate_sandbox_agents.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""Generate example sandbox agent specs for each sandbox variant.
+
+This keeps sandbox demonstration specs aligned with supported sandbox variants
+so examples can offer a consistent variant picker.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+VARIANTS: tuple[str, ...] = (
+    "eval",
+    "jupyter",
+    "docker",
+    "datalayer",
+    "colab",
+    "kaggle",
+    "monty",
+    "modal",
+)
+
+
+def _emoji_for_variant(variant: str) -> str:
+    mapping = {
+        "eval": "A",
+        "jupyter": "B",
+        "docker": "C",
+        "datalayer": "D",
+        "colab": "E",
+        "kaggle": "H",
+        "monty": "F",
+        "modal": "G",
+    }
+    return mapping.get(variant, "A")
+
+
+def _content_for_variant(variant: str) -> str:
+    variant_title = variant.capitalize()
+    spec_id = f"example-sandbox-{variant}"
+    emoji = _emoji_for_variant(variant)
+
+    return f"""# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+# Agent Specification: Sandbox Variant ({variant})
+
+id: {spec_id}
+version: 0.0.1
+name: Example Sandbox {variant_title} Agent
+description: >-
+  Demonstration agent configured to run codemode code execution with the
+  '{variant}' sandbox variant.
+
+tags:
+  - sandbox
+  - codemode
+  - {variant}
+
+enabled: true
+model: "bedrock:us.anthropic.claude-opus-4-8"
+
+sandbox_variant: {variant}
+memory: ephemeral
+
+mcp_servers:
+  - tavily:0.0.1
+
+skills:
+  - events:0.0.1
+
+tools:
+  - runtime-echo:0.0.1
+
+frontend_tools:
+  - jupyter-notebook:0.0.1
+  - lexical-document:0.0.1
+
+environment_name: ai-agents-env
+
+icon: package
+emoji: "{emoji}"
+color: "#1F6FEB"
+
+suggestions:
+  - "Use execute_code to print('sandbox variant: {variant}')"
+  - "Use execute_code to compute sum(i*i for i in range(20))"
+  - "Use execute_code to load pandas and build a small DataFrame"
+
+welcome_message: >-
+  You're connected to the {variant} sandbox variant demo. Ask me to run
+  Python code and I will use execute_code in codemode.
+
+system_prompt: >-
+  You are a sandbox-variant demonstration assistant. Prefer executing
+  Python code via execute_code for computations, data checks, and quick
+  experiments, then summarize results clearly.
+
+system_prompt_codemode_addons: >-
+  Always use execute_code when the user requests calculations, scripts,
+  DataFrame operations, package checks, or shell-style diagnostics.
+
+codemode:
+  enabled: true
+  token_reduction: "~80%"
+  speedup: "~1.5x"
+
+welcome_notebook: null
+welcome_document: null
+trigger: null
+"""
+
+
+def generate_specs(agents_dir: Path) -> int:
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for variant in VARIANTS:
+        path = agents_dir / f"example-sandbox-{variant}.yaml"
+        path.write_text(_content_for_variant(variant), encoding="utf-8")
+        count += 1
+    return count
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate example sandbox agentspec files by sandbox variant."
+    )
+    parser.add_argument(
+        "--agents-dir",
+        type=Path,
+        required=True,
+        help="Path to agentspecs/agents directory.",
+    )
+    args = parser.parse_args()
+
+    generated = generate_specs(args.agents_dir)
+    print(f"Generated {generated} sandbox variant agentspec files in {args.agents_dir}")
+
+
+if __name__ == "__main__":
+    main()