@datalayer/agent-runtimes 0.0.2

package/LICENSE

@@ -0,0 +1,32 @@
+
+BSD 3-Clause License
+
+Copyright (c) 2022, Datalayer
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+This contains code taken from https://github.com/jupyter/jupyter_core

package/README.md

@@ -0,0 +1,56 @@
+<!--
+  ~ Copyright (c) 2025-2026 Datalayer, Inc.
+  ~
+  ~ BSD 3-Clause License
+
+
+So your goal is to require approval for all or only some tools on that MCP server? And then to present the approval to the user using the Vercel AI integration?
+yes, that is my goal to implement https://github.com/datalayer/jupyter-ai-agents/issues/53
+
+
+As you know, Vercel AI Element are just React UI components, it is up to the developer to implement such features.
+I believe it's a little bit more than that because of the Data Stream Protocol they implement: https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol#data-stream-protocol, that we support as well: https://ai.pydantic.dev/ui/vercel-ai/, so you don't just get the components but also the automatic rendering of the chat interface based on the events that are coming from the server. Right?
+The vercel ai-element tool approval has been merged 3 weeks ago https://github.com/vercel/ai-elements/pull/163
+That's great! It doesn't look like they have events for that in the Data Stream Protocol yet though, so it's not clear how they expect agent backends to represent tool calls that require approval, or how they'll send approval to the backend...
+I guess having a kind of reference implementation for common use cases/patterns will be good for the community. I would say that kind of case (external mcp server with tool approval like done by eg claude desktop) is quite common, or will become common
+Definitely, which is partly why github.com/pydantic/pydantic-ai/issues/3295 exists, but there's currently a missing link in how approvals should be represented on the event stream going from agent to frontend, and in approval results going from frontend to agent. I'd expect Vercel AI to come up with something sooner rather than later since they have their own (TypeScript) agent SDK as well, which they'd then document in the Data Stream Protocol, which we can then support as well.
+In the meantime, you could do something like this:
+Wrap your MCPServer in ApprovalRequiredToolset (assuming all tools require approval). This means that when any of the tools are called, the agent run will end with a DeferredToolRequests object as result.output
+When you use VercelAIAdapter.dispatch_request, you can add an on_complete handler that is passed the AgentRunResult and can yield additional Vercel AI events. In that handler, you can check result.output , and if it's DeferredToolRequests , you can yield a custom pydantic_ai.ui.vercel_ai.response_types.DataChunk wrapping those deferred tool requests, which will be sent to frontend
+On the frontend you can handle that custom data part by showing the user the tool call that needs approval
+When the user approves, you'll need to perform a new request to the backend containing that approval, by listing the approved tool_call_ids on the SubmitMessage payload (I'm not an expert on how this part of AI Elements works...)
+In the backend endpoint, you then have to parse this value out of the SubmitMessage payload (similar to this: https://github.com/pydantic/ai-chat-ui/blob/b0ac18d2dbbef3cf1636c17a29fb7578a59b32c8/agent/chatbot/server.py#L115-L122), turn it into a DeferredToolResults object and pass it to the dispatch/run method as deferred_tool_results
+
+-->
+
+[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)
+
+[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
+
+# 🤖 Agent Runtimes
+
+[![Github Actions Status](https://github.com/datalayer/code-sandboxes/workflows/Build/badge.svg)](https://github.com/datalayer/code-sandboxes/actions/workflows/build.yml)
+[![PyPI - Version](https://img.shields.io/pypi/v/code-sandboxes)](https://pypi.org/project/code-sandboxes)
+
+**Agent Runtimes** is a flexible server framework for exposing AI agents through multiple protocols.
+
+## 🌟 Features
+
+### Multi-Protocol Support
+- **ACP (Agent Client Protocol)**: WebSocket-based standard protocol
+- **Vercel AI SDK**: Compatible with Vercel's AI SDK for React/Next.js
+- **AG-UI**: Lightweight web interface (Pydantic AI native)
+- **MCP-UI**: Interactive UI resources protocol with React/Web Components
+- **A2A**: Agent-to-agent communication
+
+### Multi-Agent Support  
+- **Pydantic AI**: Type-safe agents (fully implemented)
+- **LangChain**: Complex workflows (adapter ready)
+- **Jupyter AI**: Notebook integration (adapter ready)
+
+### Built-in Features
+- 🔌 **Adapter Architecture**: Easy to add new agents and protocols
+- 🛠️ **Tool Support**: MCP, custom tools, built-in utilities
+- 📊 **Observability**: OpenTelemetry integration
+- 💾 **Persistence**: DBOS support for durable execution
+- 🔒 **Context Optimization**: LLM context management

package/lib/App.css

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  /*  text-align: center; */
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

package/lib/App.d.ts

@@ -0,0 +1,3 @@
+import './App.css';
+export declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/lib/App.js

@@ -0,0 +1,18 @@
+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 { useJupyter, JupyterReactTheme } from '@datalayer/jupyter-react';
+import { JupyterCellExample } from './examples/JupyterCellExample';
+import { JupyterNotebookExample } from './examples/JupyterNotebookExample';
+import './App.css';
+export function App() {
+    const { serviceManager } = useJupyter({
+        jupyterServerUrl: 'https://oss.datalayer.run/api/jupyter-server',
+        jupyterServerToken: '60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6',
+        startDefaultKernel: true,
+    });
+    return (_jsxs(JupyterReactTheme, { children: [serviceManager && _jsx(JupyterCellExample, { serviceManager: serviceManager }), serviceManager && (_jsx(JupyterNotebookExample, { serviceManager: serviceManager }))] }));
+}
+export default App;

package/lib/components/chat/components/AgentDetails.d.ts

@@ -0,0 +1,19 @@
+export interface AgentDetailsProps {
+    /** Agent name/title */
+    name?: string;
+    /** Protocol being used */
+    protocol: string;
+    /** Endpoint URL */
+    url: string;
+    /** Number of messages in conversation */
+    messageCount: number;
+    /** Agent ID */
+    agentId?: string;
+    /** Callback to go back to chat view */
+    onBack: () => void;
+}
+/**
+ * AgentDetails component displays comprehensive information about the agent.
+ */
+export declare function AgentDetails({ name, protocol, url, messageCount, agentId, onBack, }: AgentDetailsProps): import("react/jsx-runtime").JSX.Element;
+export default AgentDetails;

package/lib/components/chat/components/AgentDetails.js

@@ -0,0 +1,170 @@
+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.
+/**
+ * AgentDetails component - Shows detailed information about the agent
+ * including name, protocol, URL, message count, and context details.
+ */
+import { ArrowLeftIcon, GlobeIcon, CommentDiscussionIcon, DatabaseIcon, FileIcon, ToolsIcon, ClockIcon, } from '@primer/octicons-react';
+import { Box, Button, Heading, IconButton, Text, Label, ProgressBar, } from '@primer/react';
+import { AiAgentIcon } from '@datalayer/icons-react';
+// Mock context data for display
+const MOCK_CONTEXT_DATA = {
+    name: 'Context',
+    totalTokens: 2520000,
+    usedTokens: 1523552,
+    children: [
+        {
+            name: 'Files',
+            value: 450000,
+            children: [
+                { name: 'app.py', value: 125000 },
+                { name: 'models.py', value: 98000 },
+                { name: 'routes.py', value: 112000 },
+                { name: 'utils.py', value: 115000 },
+            ],
+        },
+        {
+            name: 'Messages',
+            value: 380000,
+            children: [
+                { name: 'User messages', value: 180000 },
+                { name: 'Assistant responses', value: 200000 },
+            ],
+        },
+        {
+            name: 'Tools',
+            value: 220000,
+            children: [
+                { name: 'Code execution', value: 95000 },
+                { name: 'File operations', value: 75000 },
+                { name: 'Search', value: 50000 },
+            ],
+        },
+        {
+            name: 'Memory',
+            value: 473552,
+            children: [
+                { name: 'Short term', value: 150000 },
+                { name: 'Long term', value: 323552 },
+            ],
+        },
+    ],
+};
+/**
+ * Format token count for display
+ */
+function formatTokens(tokens) {
+    if (tokens >= 1000000) {
+        return `${(tokens / 1000000).toFixed(1)}M`;
+    }
+    if (tokens >= 1000) {
+        return `${(tokens / 1000).toFixed(1)}K`;
+    }
+    return tokens.toString();
+}
+/**
+ * Get icon for context category
+ */
+function getCategoryIcon(name) {
+    switch (name.toLowerCase()) {
+        case 'files':
+            return FileIcon;
+        case 'messages':
+            return CommentDiscussionIcon;
+        case 'tools':
+            return ToolsIcon;
+        case 'memory':
+            return DatabaseIcon;
+        default:
+            return ClockIcon;
+    }
+}
+/**
+ * AgentDetails component displays comprehensive information about the agent.
+ */
+export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, agentId, onBack, }) {
+    const contextUsagePercent = (MOCK_CONTEXT_DATA.usedTokens / MOCK_CONTEXT_DATA.totalTokens) * 100;
+    return (_jsxs(Box, { sx: {
+            display: 'flex',
+            flexDirection: 'column',
+            height: '100%',
+            bg: 'canvas.default',
+            overflow: 'auto',
+        }, children: [_jsxs(Box, { sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 2,
+                    p: 3,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                }, children: [_jsx(IconButton, { icon: ArrowLeftIcon, "aria-label": "Back to chat", variant: "invisible", onClick: onBack }), _jsx(Heading, { as: "h2", sx: { fontSize: 3, fontWeight: 'semibold' }, children: "Agent Details" })] }), _jsxs(Box, { sx: { p: 3, display: 'flex', flexDirection: 'column', gap: 4 }, children: [_jsxs(Box, { sx: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 3,
+                            p: 3,
+                            bg: 'canvas.subtle',
+                            borderRadius: 2,
+                            border: '1px solid',
+                            borderColor: 'border.default',
+                        }, children: [_jsx(Box, { sx: {
+                                    p: 2,
+                                    bg: 'accent.subtle',
+                                    borderRadius: 2,
+                                }, children: _jsx(AiAgentIcon, { colored: true, size: 32 }) }), _jsxs(Box, { sx: { flex: 1 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, fontWeight: 'semibold', mb: 1 }, children: name }), _jsxs(Box, { sx: { display: 'flex', gap: 2, alignItems: 'center' }, children: [_jsx(Label, { variant: "accent", size: "small", children: protocol.toUpperCase().replace(/-/g, ' ') }), agentId && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["ID: ", agentId] }))] })] })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                                    fontSize: 1,
+                                    fontWeight: 'semibold',
+                                    mb: 2,
+                                    color: 'fg.muted',
+                                }, children: "Connection" }), _jsx(Box, { sx: {
+                                    p: 3,
+                                    bg: 'canvas.subtle',
+                                    borderRadius: 2,
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                }, children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(GlobeIcon, { size: 16 }), _jsx(Text, { sx: {
+                                                fontSize: 1,
+                                                fontFamily: 'mono',
+                                                wordBreak: 'break-all',
+                                            }, children: url })] }) })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                                    fontSize: 1,
+                                    fontWeight: 'semibold',
+                                    mb: 2,
+                                    color: 'fg.muted',
+                                }, children: "Conversation" }), _jsxs(Box, { sx: {
+                                    p: 3,
+                                    bg: 'canvas.subtle',
+                                    borderRadius: 2,
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    gap: 2,
+                                }, children: [_jsx(CommentDiscussionIcon, { size: 16 }), _jsxs(Text, { sx: { fontSize: 1 }, children: [_jsx(Text, { as: "span", sx: { fontWeight: 'semibold' }, children: messageCount }), ' ', messageCount === 1 ? 'message' : 'messages'] })] })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                                    fontSize: 1,
+                                    fontWeight: 'semibold',
+                                    mb: 2,
+                                    color: 'fg.muted',
+                                }, children: "Context Usage" }), _jsxs(Box, { sx: {
+                                    p: 3,
+                                    bg: 'canvas.subtle',
+                                    borderRadius: 2,
+                                    border: '1px solid',
+                                    borderColor: 'border.default',
+                                }, children: [_jsxs(Box, { sx: { mb: 3 }, children: [_jsxs(Box, { sx: {
+                                                    display: 'flex',
+                                                    justifyContent: 'space-between',
+                                                    mb: 1,
+                                                }, children: [_jsxs(Text, { sx: { fontSize: 1, fontWeight: 'semibold' }, children: [formatTokens(MOCK_CONTEXT_DATA.usedTokens), " /", ' ', formatTokens(MOCK_CONTEXT_DATA.totalTokens), " tokens"] }), _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: [contextUsagePercent.toFixed(0), "%"] })] }), _jsx(ProgressBar, { progress: contextUsagePercent, sx: { height: 8 }, bg: contextUsagePercent > 80
+                                                    ? 'danger.emphasis'
+                                                    : 'accent.emphasis' })] }), _jsx(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: MOCK_CONTEXT_DATA.children.map(category => {
+                                            const CategoryIcon = getCategoryIcon(category.name);
+                                            const categoryPercent = (category.value / MOCK_CONTEXT_DATA.totalTokens) * 100;
+                                            return (_jsxs(Box, { sx: {
+                                                    display: 'flex',
+                                                    alignItems: 'center',
+                                                    gap: 2,
+                                                }, children: [_jsx(Box, { sx: { color: 'fg.muted', width: 20 }, children: _jsx(CategoryIcon, { size: 16 }) }), _jsx(Text, { sx: { fontSize: 1, flex: 1 }, children: category.name }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', minWidth: 60 }, children: formatTokens(category.value) }), _jsx(Box, { sx: { width: 80 }, children: _jsx(ProgressBar, { progress: categoryPercent, sx: { height: 4 } }) })] }, category.name));
+                                        }) })] })] }), _jsx(Box, { sx: { mt: 2 }, children: _jsx(Button, { variant: "primary", onClick: onBack, sx: { width: '100%' }, children: "Back to Chat" }) })] })] }));
+}
+export default AgentDetails;

package/lib/components/chat/components/Chat.d.ts

@@ -0,0 +1,105 @@
+import { type Suggestion } from './base/ChatBase';
+/**
+ * Supported transports (communication transports)
+ */
+export type Transport = 'ag-ui' | 'a2a' | 'acp' | 'vercel-ai' | 'vercel-ai-jupyter';
+/**
+ * Extension type for chat features
+ */
+export type Extension = 'mcp-ui' | 'a2ui';
+/**
+ * Chat props
+ */
+export interface ChatProps {
+    /** Transport to use */
+    transport: Transport;
+    /** Extensions for chat features */
+    extensions?: Extension[];
+    /** Base URL of the server (for HTTP-based protocols) */
+    baseUrl?: string;
+    /** WebSocket URL (for WebSocket-based protocols like ACP) */
+    wsUrl?: string;
+    /** Agent ID */
+    agentId?: string;
+    /** Custom placeholder text */
+    placeholder?: string;
+    /** Custom title */
+    title?: string;
+    /** Whether to auto-connect on mount */
+    autoConnect?: boolean;
+    /** Whether to use streaming (for protocols that support it) */
+    streaming?: boolean;
+    /** Callback when a message is sent */
+    onMessageSent?: (content: string) => void;
+    /** Callback when a response is received */
+    onMessageReceived?: (message: unknown) => void;
+    /** Callback when disconnect is clicked */
+    onDisconnect?: () => void;
+    /** Callback when logout is clicked */
+    onLogout?: () => void;
+    /** Callback when collapse panel is clicked */
+    onCollapsePanel?: () => void;
+    /** Custom styles */
+    className?: string;
+    /** Height of the chat container */
+    height?: string | number;
+    /** Show header with connection status */
+    showHeader?: boolean;
+    /** Show model selector (fetched from /configure endpoint) */
+    showModelSelector?: boolean;
+    /** Show tools menu (fetched from /configure endpoint) */
+    showToolsMenu?: boolean;
+    /** Clear messages when component mounts or agentId changes */
+    clearOnMount?: boolean;
+    /** Suggestions to show in empty state */
+    suggestions?: Suggestion[];
+    /** Whether to automatically submit the message when a suggestion is clicked */
+    submitOnSuggestionClick?: boolean;
+    /** Description shown in empty state */
+    description?: string;
+    /** Auto-focus the input on mount */
+    autoFocus?: boolean;
+}
+/**
+ * Chat Component
+ *
+ * A unified chat interface that supports multiple transports.
+ * Uses ChatBase internally for consistent UI and behavior.
+ *
+ * Note: Different transports connect to different servers:
+ * - vercel-ai, vercel-ai-jupyter: Connect to Jupyter server (default: localhost:8888)
+ * - ag-ui, acp, a2a: Connect to agent-runtimes server (default: localhost:8765)
+ *
+ * @example
+ * ```tsx
+ * // AG-UI Transport (connects to agent-runtimes server)
+ * <Chat
+ *   transport="ag-ui"
+ *   baseUrl="http://localhost:8765"
+ *   agentId="demo-agent"
+ * />
+ *
+ * // ACP Transport (WebSocket to agent-runtimes server)
+ * <Chat
+ *   transport="acp"
+ *   wsUrl="ws://localhost:8765/api/v1/acp/ws"
+ *   agentId="demo-agent"
+ * />
+ *
+ * // Vercel AI Transport (connects to Jupyter server)
+ * <Chat
+ *   transport="vercel-ai"
+ *   baseUrl="http://localhost:8888"
+ *   agentId="demo-agent"
+ * />
+ *
+ * // Vercel AI (Jupyter) Transport with model/tools selection
+ * <Chat
+ *   transport="vercel-ai-jupyter"
+ *   showModelSelector={true}
+ *   showToolsMenu={true}
+ * />
+ * ```
+ */
+export declare function Chat({ transport, extensions: _extensions, baseUrl, wsUrl, agentId, placeholder, title, autoConnect: _autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showModelSelector, showToolsMenu, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, autoFocus, }: ChatProps): import("react/jsx-runtime").JSX.Element;
+export default Chat;