@datalayer/agent-runtimes 0.0.2

package/lib/examples/vercel-ai-elements/showcase.css

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ *
+ * Showcase-specific styles for Vercel AI Elements
+ */
+
+/* Additional showcase-specific styles */
+:root {
+  --showcase-max-width: 1400px;
+}
+
+.showcase-container {
+  max-width: var(--showcase-max-width);
+  margin: 0 auto;
+}
+
+/* Ensure proper spacing in showcase examples */
+.space-y-8 > * + * {
+  margin-top: 2rem;
+}
+
+.space-y-4 > * + * {
+  margin-top: 1rem;
+}
+
+.space-y-3 > * + * {
+  margin-top: 0.75rem;
+}
+
+.space-y-2 > * + * {
+  margin-top: 0.5rem;
+}
+
+/* Prose styles for documentation content */
+.prose {
+  color: var(--color-fg-default);
+  max-width: 65ch;
+}
+
+.prose h1 {
+  font-size: 2em;
+  margin-top: 0;
+  margin-bottom: 0.8em;
+  line-height: 1.1;
+  font-weight: 700;
+}
+
+.prose h2 {
+  font-size: 1.5em;
+  margin-top: 2em;
+  margin-bottom: 1em;
+  line-height: 1.3;
+  font-weight: 600;
+}
+
+.prose h3 {
+  font-size: 1.25em;
+  margin-top: 1.6em;
+  margin-bottom: 0.6em;
+  line-height: 1.4;
+  font-weight: 600;
+}
+
+.prose p {
+  margin-top: 1.25em;
+  margin-bottom: 1.25em;
+  line-height: 1.7;
+}
+
+.prose pre {
+  background-color: var(--color-canvas-subtle);
+  border-radius: 0.375rem;
+  padding: 1em;
+  overflow-x: auto;
+  margin-top: 1.7em;
+  margin-bottom: 1.7em;
+}
+
+.prose code {
+  background-color: var(--color-canvas-subtle);
+  border-radius: 0.25rem;
+  padding: 0.2em 0.4em;
+  font-size: 0.875em;
+  font-family: 'Fira Code', 'Consolas', 'Monaco', monospace;
+}
+
+.prose pre code {
+  background-color: transparent;
+  padding: 0;
+  font-size: inherit;
+}
+
+.prose ul {
+  margin-top: 1.25em;
+  margin-bottom: 1.25em;
+  padding-left: 1.625em;
+  list-style-type: disc;
+}
+
+.prose li {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+}
+
+.prose strong {
+  font-weight: 600;
+}
+
+/* Ensure code blocks in examples are visible */
+.border {
+  border-width: 1px;
+}
+
+/* Dark mode adjustments */
+@media (prefers-color-scheme: dark) {
+  .prose {
+    color: var(--color-fg-default);
+  }
+
+  .prose code {
+    background-color: rgba(110, 118, 129, 0.4);
+  }
+
+  .prose pre {
+    background-color: rgba(110, 118, 129, 0.2);
+  }
+}

package/lib/hooks/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Hooks for agent-runtimes.
+ *
+ * This module exports hooks organized by their purpose:
+ *
+ * ## Chat Component System Hooks
+ * These hooks work with the Zustand-based chat component system.
+ * Use these when building with `<Chat />`, `<ChatSidebar />`, etc.
+ *
+ * - `useChat` - Main chat hook for messages, streaming, and state
+ * - `useFrontendTool`, `useBackendTool` - Tool registration hooks
+ * - `useKeyboardShortcuts` - Keyboard shortcut handling
+ *
+ * ## Transport-Specific Hooks
+ * These hooks provide direct protocol access without the chat component system.
+ * Use these for custom implementations or when you need fine-grained control.
+ *
+ * - `useAGUI` - AG-UI protocol (Pydantic AI's native protocol)
+ * - `useA2A` - A2A protocol (Agent-to-Agent with JSON-RPC)
+ * - `useAcp` - ACP protocol (Agent Client Protocol via WebSocket)
+ * - `useVercelChat` - Vercel AI SDK chat protocol
+ *
+ * ## Datalayer-Specific Hooks
+ * Hooks for Datalayer platform integration.
+ *
+ * - `useAIAgents` - Datalayer AI Agents REST API
+ * - `useNotebookAIAgent` - Notebook-specific agent management
+ *
+ * @module hooks
+ */
+/**
+ * Main chat hook for the chat component system (Zustand-based).
+ * Use with `<Chat />`, `<ChatSidebar />`, `<ChatFloating />`, etc.
+ */
+export { useChat, type UseChatReturn } from './useChat';
+/**
+ * Tool registration hooks for the chat component system.
+ */
+export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendingToolCalls, ActionRegistrar, type UseFrontendToolFn, } from './useTools';
+/**
+ * Keyboard shortcut hooks for chat UI.
+ */
+export { useKeyboardShortcuts, useChatKeyboardShortcuts, getShortcutDisplay, type KeyboardShortcut, type UseKeyboardShortcutsOptions, } from './useKeyboardShortcuts';
+/**
+ * AG-UI protocol hook - Pydantic AI's native protocol.
+ * Use for direct AG-UI communication without the chat component system.
+ */
+export { useAGUI } from './useAGUI';
+/**
+ * A2A protocol hook - Agent-to-Agent with JSON-RPC 2.0.
+ * Use for direct A2A communication without the chat component system.
+ */
+export { useA2A } from './useA2A';
+/**
+ * ACP protocol hook - Agent Client Protocol via WebSocket.
+ * Use for direct ACP communication without the chat component system.
+ */
+export * from './useAcp';
+/**
+ * Vercel AI SDK chat hook - HTTP/SSE streaming.
+ * Use for direct Vercel AI communication without the chat component system.
+ */
+export { useVercelChat } from './useVercelChat';
+/**
+ * Datalayer AI Agents REST API hook.
+ */
+export * from './useAgents';
+export * from './useNotebookAIAgent';

package/lib/hooks/index.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Hooks for agent-runtimes.
+ *
+ * This module exports hooks organized by their purpose:
+ *
+ * ## Chat Component System Hooks
+ * These hooks work with the Zustand-based chat component system.
+ * Use these when building with `<Chat />`, `<ChatSidebar />`, etc.
+ *
+ * - `useChat` - Main chat hook for messages, streaming, and state
+ * - `useFrontendTool`, `useBackendTool` - Tool registration hooks
+ * - `useKeyboardShortcuts` - Keyboard shortcut handling
+ *
+ * ## Transport-Specific Hooks
+ * These hooks provide direct protocol access without the chat component system.
+ * Use these for custom implementations or when you need fine-grained control.
+ *
+ * - `useAGUI` - AG-UI protocol (Pydantic AI's native protocol)
+ * - `useA2A` - A2A protocol (Agent-to-Agent with JSON-RPC)
+ * - `useAcp` - ACP protocol (Agent Client Protocol via WebSocket)
+ * - `useVercelChat` - Vercel AI SDK chat protocol
+ *
+ * ## Datalayer-Specific Hooks
+ * Hooks for Datalayer platform integration.
+ *
+ * - `useAIAgents` - Datalayer AI Agents REST API
+ * - `useNotebookAIAgent` - Notebook-specific agent management
+ *
+ * @module hooks
+ */
+// =============================================================================
+// Chat Component System Hooks
+// =============================================================================
+/**
+ * Main chat hook for the chat component system (Zustand-based).
+ * Use with `<Chat />`, `<ChatSidebar />`, `<ChatFloating />`, etc.
+ */
+export { useChat } from './useChat';
+/**
+ * Tool registration hooks for the chat component system.
+ */
+export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendingToolCalls, ActionRegistrar, } from './useTools';
+/**
+ * Keyboard shortcut hooks for chat UI.
+ */
+export { useKeyboardShortcuts, useChatKeyboardShortcuts, getShortcutDisplay, } from './useKeyboardShortcuts';
+// =============================================================================
+// Transport-Specific Hooks (Direct Protocol Access)
+// =============================================================================
+/**
+ * AG-UI protocol hook - Pydantic AI's native protocol.
+ * Use for direct AG-UI communication without the chat component system.
+ */
+export { useAGUI } from './useAGUI';
+/**
+ * A2A protocol hook - Agent-to-Agent with JSON-RPC 2.0.
+ * Use for direct A2A communication without the chat component system.
+ */
+export { useA2A } from './useA2A';
+/**
+ * ACP protocol hook - Agent Client Protocol via WebSocket.
+ * Use for direct ACP communication without the chat component system.
+ */
+export * from './useAcp';
+/**
+ * Vercel AI SDK chat hook - HTTP/SSE streaming.
+ * Use for direct Vercel AI communication without the chat component system.
+ */
+export { useVercelChat } from './useVercelChat';
+// =============================================================================
+// Datalayer Platform Hooks
+// =============================================================================
+/**
+ * Datalayer AI Agents REST API hook.
+ */
+export * from './useAgents';
+export * from './useNotebookAIAgent';

package/lib/hooks/useA2A.d.ts

@@ -0,0 +1,75 @@
+import type { AgentCard, Task, TaskState } from '@a2a-js/sdk';
+export type { AgentCard, Task, TaskState };
+export interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp?: string;
+    taskId?: string;
+    contextId?: string;
+}
+export interface UseA2AOptions {
+    /**
+     * Base URL for the A2A endpoint (e.g., 'http://localhost:8000')
+     */
+    baseUrl?: string;
+    /**
+     * Agent ID to use (default: 'demo-agent')
+     */
+    agentId?: string;
+    /**
+     * Whether to use streaming (default: true)
+     */
+    streaming?: boolean;
+    /**
+     * Auto-connect on mount (default: true)
+     */
+    autoConnect?: boolean;
+    /**
+     * Callback when a message is sent
+     */
+    onMessageSent?: (content: string) => void;
+    /**
+     * Callback when a message is received
+     */
+    onMessageReceived?: (message: Message) => void;
+    /**
+     * Callback when a task status changes
+     */
+    onTaskStatusChange?: (task: Task) => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+export interface UseA2AReturn {
+    isConnected: boolean;
+    agentCard: AgentCard | null;
+    messages: Message[];
+    sendMessage: (content: string) => Promise<void>;
+    clearMessages: () => void;
+    currentTask: Task | null;
+    isLoading: boolean;
+    isStreaming: boolean;
+    streamingContent: string;
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    error: Error | null;
+}
+/**
+ * Hook to manage chat state with A2A protocol.
+ *
+ * This hook provides an interface to the A2A protocol endpoint
+ * at /api/v1/a2a/agents/{agent_id} using JSON-RPC 2.0.
+ *
+ * Example:
+ * ```tsx
+ * const { messages, sendMessage, isConnected } = useA2A({
+ *   baseUrl: 'http://localhost:8765',
+ *   agentId: 'demo-agent',
+ * });
+ *
+ * await sendMessage('Hello!');
+ * ```
+ */
+export declare function useA2A(options?: UseA2AOptions): UseA2AReturn;
+export default useA2A;