@datalayer/agent-runtimes 0.0.5 → 0.0.8

package/README.md

@@ -2,37 +2,34 @@
   ~ Copyright (c) 2025-2026 Datalayer, Inc.
   ~
   ~ BSD 3-Clause License
+-->
 
+[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)
 
-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
+[![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
 
-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
+[![Github Actions Status](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yml/badge.svg)](https://github.com/datalayer/agent-runtimes/actions/workflows/build.yml)
+[![PyPI - Version](https://img.shields.io/pypi/v/agent-runtimes)](https://pypi.org/project/agent-runtimes)
 
--->
+**Agent Runtimes** is a unified platform for deploying, managing, and interacting with AI agents across multiple protocols and frameworks. It provides both a Python server for hosting agents and React components for seamless integration into web and desktop applications.
 
-[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)
+## 🎯 What is Agent Runtimes?
 
-[![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 solves the complexity of deploying AI agents by providing:
 
-# 🤖 Agent Runtimes
+1. **Protocol Abstraction**: One agent, multiple protocols - deploy your agent once and access it through ACP, Vercel AI SDK, AG-UI, MCP-UI, or A2A without changing your code.
+
+2. **Framework Flexibility**: Write agents using your preferred framework (Pydantic AI, LangChain, Jupyter AI) while maintaining a consistent API.
+
+3. **Cloud Runtime Management**: Built-in integration with Datalayer Cloud Runtimes for launching and managing compute resources with Zustand-based state management.
 
-[![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)
+4. **UI Components**: Pre-built React components (ChatBase, ChatSidebar, ChatFloating) that connect to agents and execute tools directly in the browser.
 
-**Agent Runtimes** is a flexible server framework for exposing AI agents through multiple protocols.
+5. **Tool Ecosystem**: Seamless integration with MCP (Model Context Protocol) tools, custom tools, and built-in utilities for Jupyter notebooks and Lexical documents.
+
+![Agent Runtimes](https://images.datalayer.io/product/agent-runtimes/agent-runtimes-example-1.gif)
 
 ## 🌟 Features
 
@@ -49,8 +46,139 @@ In the backend endpoint, you then have to parse this value out of the SubmitMess
 - **Jupyter AI**: Notebook integration (adapter ready)
 
 ### Built-in Features
-- 🔌 **Adapter Architecture**: Easy to add new agents and protocols
+- 🔌 **Flexible 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
+
+## 🏗️ Architecture
+
+Agent Runtimes consists of three main components:
+
+### 1. Python Server (`agent_runtimes/`)
+The backend server that hosts AI agents and handles protocol routing:
+- **Agent Adapters**: Unified interface for Pydantic AI, LangChain, and Jupyter AI
+- **Protocol Adapters**: Convert between different agent protocols (ACP, AG-UI, Vercel AI, etc.)
+- **FastAPI Server**: High-performance async server with automatic API documentation
+- **Tool Registry**: Manages and executes tools from various sources (MCP, custom, built-in)
+
+### 2. React Components (`src/components/`)
+Pre-built UI components for interacting with agents:
+- **ChatBase**: Core chat interface with customizable styling
+- **ChatSidebar**: Collapsible sidebar for agent interactions
+- **ChatFloating**: Floating chat widget for non-intrusive agent access
+- **All components support**: Frontend tool execution, markdown rendering, code highlighting, and real-time streaming
+
+### 3. Runtime Management (`src/runtime/`)
+Cloud runtime lifecycle management with Zustand store:
+- **Launch & Connect**: Create new cloud runtimes or connect to existing ones
+- **Agent Creation**: Automatically create and configure agents on runtimes
+- **State Management**: Track runtime status, agent connections, and errors
+- **Hooks**: React hooks for easy integration (`useAgentRuntime`, `useRuntimeStore`)
+
+## 🚀 Use Cases
+
+### Notebook AI Assistant
+Add an AI agent to Jupyter notebooks that can:
+- Execute cells, insert code, and modify notebook content
+- Explain code and data analysis
+- Debug errors and suggest improvements
+
+```tsx
+import { NotebookAgentsRuntime } from '@datalayer/agent-runtimes';
+
+<NotebookAgentsRuntime
+  notebookId={notebookId}
+  environmentName="python-simple"
+  runtimeName={runtimeName}
+  serviceManager={serviceManager}
+/>
+```
+
+### Document Editor AI
+Integrate AI into Lexical-based document editors:
+- Insert headings, lists, code blocks, and formatted text
+- Summarize content and proofread text
+- Generate ideas and help with writing
+
+```tsx
+import { DocumentAgentRuntime } from '@datalayer/agent-runtimes';
+
+<DocumentAgentRuntime
+  documentId={documentId}
+  environmentName="python-simple"
+  runtimeName={runtimeName}
+  serviceManager={serviceManager}
+/>
+```
+
+### Custom Agent Deployment
+Deploy your own Pydantic AI agent with custom tools:
+
+```python
+from agent_runtimes import AgentRuntimesApp
+from pydantic_ai import Agent
+
+# Create your agent
+agent = Agent(
+    model='anthropic:claude-sonnet-4-5',
+    system_prompt='You are a helpful assistant.',
+)
+
+# Launch the server
+app = AgentRuntimesApp()
+app.add_agent(agent, name='my-agent', transport='ag-ui')
+app.run(port=8000)
+```
+
+## 🧪 Run the examples
+
+Run the Codemode + MCP example UI:
+
+```bash
+cd src/ai/agent-runtimes
+EXAMPLE=AgentCodemodeMcpExample npm run dev
+```
+
+## 🔧 Key Concepts
+
+### Protocols
+Agent Runtimes supports multiple protocols for agent communication:
+
+- **AG-UI**: Lightweight protocol for web UIs (POST-based, Pydantic AI native)
+- **ACP**: WebSocket-based Agent Client Protocol for real-time interaction
+- **Vercel AI SDK**: Compatible with Vercel's AI SDK streaming
+- **MCP-UI**: Model Context Protocol with UI resources
+- **A2A**: Agent-to-agent communication protocol
+
+### Tools
+Tools extend agent capabilities by allowing them to perform actions:
+
+- **Frontend Tools**: Execute in the browser (notebook editing, document manipulation)
+- **MCP Tools**: Tools from Model Context Protocol servers
+- **Custom Tools**: Your own Python functions decorated with tool metadata
+- **Built-in Tools**: File operations, web search, code execution
+- **Code Mode**: Tool discovery includes `output_schema` and `input_examples` for reliable calls; code execution returns `stdout`/`stderr` and a summarized `result`.
+
+### Runtime Management
+Cloud runtimes provide compute resources for agents:
+
+```typescript
+import { useAgentRuntime } from '@datalayer/agent-runtimes/lib/runtime';
+
+const { isReady, endpoint, tools, launchRuntime } = useAgentRuntime({
+  autoCreateAgent: true,
+  agentConfig: {
+    model: 'anthropic:claude-sonnet-4-5',
+    systemPrompt: 'You are a helpful AI assistant.',
+  },
+});
+
+// Launch a new runtime
+await launchRuntime({
+  environmentName: 'python-simple',
+  creditsLimit: 100,
+  type: 'notebook',
+});
+```

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

@@ -1,3 +1,4 @@
+import type { OAuthProvider, OAuthProviderConfig, Identity } from '../../../identity';
 export interface AgentDetailsProps {
     /** Agent name/title */
     name?: string;
@@ -7,13 +8,25 @@ export interface AgentDetailsProps {
     url: string;
     /** Number of messages in conversation */
     messageCount: number;
-    /** Agent ID */
+    /** Agent ID for context usage tracking */
     agentId?: string;
+    /** Identity provider configurations */
+    identityProviders?: {
+        [K in OAuthProvider]?: {
+            clientId: string;
+            scopes?: string[];
+            config?: Partial<OAuthProviderConfig>;
+        };
+    };
+    /** Callback when identity connects */
+    onIdentityConnect?: (identity: Identity) => void;
+    /** Callback when identity disconnects */
+    onIdentityDisconnect?: (provider: OAuthProvider) => void;
     /** 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 declare function AgentDetails({ name, protocol, url, messageCount, agentId, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, }: AgentDetailsProps): import("react/jsx-runtime").JSX.Element;
 export default AgentDetails;

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

@@ -5,53 +5,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * 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, CheckCircleIcon, XCircleIcon, } from '@primer/octicons-react';
-import { Box, Button, Heading, IconButton, Text, Label, ProgressBar, Spinner, } from '@primer/react';
+import { ArrowLeftIcon, GlobeIcon, CommentDiscussionIcon, CheckCircleIcon, XCircleIcon, } from '@primer/octicons-react';
+import { Box, Button, Heading, IconButton, Text, Label, Spinner, } from '@primer/react';
 import { AiAgentIcon } from '@datalayer/icons-react';
 import { useQuery } from '@tanstack/react-query';
-// 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 },
-            ],
-        },
-    ],
-};
+import { ContextUsage } from './ContextUsage';
+import { ContextDistribution } from './ContextDistribution';
+import { AgentIdentity } from './AgentIdentity';
 function getLocalApiBase() {
     if (typeof window === 'undefined') {
         return '';
@@ -61,40 +21,10 @@ function getLocalApiBase() {
         ? 'http://127.0.0.1:8765'
         : '';
 }
-/**
- * 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;
+export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, agentId, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, }) {
     // Fetch MCP toolsets status
     const { data: mcpStatus, isLoading: mcpLoading } = useQuery({
         queryKey: ['mcp-toolsets-status'],
@@ -203,31 +133,17 @@ export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, a
                                                                 pl: 4,
                                                                 whiteSpace: 'pre-wrap',
                                                                 wordBreak: 'break-word',
-                                                            }, children: error.split('\n')[0] })] }, server)))] }))] })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load MCP status" })) })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                                                            }, children: error.split('\n')[0] })] }, server)))] }))] })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load MCP status" })) })] }), agentId && _jsx(ContextUsage, { agentId: agentId }), agentId && (_jsxs(Box, { sx: { mt: 3 }, children: [_jsx(Heading, { as: "h4", sx: {
                                     fontSize: 1,
                                     fontWeight: 'semibold',
                                     mb: 2,
                                     color: 'fg.muted',
-                                }, children: "Context Usage" }), _jsxs(Box, { sx: {
+                                }, children: "Current Context Distribution" }), _jsx(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" }) })] })] }));
+                                }, children: _jsx(ContextDistribution, { agentId: agentId, height: "250px" }) })] })), _jsx(AgentIdentity, { providers: identityProviders, title: "Connected Accounts", showHeader: true, showDescription: true, description: "OAuth identities connected to this agent. Agents can use these to access external services like GitHub repositories on your behalf.", showExpirationDetails: true, allowReconnect: Boolean(identityProviders), onConnect: onIdentityConnect, onDisconnect: onIdentityDisconnect }), _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/AgentIdentity.d.ts

@@ -0,0 +1,92 @@
+import type { OAuthProvider, OAuthProviderConfig, Identity } from '../../../identity';
+/**
+ * Token status information
+ */
+export interface TokenStatus {
+    isExpired: boolean;
+    isExpiringSoon: boolean;
+    expiresAt?: Date;
+    timeUntilExpiry?: number;
+    timeSinceExpiry?: number;
+}
+/**
+ * Calculate token status from expiration timestamp
+ */
+export declare function getTokenStatus(expiresAt?: number): TokenStatus;
+/**
+ * Format duration for display
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format expiration status text
+ */
+export declare function formatExpirationStatus(status: TokenStatus): string;
+/**
+ * Props for IdentityCard component
+ */
+export interface IdentityCardProps {
+    /** Identity to display */
+    identity: Identity;
+    /** Provider configuration */
+    providerConfig?: {
+        clientId: string;
+        scopes?: string[];
+        config?: Partial<OAuthProviderConfig>;
+    };
+    /** Show detailed expiration info */
+    showExpirationDetails?: boolean;
+    /** Allow reconnection */
+    allowReconnect?: boolean;
+    /** Callback when connected */
+    onConnect?: (identity: Identity) => void;
+    /** Callback when disconnected */
+    onDisconnect?: (provider: OAuthProvider) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Single identity card with status and actions
+ */
+export declare function IdentityCard({ identity, providerConfig, showExpirationDetails, allowReconnect, onConnect: _onConnect, onDisconnect, onError, }: IdentityCardProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props for AgentIdentity component
+ */
+export interface AgentIdentityProps {
+    /** Provider configurations with client IDs */
+    providers?: {
+        [K in OAuthProvider]?: {
+            clientId: string;
+            scopes?: string[];
+            config?: Partial<OAuthProviderConfig>;
+        };
+    };
+    /** Title for the section */
+    title?: string;
+    /** Show header */
+    showHeader?: boolean;
+    /** Show description */
+    showDescription?: boolean;
+    /** Description text */
+    description?: string;
+    /** Show expiration details */
+    showExpirationDetails?: boolean;
+    /** Allow reconnection */
+    allowReconnect?: boolean;
+    /** Callback when identity connects */
+    onConnect?: (identity: Identity) => void;
+    /** Callback when identity disconnects */
+    onDisconnect?: (provider: OAuthProvider) => void;
+    /** Callback on error */
+    onError?: (provider: OAuthProvider, error: Error) => void;
+}
+/**
+ * AgentIdentity component - Displays all connected identities with status
+ *
+ * Features:
+ * - Shows connected OAuth identities (GitHub, Google, Kaggle, etc.)
+ * - Displays token expiration status with detailed timing
+ * - Allows reconnection if token expired
+ * - Reusable across AgentDetails, AgentConfiguration, etc.
+ */
+export declare function AgentIdentity({ providers, title, showHeader, showDescription, description, showExpirationDetails, allowReconnect, onConnect, onDisconnect, onError, }: AgentIdentityProps): import("react/jsx-runtime").JSX.Element | null;
+export default AgentIdentity;