@datalayer/agent-runtimes 1.0.3 → 1.0.4

package/README.md

@@ -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/chat/Chat.d.ts

@@ -51,6 +51,8 @@ export interface ChatProps {
     showModelSelector?: boolean;
     /** Show tools menu (fetched from /configure endpoint) */
     showToolsMenu?: boolean;
+    /** Show input area */
+    showInput?: boolean;
     /** Show skills menu (fetched from /skills endpoint) */
     showSkillsMenu?: boolean;
     /** Indicate tools are accessed via Codemode meta-tools */
@@ -193,5 +195,5 @@ export interface ChatProps {
  * />
  * ```
  */
-export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, wsUrl, agentId, authToken: authTokenProp, placeholder, title, brandIcon, autoConnect: _autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showSkillsMenu, codemodeEnabled, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, renderToolResult, hideMessagesAfterToolUI, }: ChatProps): import("react/jsx-runtime").JSX.Element;
+export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, wsUrl, agentId, authToken: authTokenProp, placeholder, title, brandIcon, autoConnect: _autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showInput, showSkillsMenu, codemodeEnabled, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, renderToolResult, hideMessagesAfterToolUI, }: ChatProps): import("react/jsx-runtime").JSX.Element;
 export default Chat;

package/lib/chat/Chat.js

@@ -133,7 +133,7 @@ function getProtocolType(protocol) {
  * />
  * ```
  */
-export function Chat({ protocol: transport, extensions: _extensions, baseUrl = 'http://localhost:8765', wsUrl, agentId, authToken: authTokenProp, placeholder = 'Type your message...', title, brandIcon, autoConnect: _autoConnect = true, streaming: _streaming = true, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height = '600px', showHeader = true, showNewChatButton = true, showClearButton = true, showModelSelector = true, showToolsMenu = true, showSkillsMenu = false, codemodeEnabled = false, showTokenUsage = true, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount = true, suggestions, submitOnSuggestionClick = true, description, headerContent, headerActions, autoFocus = false, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation = true, chatViewMode, onChatViewModeChange, frontendTools, renderToolResult, hideMessagesAfterToolUI = false, }) {
+export function Chat({ protocol: transport, extensions: _extensions, baseUrl = 'http://localhost:8765', wsUrl, agentId, authToken: authTokenProp, placeholder = 'Type your message...', title, brandIcon, autoConnect: _autoConnect = true, streaming: _streaming = true, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height = '600px', showHeader = true, showNewChatButton = true, showClearButton = true, showModelSelector = true, showToolsMenu = true, showInput = true, showSkillsMenu = false, codemodeEnabled = false, showTokenUsage = true, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount = true, suggestions, submitOnSuggestionClick = true, description, headerContent, headerActions, autoFocus = false, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation = true, chatViewMode, onChatViewModeChange, frontendTools, renderToolResult, hideMessagesAfterToolUI = false, }) {
     const [error, setError] = useState(null);
     const [isInitializing, setIsInitializing] = useState(true);
     const [showDetails, setShowDetails] = useState(false);
@@ -310,7 +310,7 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                                             ? 'attention.fg'
                                             : 'danger.fg',
                                         flex: 1,
-                                    }, children: errorBanner.message })] })), _jsx(ChatBase, { title: title, brandIcon: brandIcon, showHeader: showHeader, protocol: protocolConfig, placeholder: placeholder, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, autoFocus: autoFocus, runtimeId: runtimeId, historyEndpoint: historyEndpoint, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: () => setShowDetails(true), headerContent: headerContent, headerActions: headerActions, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, codemodeEnabled: codemodeEnabled, initialModel: initialModel, availableModels: availableModels, mcpServers: mcpServers, initialSkills: initialSkills, connectedIdentities: identitiesForChat, onNewChat: handleNewChat, onMessagesChange: messages => setMessageCount(messages.length), headerButtons: {
+                                    }, children: errorBanner.message })] })), _jsx(ChatBase, { title: title, brandIcon: brandIcon, showHeader: showHeader, protocol: protocolConfig, placeholder: placeholder, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, autoFocus: autoFocus, runtimeId: runtimeId, historyEndpoint: historyEndpoint, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: () => setShowDetails(true), headerContent: headerContent, headerActions: headerActions, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showInput: showInput, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, codemodeEnabled: codemodeEnabled, initialModel: initialModel, availableModels: availableModels, mcpServers: mcpServers, initialSkills: initialSkills, connectedIdentities: identitiesForChat, onNewChat: handleNewChat, onMessagesChange: messages => setMessageCount(messages.length), headerButtons: {
                                 showNewChat: showNewChatButton,
                                 showClear: showClearButton,
                                 onNewChat: handleNewChat,

package/lib/chat/base/ChatBase.js

@@ -1169,7 +1169,58 @@ pendingPrompt, }) {
     // ---- HITL respond handler (passed to MessageList) ----
     const handleRespond = useCallback(async (toolCallId, result) => {
         const existingToolCall = toolCallsRef.current.get(toolCallId);
-        if (existingToolCall && existingToolCall.status === 'executing') {
+        if (existingToolCall &&
+            (existingToolCall.status === 'executing' ||
+                existingToolCall.status === 'inProgress')) {
+            const isApprovalDecision = !!result &&
+                typeof result === 'object' &&
+                result.type === 'tool-approval-decision' &&
+                typeof result.approved === 'boolean';
+            if (isApprovalDecision && adapterRef.current) {
+                const approved = Boolean(result.approved);
+                const updatedToolCall = {
+                    ...existingToolCall,
+                    result,
+                    status: approved ? 'complete' : 'error',
+                    error: approved ? undefined : 'Tool approval rejected by user',
+                };
+                toolCallsRef.current.set(toolCallId, updatedToolCall);
+                setDisplayItems(prev => prev.map(item => isToolCallMessage(item) && item.toolCallId === toolCallId
+                    ? updatedToolCall
+                    : item));
+                setIsLoading(true);
+                setIsStreaming(true);
+                try {
+                    const approvalId = typeof result === 'object' &&
+                        result !== null &&
+                        typeof result.approvalId === 'string'
+                        ? result.approvalId
+                        : undefined;
+                    await adapterRef.current.sendToolResult(toolCallId, {
+                        toolCallId,
+                        success: approved,
+                        result: approved
+                            ? {
+                                approved: true,
+                                message: 'Tool call approved by user.',
+                                ...(approvalId ? { approvalId } : {}),
+                            }
+                            : {
+                                approved: false,
+                                message: 'Tool call rejected by user.',
+                                ...(approvalId ? { approvalId } : {}),
+                            },
+                        ...(approved
+                            ? {}
+                            : { error: 'Tool approval rejected by user' }),
+                    });
+                }
+                catch (err) {
+                    console.error('[ChatBase] Approval continuation error:', err);
+                    setError(err);
+                }
+                return;
+            }
             const updatedToolCall = {
                 ...existingToolCall,
                 result,

package/lib/chat/messages/ChatMessageList.js

@@ -19,7 +19,7 @@ import { isToolCallMessage, getMessageText } from '../../utils';
 // ---------------------------------------------------------------------------
 // DefaultToolCallRenderer — handles tool approval for a single tool call
 // ---------------------------------------------------------------------------
-function DefaultToolCallRenderer({ item, approvalConfig, }) {
+function DefaultToolCallRenderer({ item, approvalConfig, onRespond, }) {
     const resultObject = item.result && typeof item.result === 'object'
         ? item.result
         : undefined;
@@ -110,6 +110,12 @@ function DefaultToolCallRenderer({ item, approvalConfig, }) {
             });
             if (res.ok) {
                 setDecision(action === 'approve' ? 'approved' : 'denied');
+                onRespond({
+                    type: 'tool-approval-decision',
+                    approved: action === 'approve',
+                    approvalId: matchedApprovalId,
+                    toolName: item.toolName,
+                });
             }
         }
         catch {
@@ -118,7 +124,14 @@ function DefaultToolCallRenderer({ item, approvalConfig, }) {
         finally {
             setLoading(false);
         }
-    }, [matchedApprovalId, approvalConfig?.apiBaseUrl, approvalConfig?.authToken]);
+    }, [
+        matchedApprovalId,
+        approvalConfig?.apiBaseUrl,
+        approvalConfig?.authToken,
+        onRespond,
+        item.toolCallId,
+        item.toolName,
+    ]);
     // Show approval UI when we have a confirmed pending approval (from result
     // or discovered via polling) or after a decision has been made.
     const hasApproval = isPendingFromResult || !!matchedApprovalId;
@@ -170,7 +183,7 @@ export function ChatMessageList({ displayItems, isLoading, isStreaming, showLoad
     return (_jsxs(_Fragment, { children: [displayItems.map((item, index) => {
                 // ---- Tool call item ----
                 if (isToolCallMessage(item)) {
-                    const respond = item.status === 'executing'
+                    const respond = item.status === 'executing' || item.status === 'inProgress'
                         ? createRespondCallback(item.toolCallId)
                         : undefined;
                     const toolUI = renderToolResult ? (renderToolResult({
@@ -182,7 +195,7 @@ export function ChatMessageList({ displayItems, isLoading, isStreaming, showLoad
                         status: item.status,
                         error: item.error,
                         respond,
-                    })) : (_jsx(DefaultToolCallRenderer, { item: item, approvalConfig: approvalConfig }));
+                    })) : (_jsx(DefaultToolCallRenderer, { item: item, approvalConfig: approvalConfig, onRespond: createRespondCallback(item.toolCallId) }));
                     if (toolUI === null || toolUI === undefined)
                         return null;
                     return (_jsx(Box, { sx: {

package/lib/client/AgentsMixin.d.ts

@@ -11,7 +11,8 @@
  * @module client/AgentsMixin
  */
 import type { Constructor } from '@datalayer/core/lib/client/utils/mixins';
-import type { AgentEvent, CreateAgentEventRequest, GetAgentEventResponse, ListAgentEventsParams, ListAgentEventsResponse, UpdateAgentEventRequest, RunningAgent, AgentUsageSummary, ConversationCheckpoint, AgentNotification, NotificationFilters, OutputArtifact, EvalReport, RunEvalsRequest, ContextUsage, CostUsage } from '../types';
+import type { AgentEvent, CreateAgentEventRequest, GetAgentEventResponse, ListAgentEventsParams, ListAgentEventsResponse, UpdateAgentEventRequest, RunningAgent, AgentUsageSummary, ConversationCheckpoint, AgentNotification, NotificationFilters, OutputArtifact, EvalReport, RunEvalsRequest, ContextUsage, CostUsage, AgentSpec } from '../types';
+import type { CreateAgentRuntimeRequest, CreateRuntimeApiResponse } from '../types/agents-lifecycle';
 import type { ToolApproval, ToolApprovalFilters } from '../types/tool-approvals';
 /** Agents mixin providing durable agent management. */
 export declare function AgentsMixin<TBase extends Constructor>(Base: TBase): {
@@ -165,5 +166,51 @@ export declare function AgentsMixin<TBase extends Constructor>(Base: TBase): {
          * @returns Cost usage including per-model breakdown
          */
         getCostUsage(agentId: string): Promise<CostUsage>;
+        /**
+         * Get an agent specification by ID.
+         * @param agentSpecId - Agent spec identifier.
+         * @returns The agent spec, or undefined if not found.
+         */
+        getAgentSpec(agentSpecId: string): AgentSpec | undefined;
+        /**
+         * List all available agent specifications.
+         * @param prefix - If provided, only return specs whose ID starts with this prefix.
+         * @returns Array of agent specifications.
+         */
+        listAgentSpecs(prefix?: string): AgentSpec[];
+        /**
+         * Get required environment variables for an agent spec.
+         * @param spec - The agent specification.
+         * @returns Deduplicated array of required environment variable names.
+         */
+        getAgentSpecRequiredEnvVars(spec: AgentSpec): string[];
+        /**
+         * Assign an agent runtime to a project.
+         * @param projectUid - Project UID.
+         * @param agentPodName - Agent runtime pod name.
+         * @param agentSpecId - Agent spec ID.
+         * @param agentGivenName - Human-readable runtime name.
+         * @returns Updated project.
+         */
+        assignAgentToProject(projectUid: string, agentPodName: string, agentSpecId?: string, agentGivenName?: string): Promise<any>;
+        /**
+         * Remove the agent assignment from a project.
+         * @param projectUid - Project UID.
+         * @returns Updated project.
+         */
+        unassignAgentFromProject(projectUid: string): Promise<any>;
+        /**
+         * Create an agent runtime.
+         * @param data - Runtime creation parameters.
+         * @returns The created runtime response.
+         */
+        createAgentRuntime(data: CreateAgentRuntimeRequest): Promise<CreateRuntimeApiResponse>;
+        /**
+         * Create an agent runtime and assign it to a project.
+         * @param projectUid - The project UID to assign the agent to.
+         * @param data - Runtime creation parameters.
+         * @returns The created runtime response.
+         */
+        createAgentRuntimeForProject(projectUid: string, data: CreateAgentRuntimeRequest): Promise<CreateRuntimeApiResponse>;
     };
 } & TBase;

package/lib/client/AgentsMixin.js

@@ -9,6 +9,8 @@ import * as events from '../api/events';
 import * as output from '../api/output';
 import * as evals from '../api/evals';
 import * as context from '../api/context';
+import * as agentSpecs from '../specs/agents';
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
 /** Agents mixin providing durable agent management. */
 export function AgentsMixin(Base) {
     return class extends Base {
@@ -275,5 +277,112 @@ export function AgentsMixin(Base) {
             const baseUrl = this.getIamRunUrl();
             return context.getCostUsage(token, agentId, baseUrl);
         }
+        // ========================================================================
+        // Agent Specs
+        // ========================================================================
+        /**
+         * Get an agent specification by ID.
+         * @param agentSpecId - Agent spec identifier.
+         * @returns The agent spec, or undefined if not found.
+         */
+        getAgentSpec(agentSpecId) {
+            return agentSpecs.getAgentSpecs(agentSpecId);
+        }
+        /**
+         * List all available agent specifications.
+         * @param prefix - If provided, only return specs whose ID starts with this prefix.
+         * @returns Array of agent specifications.
+         */
+        listAgentSpecs(prefix) {
+            return agentSpecs.listAgentSpecs(prefix);
+        }
+        /**
+         * Get required environment variables for an agent spec.
+         * @param spec - The agent specification.
+         * @returns Deduplicated array of required environment variable names.
+         */
+        getAgentSpecRequiredEnvVars(spec) {
+            return agentSpecs.getAgentSpecRequiredEnvVars(spec);
+        }
+        // ========================================================================
+        // Project Agent Assignment
+        // ========================================================================
+        /**
+         * Assign an agent runtime to a project.
+         * @param projectUid - Project UID.
+         * @param agentPodName - Agent runtime pod name.
+         * @param agentSpecId - Agent spec ID.
+         * @param agentGivenName - Human-readable runtime name.
+         * @returns Updated project.
+         */
+        async assignAgentToProject(projectUid, agentPodName, agentSpecId, agentGivenName) {
+            // Backend requires name and description on every update
+            const project = await this.getProject(projectUid);
+            return this.updateProject(projectUid, {
+                name: project.name,
+                description: project.description,
+                attached_agent_pod_name_s: agentPodName,
+                attached_agent_spec_id_s: agentSpecId || '',
+                attached_agent_given_name_s: agentGivenName || '',
+            });
+        }
+        /**
+         * Remove the agent assignment from a project.
+         * @param projectUid - Project UID.
+         * @returns Updated project.
+         */
+        async unassignAgentFromProject(projectUid) {
+            // Backend requires name and description on every update
+            const project = await this.getProject(projectUid);
+            return this.updateProject(projectUid, {
+                name: project.name,
+                description: project.description,
+                attached_agent_pod_name_s: '',
+                attached_agent_spec_id_s: '',
+                attached_agent_given_name_s: '',
+            });
+        }
+        // ========================================================================
+        // Agent Runtime Lifecycle
+        // ========================================================================
+        /**
+         * Create an agent runtime.
+         * @param data - Runtime creation parameters.
+         * @returns The created runtime response.
+         */
+        async createAgentRuntime(data) {
+            const token = this.getToken();
+            const runtimesRunUrl = this.getRuntimesRunUrl();
+            return requestDatalayerAPI({
+                url: `${runtimesRunUrl}/api/runtimes/v1/runtimes`,
+                method: 'POST',
+                token,
+                body: {
+                    environment_name: data.environmentName || 'ai-agents-env',
+                    given_name: data.givenName || 'Agent',
+                    credits_limit: data.creditsLimit || 10,
+                    type: data.type || 'notebook',
+                    editor_variant: data.editorVariant || 'none',
+                    enable_codemode: data.enableCodemode ?? false,
+                    agent_spec_id: data.agentSpecId || undefined,
+                    agent_spec: data.agentSpec || undefined,
+                },
+            });
+        }
+        /**
+         * Create an agent runtime and assign it to a project.
+         * @param projectUid - The project UID to assign the agent to.
+         * @param data - Runtime creation parameters.
+         * @returns The created runtime response.
+         */
+        async createAgentRuntimeForProject(projectUid, data) {
+            const response = await this.createAgentRuntime(data);
+            if (response.success && response.runtime) {
+                const podName = response.runtime.pod_name;
+                const givenName = response.runtime.given_name || data.givenName || data.agentSpecId;
+                await this.assignAgentToProject(projectUid, podName, data.agentSpecId, givenName);
+            }
+            return response;
+        }
     };
 }