@datalayer/agent-runtimes 1.0.2 → 1.0.4

package/README.md

@@ -14,7 +14,7 @@
 [![Netlify Status](https://api.netlify.com/api/v1/badges/f7f9e08a-884f-4f76-b20d-666d5873716c/deploy-status)](https://app.netlify.com/projects/agent-runtimes/deploys)
 [![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.
+**Agent Runtimes** is a unified library 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.
 
 ## What is Agent Runtimes?
 
@@ -30,7 +30,9 @@ Agent Runtimes solves the complexity of deploying AI agents by providing:
 
 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)
+![Agent Runtimes Chat Web](https://images.datalayer.io/product/agent-runtimes/agent-runtimes-example-1.gif)
+
+![Agent Runtimes Chat CLI](https://images.datalayer.io/products/codeai/codeai_short_cut.gif)
 
 ## 🌟 Features
 
@@ -53,133 +55,13 @@ Agent Runtimes solves the complexity of deploying AI agents by providing:
 - 💾 **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',
-});
-```
+## Documentation
+
+The detailed guides for architecture, use cases, interactive chat, key concepts, and runtime configuration are now in Docusaurus docs:
+
+- [Agent Runtimes Overview](https://agent-runtimes.datalayer.tech/)
+- [Integrations](https://agent-runtimes.datalayer.tech/integrations)
+- [Chat](https://agent-runtimes.datalayer.tech/chat)
+- [Transports](https://agent-runtimes.datalayer.tech/transports)
+- [Programmatic Tools](https://agent-runtimes.datalayer.tech/programmatic-tools)
+- [CLI](https://agent-runtimes.datalayer.tech/cli)

package/lib/Agent.js

@@ -26,7 +26,7 @@ import { useEffect, useState } from 'react';
 import { Text, Spinner } from '@primer/react';
 import { AlertIcon } from '@primer/octicons-react';
 import { Box, DatalayerThemeProvider, setupPrimerPortals, } from '@datalayer/primer-addons';
-import { Chat } from './components/chat';
+import { Chat } from './chat';
 import { DEFAULT_MODEL } from './specs';
 import '../style/primer-primitives.css';
 setupPrimerPortals();
@@ -116,7 +116,7 @@ export const Agent = () => {
                 }, children: [_jsx(AlertIcon, { size: 48 }), _jsx(Text, { sx: { color: 'danger.fg', fontSize: 2 }, children: "Failed to connect to agent" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: error })] }) }));
     }
     // Agent is ready — render the Chat component
-    return (_jsx(DatalayerThemeProvider, { children: _jsx(Chat, { transport: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent", placeholder: "Send a message...", description: "Chat with the agent", showHeader: true, height: '100vh', showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+    return (_jsx(DatalayerThemeProvider, { children: _jsx(Chat, { protocol: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent", placeholder: "Send a message...", description: "Chat with the agent", showHeader: true, height: '100vh', showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
                 {
                     title: 'Hello',
                     message: 'Hello, what can you do?',

package/lib/AgentLexical.d.ts

@@ -13,18 +13,7 @@
  *   - jupyterBaseUrl: base URL for the Jupyter server (optional, falls back to jupyter-config-data)
  *   - jupyterToken: token for the Jupyter server (optional, falls back to jupyter-config-data)
  */
-import 'prismjs';
-import 'prismjs/components/prism-clike';
-import 'prismjs/components/prism-javascript';
-import 'prismjs/components/prism-markup';
-import 'prismjs/components/prism-markdown';
-import 'prismjs/components/prism-c';
-import 'prismjs/components/prism-css';
-import 'prismjs/components/prism-objectivec';
-import 'prismjs/components/prism-sql';
-import 'prismjs/components/prism-python';
-import 'prismjs/components/prism-rust';
-import 'prismjs/components/prism-swift';
+import '@datalayer/jupyter-react/lib/css/PrismCss';
 import React from 'react';
 import '@datalayer/jupyter-lexical/style/index.css';
 import './examples/lexical/lexical-theme.css';

package/lib/AgentLexical.js

@@ -18,18 +18,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  *   - jupyterBaseUrl: base URL for the Jupyter server (optional, falls back to jupyter-config-data)
  *   - jupyterToken: token for the Jupyter server (optional, falls back to jupyter-config-data)
  */
-import 'prismjs';
-import 'prismjs/components/prism-clike';
-import 'prismjs/components/prism-javascript';
-import 'prismjs/components/prism-markup';
-import 'prismjs/components/prism-markdown';
-import 'prismjs/components/prism-c';
-import 'prismjs/components/prism-css';
-import 'prismjs/components/prism-objectivec';
-import 'prismjs/components/prism-sql';
-import 'prismjs/components/prism-python';
-import 'prismjs/components/prism-rust';
-import 'prismjs/components/prism-swift';
+import '@datalayer/jupyter-react/lib/css/PrismCss';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { $getRoot, $createParagraphNode } from 'lexical';
 import { LexicalComposer } from '@lexical/react/LexicalComposer';
@@ -52,7 +41,7 @@ import { Box, DatalayerThemeProvider, setupPrimerPortals, } from '@datalayer/pri
 import { JupyterReactTheme, loadJupyterConfig, createServerSettings, getJupyterServerUrl, getJupyterServerToken, setJupyterServerUrl, setJupyterServerToken, useJupyter, } from '@datalayer/jupyter-react';
 import { ComponentPickerMenuPlugin, JupyterCellPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, ImagesPlugin, HorizontalRulePlugin, EquationsPlugin, YouTubePlugin, ExcalidrawPlugin, CollapsiblePlugin, AutoLinkPlugin, AutoEmbedPlugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ListMaxIndentLevelPlugin, TableCellResizerPlugin, TablePlugin, } from '@datalayer/jupyter-lexical';
 import { ServiceManager } from '@jupyterlab/services';
-import { Chat } from './components/chat';
+import { Chat } from './chat';
 import { ChatInlinePlugin } from './lexical/ChatInlinePlugin';
 import { useChatInlineToolbarItems } from './lexical/useChatInlineToolbarItems';
 import { useLexicalTools } from './tools/adapters/agent-runtimes/lexicalHooks';
@@ -187,7 +176,7 @@ const ChatPanel = ({ agentId, tools }) => {
             display: 'flex',
             flexDirection: 'column',
             overflow: 'hidden',
-        }, children: _jsx(Chat, { transport: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Lexical", placeholder: "Ask about the document...", description: "Chat with the agent to manipulate the document", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: tools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+        }, children: _jsx(Chat, { protocol: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Lexical", placeholder: "Ask about the document...", description: "Chat with the agent to manipulate the document", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: tools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
                 {
                     title: 'Insert heading',
                     message: 'Insert a heading that says "Welcome"',

package/lib/AgentNotebook.js

@@ -24,10 +24,10 @@ import { AlertIcon } from '@primer/octicons-react';
 import { Box, DatalayerThemeProvider, setupPrimerPortals, } from '@datalayer/primer-addons';
 import { Notebook, JupyterReactTheme, loadJupyterConfig, createServerSettings, getJupyterServerUrl, getJupyterServerToken, setJupyterServerUrl, setJupyterServerToken, } from '@datalayer/jupyter-react';
 import { ServiceManager } from '@jupyterlab/services';
-import { Chat } from './components/chat';
+import { Chat } from './chat';
 import { useNotebookTools } from './tools/adapters/agent-runtimes/notebookHooks';
 import { DEFAULT_MODEL } from './specs';
-import MatplotlibNotebook from './examples/stores/notebooks/Matplotlib.ipynb.json';
+import MatplotlibNotebook from './examples/utils/notebooks/Matplotlib.ipynb.json';
 import '../style/primer-primitives.css';
 setupPrimerPortals();
 const BASE_URL = window.location.origin;
@@ -88,7 +88,7 @@ const ChatPanel = ({ agentId }) => {
             display: 'flex',
             flexDirection: 'column',
             overflow: 'hidden',
-        }, children: _jsx(Chat, { transport: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Notebook", placeholder: "Ask about the notebook...", description: "Chat with the agent to manipulate the notebook", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: notebookTools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+        }, children: _jsx(Chat, { protocol: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Notebook", placeholder: "Ask about the notebook...", description: "Chat with the agent to manipulate the notebook", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: notebookTools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
                 {
                     title: 'Add a cell',
                     message: 'Insert a new code cell into the notebook',

package/lib/App.js

@@ -4,8 +4,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * 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 { JupyterCellExample } from './examples/CellSimpleExample';
+import { JupyterNotebookExample } from './examples/NotebookSimpleExample';
 import './App.css';
 export function App() {
     const { serviceManager } = useJupyter({

package/lib/{components/chat/components → agents}/AgentDetails.d.ts

@@ -1,7 +1,16 @@
-import type { OAuthProvider, OAuthProviderConfig, Identity } from '../../../identity';
+/**
+ * AgentDetails component - Shows detailed information about the agent
+ * including name, protocol, URL, message count, and context details.
+ */
+import type { ReactNode } from 'react';
+import type { OAuthProvider, OAuthProviderConfig, Identity } from '../identity';
 export interface AgentDetailsProps {
     /** Agent name/title */
     name?: string;
+    /** Custom icon node (e.g. an Octicon component) shown instead of the default icon */
+    icon?: ReactNode;
+    /** Emoji from the agent spec (displayed instead of the default icon) */
+    emoji?: string;
     /** Protocol being used */
     protocol: string;
     /** Endpoint URL */
@@ -28,9 +37,11 @@ export interface AgentDetailsProps {
     onBack: () => void;
     /** Whether to show the header with back button (default: true) */
     showBackHeader?: boolean;
+    /** Whether to show context usage/history and context snapshot sections (default: true) */
+    showUsage?: boolean;
 }
 /**
  * AgentDetails component displays comprehensive information about the agent.
  */
-export declare function AgentDetails({ name, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader, }: AgentDetailsProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentDetails({ name, icon, emoji, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader, showUsage, }: AgentDetailsProps): import("react/jsx-runtime").JSX.Element;
 export default AgentDetails;

package/lib/{components/chat/components → agents}/AgentDetails.js

@@ -1,18 +1,12 @@
 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.
-/**
- * AgentDetails component - Shows detailed information about the agent
- * including name, protocol, URL, message count, and context details.
- */
 import { ArrowLeftIcon, CheckCircleIcon, XCircleIcon, CodeIcon, BriefcaseIcon, DownloadIcon, NoteIcon, ServerIcon, } from '@primer/octicons-react';
 import { Button, Heading, IconButton, Text, Label, Spinner, ToggleSwitch, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiAgentIcon } from '@datalayer/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { ContextPanel } from './ContextPanel';
-import { ContextInspector } from './ContextInspector';
-import { AgentIdentity } from './AgentIdentity';
+import { ContextPanel } from '../context/ContextPanel';
+import { ContextInspector, } from '../context/ContextInspector';
+import { AgentIdentity } from '../identity/AgentIdentity';
 /**
  * Get the API base URL for fetching data.
  * If apiBase prop is provided, use it.
@@ -171,7 +165,7 @@ async function downloadContextSnapshotAsCSV(agentId, apiBase) {
 /**
  * AgentDetails component displays comprehensive information about the agent.
  */
-export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader = true, }) {
+export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader = true, showUsage = true, }) {
     const queryClient = useQueryClient();
     // Fetch MCP toolsets status
     const { data: mcpStatus, isLoading: mcpLoading } = useQuery({
@@ -259,7 +253,7 @@ export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, a
                                     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 }), agentId && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["ID: ", agentId] }))] })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                                }, children: icon ? (_jsx(Box, { sx: { display: 'inline-flex', color: 'accent.fg' }, children: icon })) : emoji ? (_jsx(Text, { sx: { fontSize: 5, lineHeight: 1 }, children: emoji })) : (_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 }), 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,
@@ -579,7 +573,7 @@ export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, a
                                                         gap: 1,
                                                         flexWrap: 'wrap',
                                                         mt: 1,
-                                                    }, children: codemodeStatus.available_skills.map(skill => (_jsx(Label, { variant: "secondary", size: "small", children: skill.name }, skill.name))) })] })), codemodeStatus.available_skills.length === 0 && (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No skills available. Add skills to the skills/ directory." }))] })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load Codemode status" })) })] }), agentId && (_jsx(ContextPanel, { agentId: agentId, apiBase: apiBase, messageCount: messageCount, chartHeight: "200px" })), agentId && (_jsxs(Box, { sx: { mt: 3 }, children: [_jsxs(Box, { sx: {
+                                                    }, children: codemodeStatus.available_skills.map(skill => (_jsx(Label, { variant: "secondary", size: "small", children: skill.name }, skill.name))) })] })), codemodeStatus.available_skills.length === 0 && (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No skills available. Add skills to the skills/ directory." }))] })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load Codemode status" })) })] }), showUsage && agentId && (_jsx(ContextPanel, { agentId: agentId, apiBase: apiBase, messageCount: messageCount, chartHeight: "200px" })), showUsage && agentId && (_jsxs(Box, { sx: { mt: 3 }, children: [_jsxs(Box, { sx: {
                                     display: 'flex',
                                     alignItems: 'center',
                                     justifyContent: 'space-between',

package/lib/api/agents.d.ts

@@ -0,0 +1,47 @@
+import type { RunningAgent, AgentUsageSummary, ConversationCheckpoint } from '../types';
+/**
+ * List all running agents across runtimes.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the AI Agents API
+ * @returns Promise resolving to list of running agents
+ */
+export declare const getRunningAgents: (token: string, baseUrl?: string) => Promise<RunningAgent[]>;
+/**
+ * Get detailed status for a specific agent.
+ * @param token - Authentication token
+ * @param podName - Pod name hosting the agent
+ * @param agentId - Agent ID within the pod (optional, defaults to primary)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to agent status
+ */
+export declare const getAgentStatus: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<RunningAgent>;
+/**
+ * Pause a running agent (light checkpoint by default, CRIU optional).
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export declare const pauseAgent: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+/**
+ * Resume a paused/checkpointed agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export declare const resumeAgent: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+/**
+ * Get conversation checkpoints for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export declare const getAgentCheckpoints: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<ConversationCheckpoint[]>;
+/**
+ * Get usage summary for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export declare const getAgentUsage: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<AgentUsageSummary>;

package/lib/api/agents.js

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Running agents API functions.
+ *
+ * Provides functions for listing, inspecting, pausing, and resuming
+ * durable agents across runtimes.
+ *
+ * @module api/agents
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * List all running agents across runtimes.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the AI Agents API
+ * @returns Promise resolving to list of running agents
+ */
+export const getRunningAgents = async (token, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get detailed status for a specific agent.
+ * @param token - Authentication token
+ * @param podName - Pod name hosting the agent
+ * @param agentId - Agent ID within the pod (optional, defaults to primary)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to agent status
+ */
+export const getAgentStatus = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Pause a running agent (light checkpoint by default, CRIU optional).
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export const pauseAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/pause`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Resume a paused/checkpointed agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export const resumeAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/resume`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Get conversation checkpoints for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export const getAgentCheckpoints = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/checkpoints${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get usage summary for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export const getAgentUsage = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/usage${query}`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/context.d.ts

@@ -0,0 +1,17 @@
+import type { ContextUsage, CostUsage } from '../types';
+/**
+ * Get current context window usage for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to context usage data
+ */
+export declare const getContextUsage: (token: string, agentId: string, baseUrl?: string) => Promise<ContextUsage>;
+/**
+ * Get cost/usage tracking data for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to cost usage data
+ */
+export declare const getCostUsage: (token: string, agentId: string, baseUrl?: string) => Promise<CostUsage>;

package/lib/api/context.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Context usage API functions.
+ *
+ * Provides functions for retrieving real-time context window
+ * usage and cost tracking data for agents.
+ *
+ * @module api/context
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Get current context window usage for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to context usage data
+ */
+export const getContextUsage = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/context-usage`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get cost/usage tracking data for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to cost usage data
+ */
+export const getCostUsage = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/cost-usage`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/evals.d.ts

@@ -0,0 +1,27 @@
+import type { EvalReport, RunEvalsRequest } from '../types';
+/**
+ * Trigger an evaluation run for the specified agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param request - Eval run request body
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the eval report
+ */
+export declare const runEvals: (token: string, agentId: string, request: RunEvalsRequest, baseUrl?: string) => Promise<EvalReport>;
+/**
+ * List past evaluation runs for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of eval reports
+ */
+export declare const listEvals: (token: string, agentId: string, baseUrl?: string) => Promise<EvalReport[]>;
+/**
+ * Get a specific evaluation report.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param evalId - Eval run ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the eval report
+ */
+export declare const getEval: (token: string, agentId: string, evalId: string, baseUrl?: string) => Promise<EvalReport>;