beddel 0.2.2 → 0.3.0

package/src/agents/llm/llm.yaml

@@ -0,0 +1,87 @@
+# LLM Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/llm
+# Method: llm.execute
+
+agent:
+  id: llm
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "LLM Chat Agent"
+  description: "Direct LLM interaction with conversation history support (non-RAG)"
+  category: "intelligence"
+  route: "/agents/llm"
+  tags:
+    - "llm"
+    - "chat"
+    - "gemini"
+    - "conversation"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      query:
+        type: "string"
+        description: "User message to respond to"
+      history:
+        type: "array"
+        items:
+          type: "object"
+          properties:
+            role:
+              type: "string"
+              enum: ["user", "assistant", "system"]
+            content:
+              type: "string"
+        description: "Conversation history for context continuity"
+      temperature:
+        type: "number"
+        minimum: 0
+        maximum: 2
+        default: 0.7
+        description: "LLM temperature for response generation"
+      systemPrompt:
+        type: "string"
+        description: "Custom system prompt for the LLM"
+    required: ["query"]
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+        description: "Generated response"
+      timestamp:
+        type: "string"
+        description: "ISO timestamp of generation"
+      error:
+        type: "string"
+    required: ["response"]
+
+logic:
+  workflow:
+    - name: "generate-response"
+      type: "llm"
+      action:
+        query: "$input.query"
+        history: "$input.history"
+        temperature: "$input.temperature"
+        systemPrompt: "$input.systemPrompt"
+        result: "llmResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          response: "$llmResult.response"
+          timestamp: "$llmResult.timestamp"
+          error: "$llmResult.error"
+
+output:
+  schema:
+    response: "$llmResult.response"
+    timestamp: "$llmResult.timestamp"
+    error: "$llmResult.error"

package/src/agents/mcp-tool/index.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP Tool Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { McpToolInputSchema, McpToolOutputSchema } from './mcp-tool.schema';
+export type { McpToolInput, McpToolOutput } from './mcp-tool.schema';
+
+// Type exports (client-safe)
+export type { McpToolHandlerParams, McpToolHandlerResult, McpToolMetadata } from './mcp-tool.types';
+
+// Metadata (client-safe)
+export const mcpToolMetadata = {
+  id: 'mcp-tool',
+  name: 'MCP Tool Agent',
+  description: 'Generic agent for calling MCP server tools via SSE transport',
+  category: 'integration',
+  route: '/agents/mcp-tool',
+} as const;

package/src/agents/mcp-tool/mcp-tool.handler.ts

@@ -0,0 +1,112 @@
+import 'server-only';
+
+/**
+ * MCP Tool Agent Handler - Server-only execution logic
+ * Generic agent for calling MCP server tools via SSE transport
+ */
+
+import type { ExecutionContext } from '../../types/executionContext';
+import type { McpToolHandlerParams, McpToolHandlerResult } from './mcp-tool.types';
+
+// MCP imports (lazy loaded to avoid issues if not installed)
+let mcpClient: any = null;
+let mcpSSETransport: any = null;
+
+/**
+ * Execute MCP tool invocation
+ */
+export async function executeMcpToolHandler(
+  params: McpToolHandlerParams,
+  _props: Record<string, string>,
+  context: ExecutionContext
+): Promise<McpToolHandlerResult> {
+  const serverUrl = params.server_url;
+  const toolName = params.tool_name;
+  const toolArguments = params.tool_arguments || {};
+
+  if (!serverUrl) {
+    throw new Error('Missing required MCP input: server_url');
+  }
+  if (!toolName) {
+    throw new Error('Missing required MCP input: tool_name');
+  }
+
+  context.log(`[MCP Tool] Connecting to ${serverUrl}...`);
+  context.log(`[MCP Tool] Tool: ${toolName}`);
+
+  try {
+    // Lazy load MCP SDK
+    if (!mcpClient) {
+      const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+      const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
+      mcpClient = Client;
+      mcpSSETransport = SSEClientTransport;
+
+      // Setup EventSource for Node.js
+      const eventsourceModule = await import('eventsource');
+      const EventSourceClass = eventsourceModule.default || eventsourceModule;
+      if (!(global as any).EventSource) {
+        (global as any).EventSource = EventSourceClass;
+      }
+    }
+
+    const transport = new mcpSSETransport(new URL(serverUrl));
+    const client = new mcpClient(
+      { name: 'beddel-mcp-client', version: '1.0.0' },
+      { capabilities: {} }
+    );
+
+    await client.connect(transport);
+    context.log('[MCP Tool] Connected!');
+
+    // List available tools
+    const tools = await client.listTools();
+    const availableToolNames = tools.tools.map((t: any) => t.name);
+    context.log(`[MCP Tool] Available tools: ${availableToolNames.join(', ')}`);
+
+    // Handle list_tools special case
+    if (toolName === 'list_tools') {
+      await client.close();
+      return {
+        success: true,
+        data: JSON.stringify(tools.tools),
+        tool_names: availableToolNames,
+      };
+    }
+
+    // Validate tool exists
+    if (!availableToolNames.includes(toolName)) {
+      await client.close();
+      return {
+        success: false,
+        error: `Tool '${toolName}' not found. Available tools: ${availableToolNames.join(', ')}`,
+      };
+    }
+
+    // Call the tool with timeout
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('MCP Tool Timeout (30s)')), 30000)
+    );
+
+    const callPromise = client.callTool({
+      name: toolName,
+      arguments: toolArguments,
+    });
+
+    const callResult: any = await Promise.race([callPromise, timeoutPromise]);
+    await client.close();
+
+    // Parse result content
+    const textContent = callResult.content
+      .filter((c: any) => c.type === 'text')
+      .map((c: any) => c.text)
+      .join('\n') || 'No text content returned';
+
+    return { success: true, data: textContent };
+
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[MCP Tool] Error: ${message}`);
+    return { success: false, error: message };
+  }
+}

package/src/agents/mcp-tool/mcp-tool.schema.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Tool Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const McpToolInputSchema = z.object({
+  server_url: z.string().url(),
+  tool_name: z.string().min(1),
+  tool_arguments: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const McpToolOutputSchema = z.object({
+  success: z.boolean(),
+  data: z.string().optional(),
+  tool_names: z.array(z.string()).optional(),
+  error: z.string().optional(),
+});
+
+export type McpToolInput = z.infer<typeof McpToolInputSchema>;
+export type McpToolOutput = z.infer<typeof McpToolOutputSchema>;

package/src/agents/mcp-tool/mcp-tool.types.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP Tool Agent Types - Shared between client and server
+ */
+
+/**
+ * Parameters for MCP tool invocation
+ */
+export interface McpToolHandlerParams {
+  server_url: string;
+  tool_name: string;
+  tool_arguments?: Record<string, unknown>;
+}
+
+/**
+ * Result from MCP tool invocation
+ */
+export interface McpToolHandlerResult {
+  success: boolean;
+  data?: string;
+  tool_names?: string[];
+  error?: string;
+}
+
+/**
+ * MCP Tool agent metadata
+ */
+export interface McpToolMetadata {
+  id: 'mcp-tool';
+  name: string;
+  description: string;
+  category: 'integration';
+  route: '/agents/mcp-tool';
+}

package/src/agents/mcp-tool/mcp-tool.yaml

@@ -0,0 +1,71 @@
+# MCP Tool Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/mcp-tool
+# Method: mcp-tool.execute
+
+agent:
+  id: mcp-tool
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "MCP Tool Agent"
+  description: "Generic agent for calling MCP server tools via SSE transport"
+  category: "integration"
+  route: "/agents/mcp-tool"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      server_url:
+        type: "string"
+        description: "MCP server SSE endpoint URL"
+      tool_name:
+        type: "string"
+        description: "Name of the MCP tool to invoke (use 'list_tools' to discover available tools)"
+      tool_arguments:
+        type: "object"
+        description: "Arguments to pass to the tool"
+    required: ["server_url", "tool_name"]
+
+  output:
+    type: "object"
+    properties:
+      success:
+        type: "boolean"
+      data:
+        type: "string"
+      tool_names:
+        type: "array"
+        items:
+          type: "string"
+      error:
+        type: "string"
+    required: ["success"]
+
+logic:
+  workflow:
+    - name: "call-mcp-tool"
+      type: "mcp-tool"
+      action:
+        server_url: "$input.server_url"
+        tool_name: "$input.tool_name"
+        tool_arguments: "$input.tool_arguments"
+        result: "mcpResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          success: "$mcpResult.success"
+          data: "$mcpResult.data"
+          tool_names: "$mcpResult.toolNames"
+          error: "$mcpResult.error"
+
+output:
+  schema:
+    success: "$mcpResult.success"
+    data: "$mcpResult.data"
+    tool_names: "$mcpResult.toolNames"
+    error: "$mcpResult.error"

package/src/agents/rag/index.ts

@@ -0,0 +1,20 @@
+/**
+ * RAG Agent - Public exports (client-safe)
+ */
+
+// Schema exports (client-safe)
+export { RagInputSchema, RagOutputSchema } from './rag.schema';
+export type { RagInput, RagOutput } from './rag.schema';
+
+// Type exports (client-safe)
+export type { RagHandlerParams, RagHandlerResult, ConversationMessage, RagMetadata } from './rag.types';
+
+// Metadata (client-safe)
+export const ragMetadata = {
+  id: 'rag',
+  name: 'RAG Intelligence Agent',
+  description: 'Generates natural language answers based on provided context using Gemini',
+  category: 'intelligence',
+  route: '/agents/rag',
+  tags: ['rag', 'gemini', 'qa', 'generation'],
+} as const;

package/src/agents/rag/rag.handler.ts

@@ -0,0 +1,95 @@
+import 'server-only';
+
+/**
+ * RAG Agent Handler - Server-only execution logic
+ * Generates natural language answers based on provided document context using LLM
+ *
+ * Note: RAG = Retrieval-Augmented Generation
+ * This agent ALWAYS requires document context. For direct LLM chat without
+ * documents, use the LLM agent instead.
+ */
+
+import { generateText } from 'ai';
+import { LLMProviderFactory, extractProviderConfig } from '../../runtime/llmProviderFactory';
+import type { ExecutionContext } from '../../types/executionContext';
+import type { RagHandlerParams, RagHandlerResult, ConversationMessage } from './rag.types';
+
+/**
+ * Build prompt for RAG mode (with documents)
+ */
+function buildRagPrompt(
+  query: string,
+  ragContext: string,
+  history?: ConversationMessage[]
+): string {
+  const conversationContext = history?.length
+    ? `CONVERSATION HISTORY:\n${history.map((m) => `${m.role.toUpperCase()}: ${m.content}`).join('\n')}\n\n`
+    : '';
+
+  return `You are a helpful and expert assistant for the Beddel Protocol.
+
+${conversationContext}CONTEXT INFORMATION:
+${ragContext}
+
+USER QUESTION:
+${query}
+
+INSTRUCTIONS:
+1. Answer the user's question based on the CONTEXT INFORMATION provided above.
+2. Consider the CONVERSATION HISTORY for context continuity if available.
+3. If the context does not contain the answer, politely state that you don't have enough information in the documentation to answer.
+4. Be concise but comprehensive.
+
+ANSWER:`;
+}
+
+/**
+ * Execute RAG answer generation
+ * Requires document context - for direct LLM chat, use the LLM agent
+ */
+export async function executeRagHandler(
+  params: RagHandlerParams,
+  props: Record<string, string>,
+  context: ExecutionContext
+): Promise<RagHandlerResult> {
+  const providerConfig = extractProviderConfig(props, 'google');
+  const model = LLMProviderFactory.createLanguageModel(providerConfig);
+
+  const { query, history } = params;
+  const ragContext = params.context || params.documents;
+
+  if (!query) {
+    throw new Error('Missing required RAG input: query');
+  }
+
+  if (!ragContext) {
+    throw new Error('Missing required RAG input: context or documents. For direct LLM chat without documents, use the LLM agent instead.');
+  }
+
+  const prompt = buildRagPrompt(query, ragContext, history);
+
+  try {
+    context.log(`[RAG] Generating answer for: "${query.substring(0, 50)}..."`);
+
+    const { text } = await generateText({
+      model,
+      prompt,
+      temperature: 0.3,
+    });
+
+    return {
+      response: text,
+      answer: text,
+      timestamp: new Date().toISOString(),
+    };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.log(`[RAG] Error: ${message}`);
+    return {
+      response: '',
+      answer: '',
+      timestamp: new Date().toISOString(),
+      error: message,
+    };
+  }
+}

package/src/agents/rag/rag.schema.ts

@@ -0,0 +1,26 @@
+/**
+ * RAG Agent Schema - Zod validation schemas
+ * Safe for both client and server
+ */
+
+import { z } from 'zod';
+
+export const RagInputSchema = z.object({
+  query: z.string().min(1),
+  context: z.string().optional(),
+  documents: z.string().optional(),
+  history: z.array(z.object({
+    role: z.enum(['user', 'assistant', 'system']),
+    content: z.string(),
+  })).optional(),
+});
+
+export const RagOutputSchema = z.object({
+  response: z.string(),
+  answer: z.string().optional(),
+  timestamp: z.string().optional(),
+  error: z.string().optional(),
+});
+
+export type RagInput = z.infer<typeof RagInputSchema>;
+export type RagOutput = z.infer<typeof RagOutputSchema>;

package/src/agents/rag/rag.types.ts

@@ -0,0 +1,45 @@
+/**
+ * RAG Agent Types - Shared between client and server
+ * RAG = Retrieval-Augmented Generation (always requires document context)
+ */
+
+/**
+ * Conversation message
+ */
+export interface ConversationMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+/**
+ * Parameters for RAG answer generation
+ * Note: context or documents is REQUIRED - RAG always needs document context
+ */
+export interface RagHandlerParams {
+  query: string;
+  context?: string;
+  documents?: string;
+  history?: ConversationMessage[];
+}
+
+/**
+ * Result from RAG answer generation
+ */
+export interface RagHandlerResult {
+  response: string;
+  answer: string;
+  timestamp: string;
+  error?: string;
+}
+
+/**
+ * RAG agent metadata
+ */
+export interface RagMetadata {
+  id: 'rag';
+  name: string;
+  description: string;
+  category: 'intelligence';
+  route: '/agents/rag';
+  tags: string[];
+}

package/src/agents/rag/rag.yaml

@@ -0,0 +1,89 @@
+# RAG Agent - Native Builtin Agent for Beddel Runtime
+# Route: /agents/rag
+# Method: rag.execute
+
+agent:
+  id: rag
+  version: 1.0.0
+  protocol: beddel-declarative-protocol/v2.0
+
+metadata:
+  name: "RAG Intelligence Agent"
+  description: "Generates natural language answers based on provided context using Gemini"
+  category: "intelligence"
+  route: "/agents/rag"
+  tags:
+    - "rag"
+    - "gemini"
+    - "qa"
+    - "generation"
+
+schema:
+  input:
+    type: "object"
+    properties:
+      query:
+        type: "string"
+        description: "User question to answer"
+      context:
+        type: "string"
+        description: "Retrieved documentation or context for answering"
+      documents:
+        type: "string"
+        description: "Alternative to context - retrieved documents"
+      history:
+        type: "array"
+        items:
+          type: "object"
+          properties:
+            role:
+              type: "string"
+              enum: ["user", "assistant", "system"]
+            content:
+              type: "string"
+        description: "Conversation history for context continuity"
+    required: ["query"]
+
+  output:
+    type: "object"
+    properties:
+      response:
+        type: "string"
+        description: "Generated answer"
+      answer:
+        type: "string"
+        description: "Alias for response"
+      timestamp:
+        type: "string"
+        description: "ISO timestamp of generation"
+      error:
+        type: "string"
+    required: ["response"]
+
+logic:
+  workflow:
+    - name: "generate-answer"
+      type: "rag"
+      action:
+        query: "$input.query"
+        context: "$input.context"
+        documents: "$input.documents"
+        history: "$input.history"
+        result: "ragResult"
+
+    - name: "deliver-response"
+      type: "output-generator"
+      action:
+        type: "generate"
+        output:
+          response: "$ragResult.response"
+          answer: "$ragResult.answer"
+          timestamp: "$ragResult.timestamp"
+          error: "$ragResult.error"
+
+output:
+  schema:
+    response: "$ragResult.response"
+    answer: "$ragResult.answer"
+    timestamp: "$ragResult.timestamp"
+    error: "$ragResult.error"