beddel 0.2.2 → 0.3.0

package/src/runtime/declarativeAgentRuntime.ts

@@ -1,19 +1,34 @@
 /**
  * Declarative Agent Runtime - YAML Interpreter for Beddel Declarative Protocol
  * Safely interprets declarative YAML agent definitions without dynamic code execution
+ *
+ * Phase 3 Refactored: Delegates to individual agent handlers via workflowExecutor
  */
 
-import * as yaml from "js-yaml";
-import { experimental_generateImage, generateText } from "ai";
-import { createGoogleGenerativeAI } from "@ai-sdk/google";
-import { type ZodTypeAny } from "zod";
-import { ExecutionContext } from "../types/executionContext";
-import { agentRegistry } from "../agents/agentRegistry";
+import 'server-only';
+
+import * as yaml from 'js-yaml';
+import { type ZodTypeAny } from 'zod';
+import { ExecutionContext } from '../types/executionContext';
+import { agentRegistry } from '../agents/registry';
 import {
   DeclarativeSchemaCompiler,
   DeclarativeSchemaValidationError,
   type DeclarativeSchemaPhase,
-} from "./schemaCompiler";
+} from './schemaCompiler';
+
+// Import handlers from workflowExecutor
+import {
+  executeJokeHandler,
+  executeTranslationHandler,
+  executeImageHandler,
+  executeMcpToolHandler,
+  executeVectorizeHandler,
+  executeChromaDBHandler,
+  executeGitMcpHandler,
+  executeRagHandler,
+  executeChatHandler,
+} from './workflowExecutor';
 
 export interface YamlAgentDefinition {
   agent: {
@@ -63,14 +78,12 @@ export type YamlExecutionResult = Record<string, any>;
 
 /**
  * Safe declarative YAML interpreter - no dynamic code execution
+ * Delegates execution to individual agent handlers
  */
 export class DeclarativeAgentInterpreter {
-  private readonly MAX_VARIABLE_SIZE = 1024; // 1KB max variable size
-  private readonly MAX_WORKFLOW_STEPS = 100; // Prevent infinite loops
-  private readonly MAX_OUTPUT_SIZE = 5 * 1024 * 1024; // 5MB max output to accommodate image payloads
-  private readonly GEMINI_MODEL = "models/gemini-2.5-flash";
-  private readonly GEMINI_IMAGE_MODEL = "imagen-4.0-fast-generate-001";
-  private readonly SUPPORTED_TRANSLATION_LANGUAGES = ["pt", "en", "es", "fr"];
+  private readonly MAX_VARIABLE_SIZE = 1024;
+  private readonly MAX_WORKFLOW_STEPS = 100;
+  private readonly MAX_OUTPUT_SIZE = 5 * 1024 * 1024;
   private readonly schemaCompiler = new DeclarativeSchemaCompiler();
 
   /**
@@ -82,16 +95,14 @@ export class DeclarativeAgentInterpreter {
     const startTime = Date.now();
 
     try {
-      // Parse and validate YAML
       const agent = this.parseYaml(options.yamlContent);
       this.validateAgentDefinition(agent);
 
-      // Compile schemas and validate input up front
       const schemas = this.buildSchemaSet(agent);
       const validatedInput = this.validateAgainstSchema(
         options.input,
         schemas.input,
-        "input",
+        'input',
         options.context
       );
 
@@ -100,14 +111,12 @@ export class DeclarativeAgentInterpreter {
         input: validatedInput,
       };
 
-      // Execute declarative logic
       const result = await this.executeWorkflow(agent, executionOptions);
 
-      // Validate output
       const validatedOutput = this.validateAgainstSchema(
         result,
         schemas.output,
-        "output",
+        'output',
         options.context
       );
       this.enforceOutputSize(validatedOutput);
@@ -117,30 +126,24 @@ export class DeclarativeAgentInterpreter {
 
       return validatedOutput;
     } catch (error) {
-      const executionTime = Date.now() - startTime;
       options.context.log(`Declarative agent execution failed: ${error}`);
       options.context.setError(
-        error instanceof Error
-          ? error.message
-          : "Unknown declarative agent error"
+        error instanceof Error ? error.message : 'Unknown declarative agent error'
       );
       throw error;
     }
   }
 
-  /**
-   * Parse and validate YAML content
-   */
   private parseYaml(yamlContent: string): YamlAgentDefinition {
     try {
       const parsed = yaml.load(yamlContent) as YamlAgentDefinition;
 
-      if (!parsed || typeof parsed !== "object") {
-        throw new Error("Invalid YAML: expected object");
+      if (!parsed || typeof parsed !== 'object') {
+        throw new Error('Invalid YAML: expected object');
       }
 
       if (!parsed.agent || !parsed.logic || !parsed.schema) {
-        throw new Error("Invalid agent definition: missing required sections");
+        throw new Error('Invalid agent definition: missing required sections');
       }
 
       return parsed;
@@ -149,32 +152,21 @@ export class DeclarativeAgentInterpreter {
     }
   }
 
-  /**
-   * Validate agent definition structure
-   */
   private validateAgentDefinition(agent: YamlAgentDefinition): void {
-    // Validate protocol version
-    if (agent.agent.protocol !== "beddel-declarative-protocol/v2.0") {
+    if (agent.agent.protocol !== 'beddel-declarative-protocol/v2.0') {
       throw new Error(`Unsupported protocol: ${agent.agent.protocol}`);
     }
 
-    // Validate schema
     if (!agent.schema.input || !agent.schema.output) {
-      throw new Error("Invalid schema: missing input or output definition");
+      throw new Error('Invalid schema: missing input or output definition');
     }
 
-    // Validate workflow
-    if (
-      !Array.isArray(agent.logic.workflow) ||
-      agent.logic.workflow.length === 0
-    ) {
-      throw new Error("Invalid workflow: must be non-empty array");
+    if (!Array.isArray(agent.logic.workflow) || agent.logic.workflow.length === 0) {
+      throw new Error('Invalid workflow: must be non-empty array');
     }
 
     if (agent.logic.workflow.length > this.MAX_WORKFLOW_STEPS) {
-      throw new Error(
-        `Workflow too complex: max ${this.MAX_WORKFLOW_STEPS} steps allowed`
-      );
+      throw new Error(`Workflow too complex: max ${this.MAX_WORKFLOW_STEPS} steps allowed`);
     }
   }
 
@@ -183,8 +175,8 @@ export class DeclarativeAgentInterpreter {
     output: ZodTypeAny;
   } {
     return {
-      input: this.schemaCompiler.compile(agent.schema.input, "schema.input"),
-      output: this.schemaCompiler.compile(agent.schema.output, "schema.output"),
+      input: this.schemaCompiler.compile(agent.schema.input, 'schema.input'),
+      output: this.schemaCompiler.compile(agent.schema.output, 'schema.output'),
     };
   }
 
@@ -198,29 +190,23 @@ export class DeclarativeAgentInterpreter {
     if (!validationResult.success) {
       const issues = validationResult.error.issues;
       const issueSummary = issues
-        .map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
-        .join("; ");
-      const label = phase === "input" ? "Input" : "Output";
+        .map((issue) => `${issue.path.join('.') || 'root'}: ${issue.message}`)
+        .join('; ');
+      const label = phase === 'input' ? 'Input' : 'Output';
       const message = `${label} validation failed: ${issueSummary}`;
       context.setError(message);
       throw new DeclarativeSchemaValidationError(message, phase, issues);
     }
-
     return validationResult.data;
   }
 
   private enforceOutputSize(output: any): void {
     const outputSize = JSON.stringify(output).length;
     if (outputSize > this.MAX_OUTPUT_SIZE) {
-      throw new Error(
-        `Output size exceeds maximum allowed: ${outputSize} > ${this.MAX_OUTPUT_SIZE}`
-      );
+      throw new Error(`Output size exceeds maximum allowed: ${outputSize} > ${this.MAX_OUTPUT_SIZE}`);
     }
   }
 
-  /**
-   * Execute declarative workflow
-   */
   private async executeWorkflow(
     agent: YamlAgentDefinition,
     options: YamlAgentInterpreterOptions
@@ -228,7 +214,6 @@ export class DeclarativeAgentInterpreter {
     const variables = new Map<string, any>();
     let output: any = undefined;
 
-    // Initialize variables
     if (agent.logic.variables) {
       for (const variable of agent.logic.variables) {
         this.validateVariable(variable);
@@ -237,7 +222,6 @@ export class DeclarativeAgentInterpreter {
       }
     }
 
-    // Execute workflow steps
     for (const step of agent.logic.workflow) {
       output = await this.executeWorkflowStep(step, variables, options);
     }
@@ -245,9 +229,6 @@ export class DeclarativeAgentInterpreter {
     return output;
   }
 
-  /**
-   * Execute single workflow step
-   */
   private async executeWorkflowStep(
     step: any,
     variables: Map<string, any>,
@@ -256,53 +237,65 @@ export class DeclarativeAgentInterpreter {
     options.context.log(`Executing workflow step: ${step.name} (${step.type})`);
 
     switch (step.type) {
-      case "output-generator":
+      case 'output-generator':
         return this.executeOutputGenerator(step, variables, options);
-      case "genkit-joke":
-        return this.executeGenkitJoke(step, variables, options);
-      case "genkit-translation":
-        return this.executeGenkitTranslation(step, variables, options);
-      case "genkit-image":
-        return this.executeGenkitImage(step, variables, options);
-      case "custom-action":
+      // Preferred step types
+      case 'joke':
+      case 'genkit-joke':
+        return this.executeJoke(step, variables, options);
+      case 'translation':
+      case 'genkit-translation':
+        return this.executeTranslation(step, variables, options);
+      case 'image':
+      case 'genkit-image':
+        return this.executeImage(step, variables, options);
+      case 'vectorize':
+      case 'gemini-vectorize':
+        return this.executeVectorize(step, variables, options);
+      case 'custom-action':
         return this.executeCustomAction(step, variables, options);
+      case 'mcp-tool':
+        return this.executeMcpTool(step, variables, options);
+      case 'chromadb':
+        return this.executeChromaDB(step, variables, options);
+      case 'gitmcp':
+        return this.executeGitMcp(step, variables, options);
+      case 'rag':
+        return this.executeRag(step, variables, options);
+      case 'chat':
+        return this.executeChat(step, variables, options);
+      case 'builtin-agent':
+        return this.executeBuiltinAgent(step, variables, options);
       default:
         throw new Error(`Unsupported workflow step type: ${step.type}`);
     }
   }
 
-  /**
-   * Execute output generator step
-   */
+  // ============================================================================
+  // Output Generator (kept inline - orchestration logic)
+  // ============================================================================
+
   private executeOutputGenerator(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
   ): any {
-    if (step.action?.type !== "generate" || !step.action.output) {
-      throw new Error("Invalid output generator configuration");
+    if (step.action?.type !== 'generate' || !step.action.output) {
+      throw new Error('Invalid output generator configuration');
     }
 
-    // Build output object
     const output: any = {};
 
-    // Debug: Log available variables
     options.context.log(
-      `Output generator: Available variables: ${Array.from(variables.keys()).join(", ")}`
+      `Output generator: Available variables: ${Array.from(variables.keys()).join(', ')}`
     );
 
     for (const [key, valueExpr] of Object.entries(step.action.output)) {
-      if (typeof valueExpr === "string" && valueExpr.startsWith("$")) {
+      if (typeof valueExpr === 'string' && valueExpr.startsWith('$')) {
         try {
           const reference = valueExpr.substring(1);
-          options.context.log(
-            `Output generator: Resolving reference ${valueExpr} -> ${reference}`
-          );
           const resolved = this.resolveReference(reference, variables);
           output[key] = resolved;
-          options.context.log(
-            `Output generator: Resolved ${key} = ${typeof resolved === "string" ? resolved.substring(0, 50) + "..." : JSON.stringify(resolved).substring(0, 100)}`
-          );
         } catch (error) {
           options.context.log(
             `Output generator: Failed to resolve ${valueExpr}: ${error instanceof Error ? error.message : String(error)}`
@@ -314,72 +307,62 @@ export class DeclarativeAgentInterpreter {
       }
     }
 
-    options.context.log(
-      `Output generator: Final output keys: ${Object.keys(output).join(", ")}`
-    );
-
     return output;
   }
 
-  /**
-   * Execute Gemini Flash text helper for the joke agent
-   */
-  private async executeGenkitJoke(
+  // ============================================================================
+  // Delegated Handlers - Using extracted agent handlers
+  // ============================================================================
+
+  private async executeJoke(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
   ): Promise<any> {
     const prompt =
-      typeof step.action?.prompt === "string" && step.action.prompt.trim().length
+      typeof step.action?.prompt === 'string' && step.action.prompt.trim().length
         ? step.action.prompt.trim()
-        : "Conte uma piada curta e original em português.";
+        : 'Tell a short and original joke that works for any audience.';
     const temperature =
-      typeof step.action?.temperature === "number"
-        ? step.action.temperature
-        : 0.8;
+      typeof step.action?.temperature === 'number' ? step.action.temperature : 0.8;
     const maxTokens =
-      typeof step.action?.maxTokens === "number"
-        ? step.action.maxTokens
-        : undefined;
+      typeof step.action?.maxTokens === 'number' ? step.action.maxTokens : undefined;
     const resultVar =
-      typeof step.action?.result === "string" && step.action.result.length > 0
+      typeof step.action?.result === 'string' && step.action.result.length > 0
         ? step.action.result
-        : "jokerResult";
+        : 'jokerResult';
 
-    const joke = await this.callGeminiFlashText(
+    const result = await executeJokeHandler(
       { prompt, temperature, maxTokens },
       options.props,
       options.context
     );
 
-    variables.set(resultVar, joke);
-    return joke;
+    variables.set(resultVar, result);
+    return result;
   }
 
-  /**
-   * Execute translation step backed by Gemini Flash
-   */
-  private async executeGenkitTranslation(
+  private async executeTranslation(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
   ): Promise<any> {
-    const texto = options.input?.texto;
-    const idiomaOrigem = options.input?.idioma_origem;
-    const idiomaDestino = options.input?.idioma_destino;
+    const text = options.input?.texto || options.input?.text;
+    const sourceLanguage = options.input?.idioma_origem || options.input?.source_language;
+    const targetLanguage = options.input?.idioma_destino || options.input?.target_language;
 
     const resultVar =
-      typeof step.action?.result === "string" && step.action.result.length > 0
+      typeof step.action?.result === 'string' && step.action.result.length > 0
         ? step.action.result
-        : "translationResult";
+        : 'translationResult';
 
-    const translation = await this.callGeminiFlashTranslation(
+    const result = await executeTranslationHandler(
       {
-        texto,
-        idioma_origem: idiomaOrigem,
-        idioma_destino: idiomaDestino,
+        text,
+        source_language: sourceLanguage,
+        target_language: targetLanguage,
         promptTemplate:
-          typeof step.action?.promptTemplate === "string"
+          typeof step.action?.promptTemplate === 'string'
             ? step.action.promptTemplate
             : undefined,
       },
@@ -387,80 +370,228 @@ export class DeclarativeAgentInterpreter {
       options.context
     );
 
-    variables.set(resultVar, translation);
-    return translation;
+    variables.set(resultVar, result);
+    return result;
   }
 
-  /**
-   * Execute image generation step backed by Gemini Flash
-   */
-  private async executeGenkitImage(
+  private async executeImage(
     step: any,
     variables: Map<string, any>,
     options: YamlAgentInterpreterOptions
   ): Promise<any> {
-    const descricao =
-      typeof options.input?.descricao === "string"
+    const description =
+      typeof options.input?.descricao === 'string'
         ? options.input.descricao.trim()
-        : "";
-    const estilo =
-      typeof options.input?.estilo === "string"
+        : typeof options.input?.description === 'string'
+          ? options.input.description.trim()
+          : '';
+    const style =
+      typeof options.input?.estilo === 'string'
         ? options.input.estilo.trim()
-        : "";
-    const resolucaoInput =
-      typeof options.input?.resolucao === "string"
+        : typeof options.input?.style === 'string'
+          ? options.input.style.trim()
+          : '';
+    const resolution =
+      typeof options.input?.resolucao === 'string'
         ? options.input.resolucao.trim()
-        : "";
+        : typeof options.input?.resolution === 'string'
+          ? options.input.resolution.trim()
+          : '';
 
-    if (!descricao) {
-      throw new Error("Missing required image input: descricao");
+    if (!description) {
+      throw new Error('Missing required image input: description');
     }
-    if (!estilo) {
-      throw new Error("Missing required image input: estilo");
+    if (!style) {
+      throw new Error('Missing required image input: style');
     }
-    if (!resolucaoInput) {
-      throw new Error("Missing required image input: resolucao");
+    if (!resolution) {
+      throw new Error('Missing required image input: resolution');
     }
 
     const promptTemplate =
-      typeof step.action?.promptTemplate === "string" &&
-        step.action.promptTemplate.trim().length > 0
+      typeof step.action?.promptTemplate === 'string' &&
+      step.action.promptTemplate.trim().length > 0
         ? step.action.promptTemplate
-        : "Gere uma imagem detalhada no estilo {{estilo}} baseada na descrição: {{descricao}}";
-
-    const prompt = promptTemplate
-      .replace(/{{descricao}}/g, descricao)
-      .replace(/{{estilo}}/g, estilo)
-      .trim();
+        : 'Create a detailed image in {{style}} style focusing on: {{description}}';
 
     const resultVar =
-      typeof step.action?.result === "string" && step.action.result.length > 0
+      typeof step.action?.result === 'string' && step.action.result.length > 0
         ? step.action.result
-        : "imageResult";
+        : 'imageResult';
 
-    const imageResult = await this.callGeminiFlashImage(
+    const result = await executeImageHandler(
       {
-        prompt,
-        estilo,
-        resolucao: resolucaoInput,
+        description,
+        style,
+        resolution,
+        promptTemplate,
       },
       options.props,
       options.context
     );
 
-    variables.set(resultVar, imageResult);
-    options.context.log(
-      `Image generator: Saved result in variable '${resultVar}' with keys: ${Object.keys(imageResult).join(", ")}`
+    variables.set(resultVar, result);
+    return result;
+  }
+
+  private async executeMcpTool(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const serverUrl = this.resolveInputValue(step.action?.server_url, options.input, variables);
+    const toolName = this.resolveInputValue(step.action?.tool_name, options.input, variables);
+    const toolArguments =
+      this.resolveInputValue(step.action?.tool_arguments, options.input, variables) || {};
+    const resultVar = step.action?.result || 'mcpResult';
+
+    const result = await executeMcpToolHandler(
+      {
+        server_url: serverUrl,
+        tool_name: toolName,
+        tool_arguments: toolArguments,
+      },
+      options.props,
+      options.context
     );
-    options.context.log(
-      `Image generator: imageResult.image_url exists: ${!!imageResult?.image_url}`
+
+    variables.set(resultVar, result);
+    return result;
+  }
+
+  private async executeVectorize(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const action = step.action?.action || 'embedSingle';
+    const resultVar = step.action?.result || 'vectorizeResult';
+
+    let result;
+    if (action === 'embedSingle') {
+      const text = this.resolveInputValue(step.action?.text, options.input, variables);
+      result = await executeVectorizeHandler(
+        { action: 'embedSingle', text },
+        options.props,
+        options.context
+      );
+    } else if (action === 'embedBatch') {
+      const texts = this.resolveInputValue(step.action?.texts, options.input, variables);
+      result = await executeVectorizeHandler(
+        { action: 'embedBatch', texts },
+        options.props,
+        options.context
+      );
+    } else {
+      throw new Error(`Unknown vectorize action: ${action}`);
+    }
+
+    variables.set(resultVar, result);
+    return result;
+  }
+
+  private async executeChromaDB(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const action = this.resolveInputValue(step.action?.action, options.input, variables);
+    const collectionName = this.resolveInputValue(
+      step.action?.collection_name,
+      options.input,
+      variables
     );
-    return imageResult;
+    const resultVar = step.action?.result || 'chromaResult';
+
+    let params: any = { action, collection_name: collectionName };
+
+    if (action === 'hasData') {
+      params.min_count =
+        this.resolveInputValue(step.action?.min_count, options.input, variables) || 1;
+    } else if (action === 'store') {
+      params.ids = this.resolveInputValue(step.action?.ids, options.input, variables);
+      params.vectors = this.resolveInputValue(step.action?.vectors, options.input, variables);
+      params.documents = this.resolveInputValue(step.action?.documents, options.input, variables);
+      params.metadatas = this.resolveInputValue(step.action?.metadatas, options.input, variables);
+    } else if (action === 'search') {
+      params.query_vector = this.resolveInputValue(
+        step.action?.query_vector,
+        options.input,
+        variables
+      );
+      params.limit =
+        this.resolveInputValue(step.action?.limit, options.input, variables) || 5;
+    }
+
+    const result = await executeChromaDBHandler(params, options.props, options.context);
+
+    variables.set(resultVar, result);
+    return result;
   }
 
-  /**
-   * Execute custom action backed by TypeScript implementation
-   */
+  private async executeGitMcp(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const gitmcpUrl = this.resolveInputValue(step.action?.gitmcp_url, options.input, variables);
+    const resultVar = step.action?.result || 'gitmcpResult';
+
+    const result = await executeGitMcpHandler(
+      { gitmcp_url: gitmcpUrl },
+      options.props,
+      options.context
+    );
+
+    variables.set(resultVar, result);
+    return result;
+  }
+
+  private async executeRag(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const query = this.resolveInputValue(step.action?.query, options.input, variables);
+    const context =
+      this.resolveInputValue(step.action?.context, options.input, variables) ||
+      this.resolveInputValue(step.action?.documents, options.input, variables);
+    const history = this.resolveInputValue(step.action?.history, options.input, variables);
+    const resultVar = step.action?.result || 'ragResult';
+
+    const result = await executeRagHandler(
+      { query, context, documents: context, history },
+      options.props,
+      options.context
+    );
+
+    variables.set(resultVar, result);
+    return result;
+  }
+
+  private async executeChat(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const messages = this.resolveInputValue(step.action?.messages, options.input, variables);
+    const query = this.resolveInputValue(step.action?.query, options.input, variables);
+    const resultVar = step.action?.result || 'chatResult';
+
+    const result = await executeChatHandler(
+      { messages, query },
+      options.props,
+      options.context
+    );
+
+    variables.set(resultVar, result);
+    return result;
+  }
+
+  // ============================================================================
+  // Custom Action & Builtin Agent (orchestration logic)
+  // ============================================================================
+
   private async executeCustomAction(
     step: any,
     variables: Map<string, any>,
@@ -473,16 +604,14 @@ export class DeclarativeAgentInterpreter {
 
     options.context.log(`Custom action: Looking up function '${functionName}'`);
 
-    // Retrieve Code Implementation
     const customFunc = agentRegistry.getCustomFunction(functionName);
     if (!customFunc) {
       throw new Error(
         `Custom function '${functionName}' not found in registry. ` +
-        `Make sure the corresponding .ts file is in the /agents directory.`
+          `Make sure the corresponding .ts file is in the /agents directory.`
       );
     }
 
-    // Prepare Arguments
     const args = {
       input: options.input,
       variables: Object.fromEntries(variables),
@@ -492,16 +621,11 @@ export class DeclarativeAgentInterpreter {
 
     options.context.log(`Custom action: Executing function '${functionName}'`);
 
-    // Execute Code
     try {
       const result = await customFunc(args);
 
-      // Save Result
       if (step.action.result) {
         variables.set(step.action.result, result);
-        options.context.log(
-          `Custom action: Saved result to variable '${step.action.result}'`
-        );
       }
 
       return result;
@@ -513,77 +637,129 @@ export class DeclarativeAgentInterpreter {
     }
   }
 
+  private async executeBuiltinAgent(
+    step: any,
+    variables: Map<string, any>,
+    options: YamlAgentInterpreterOptions
+  ): Promise<any> {
+    const agentName = step.action?.agent;
+    const agentInput =
+      this.resolveInputValue(step.action?.input, options.input, variables) || options.input;
+    const agentProps = step.action?.props || options.props;
+    const resultVar = step.action?.result || 'builtinResult';
+
+    if (!agentName) {
+      throw new Error('Missing required builtin-agent input: agent');
+    }
+
+    options.context.log(`[Builtin Agent] Invoking agent: ${agentName}`);
+
+    try {
+      const result = await agentRegistry.executeAgent(
+        agentName,
+        agentInput,
+        agentProps,
+        options.context
+      );
+
+      variables.set(resultVar, result);
+      return result;
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      options.context.log(`[Builtin Agent] Error: ${message}`);
+      throw new Error(`Builtin agent '${agentName}' execution failed: ${message}`);
+    }
+  }
+
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+
+  private resolveInputValue(
+    value: any,
+    input: Record<string, any>,
+    variables: Map<string, any>
+  ): any {
+    if (value === undefined || value === null) return undefined;
+
+    if (typeof value === 'string' && value.startsWith('$')) {
+      const ref = value.substring(1);
+      if (ref.startsWith('input.')) {
+        const inputKey = ref.substring(6);
+        return this.getNestedValue(input, inputKey);
+      }
+      return this.resolveReference(ref, variables);
+    }
+
+    if (typeof value === 'string' && input[value] !== undefined) {
+      return input[value];
+    }
+
+    return value;
+  }
+
+  private getNestedValue(obj: any, path: string): any {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+      if (current == null) return undefined;
+      current = current[part];
+    }
+    return current;
+  }
 
-  /**
-   * Evaluate value expression
-   */
   private evaluateValue(expr: string, variables: Map<string, any>): any {
-    // Handle string literals
     if (expr.startsWith('"') && expr.endsWith('"')) {
       if (expr.length - 2 > this.MAX_VARIABLE_SIZE) {
-        throw new Error("Variable initialization exceeds maximum size");
+        throw new Error('Variable initialization exceeds maximum size');
       }
       return expr.slice(1, -1);
     }
 
     if (expr.startsWith("'") && expr.endsWith("'")) {
       if (expr.length - 2 > this.MAX_VARIABLE_SIZE) {
-        throw new Error("Variable initialization exceeds maximum size");
+        throw new Error('Variable initialization exceeds maximum size');
       }
       return expr.slice(1, -1);
     }
 
     if (expr.length > this.MAX_VARIABLE_SIZE) {
-      throw new Error("Variable initialization exceeds maximum size");
+      throw new Error('Variable initialization exceeds maximum size');
     }
 
-    // Handle boolean literals
-    if (expr === "true") return true;
-    if (expr === "false") return false;
-
-    // Handle null literal
-    if (expr === "null") return null;
+    if (expr === 'true') return true;
+    if (expr === 'false') return false;
+    if (expr === 'null') return null;
 
-    // Handle variable references
-    if (expr.startsWith("$")) {
+    if (expr.startsWith('$')) {
       return this.resolveReference(expr.substring(1), variables);
     }
 
-    // Handle numbers
     if (/^-?\d+$/.test(expr)) return parseInt(expr, 10);
     if (/^-?\d+\.\d+$/.test(expr)) return parseFloat(expr);
 
     throw new Error(`Unsupported value expression: ${expr}`);
   }
 
-  /**
-   * Validate variable declaration
-   */
   private validateVariable(variable: any): void {
     if (!variable.name || !variable.type) {
-      throw new Error("Invalid variable declaration: missing name or type");
+      throw new Error('Invalid variable declaration: missing name or type');
     }
 
-    if (!["string", "number", "boolean", "object"].includes(variable.type)) {
+    if (!['string', 'number', 'boolean', 'object'].includes(variable.type)) {
       throw new Error(`Unsupported variable type: ${variable.type}`);
     }
   }
 
-  /**
-   * Resolve variable reference, including nested properties (e.g., foo.bar.baz)
-   */
-  private resolveReference(
-    reference: string,
-    variables: Map<string, any>
-  ): any {
-    const [varName, ...pathSegments] = reference.split(".");
+  private resolveReference(reference: string, variables: Map<string, any>): any {
+    const [varName, ...pathSegments] = reference.split('.');
     let value = variables.get(varName);
     if (value === undefined) {
       throw new Error(`Undefined variable referenced: ${varName}`);
     }
 
     for (const segment of pathSegments) {
-      if (value == null || typeof value !== "object") {
+      if (value == null || typeof value !== 'object') {
         throw new Error(
           `Cannot resolve path '${reference}': segment '${segment}' is invalid`
         );
@@ -593,299 +769,6 @@ export class DeclarativeAgentInterpreter {
 
     return value;
   }
-
-  /**
-   * Ensure we have a Gemini API key before calling Genkit helpers
-   */
-  private ensureGeminiApiKey(props: Record<string, string>): string {
-    const apiKey = props?.gemini_api_key?.trim();
-    if (!apiKey) {
-      throw new Error(
-        "Missing required prop: gemini_api_key. Configure a valid Gemini API key before calling this agent."
-      );
-    }
-    return apiKey;
-  }
-
-  private createGeminiModel(props: Record<string, string>) {
-    const apiKey = this.ensureGeminiApiKey(props);
-    const google = createGoogleGenerativeAI({ apiKey });
-    const model = google(this.GEMINI_MODEL);
-    return model;
-  }
-
-  private createGeminiImageModel(props: Record<string, string>) {
-    const apiKey = this.ensureGeminiApiKey(props);
-    const google = createGoogleGenerativeAI({ apiKey });
-    return google.image(this.GEMINI_IMAGE_MODEL);
-  }
-
-  private async callGeminiFlashText(
-    params: {
-      prompt: string;
-      temperature?: number;
-      maxTokens?: number;
-    },
-    props: Record<string, string>,
-    context: ExecutionContext
-  ): Promise<{
-    texto: string;
-    metadados: {
-      modelo_utilizado: string;
-      tempo_processamento: number;
-      temperature: number;
-      max_tokens: number | null;
-      prompt_utilizado: string;
-    };
-  }> {
-    const prompt = params.prompt?.trim();
-    if (!prompt) {
-      throw new Error("Gemini Flash text helper requires a prompt");
-    }
-
-    const temperature =
-      typeof params.temperature === "number" ? params.temperature : 0.7;
-    const maxTokens =
-      typeof params.maxTokens === "number" ? params.maxTokens : undefined;
-
-    const model = this.createGeminiModel(props);
-    const startTime = Date.now();
-
-    try {
-      context.log(
-        `Invoking Gemini Flash text helper (temperature=${temperature}, maxTokens=${typeof maxTokens === "number" ? maxTokens : "provider-default"
-        })`
-      );
-      const generationOptions: Record<string, any> = {
-        model,
-        prompt,
-        temperature,
-      };
-      if (typeof maxTokens === "number") {
-        generationOptions.maxOutputTokens = maxTokens;
-      }
-      const { text, content } = await generateText(
-        generationOptions as any
-      );
-      const contentText = content
-        ? content
-          .map((part: any) =>
-            typeof part?.text === "string" ? part.text : ""
-          )
-          .join(" ")
-          .trim()
-        : "";
-      const finalText = (text || "").trim() || contentText || "";
-      if (!finalText) {
-        throw new Error("Gemini Flash text helper returned empty response");
-      }
-
-      return {
-        texto: finalText,
-        metadados: {
-          modelo_utilizado: this.GEMINI_MODEL,
-          tempo_processamento: Date.now() - startTime,
-          temperature,
-          max_tokens: typeof maxTokens === "number" ? maxTokens : null,
-          prompt_utilizado: prompt,
-        },
-      };
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Unknown Gemini Flash error";
-      context.log(`Gemini Flash text helper failed: ${message}`);
-      context.setError(message);
-      throw error;
-    }
-  }
-
-  private async callGeminiFlashTranslation(
-    params: {
-      texto?: string;
-      idioma_origem?: string;
-      idioma_destino?: string;
-      promptTemplate?: string;
-    },
-    props: Record<string, string>,
-    context: ExecutionContext
-  ): Promise<{
-    texto_traduzido: string;
-    metadados: {
-      modelo_utilizado: string;
-      tempo_processamento: number;
-      confianca: number;
-      idiomas_suportados: string[];
-      idiomas_solicitados: {
-        origem: string;
-        destino: string;
-      };
-      prompt_utilizado: string;
-    };
-  }> {
-    const texto = params.texto?.trim();
-    const idiomaOrigem = params.idioma_origem?.trim().toLowerCase();
-    const idiomaDestino = params.idioma_destino?.trim().toLowerCase();
-
-    if (!texto || !idiomaOrigem || !idiomaDestino) {
-      throw new Error(
-        "Missing required translation parameters: texto, idioma_origem, idioma_destino"
-      );
-    }
-
-    if (idiomaOrigem === idiomaDestino) {
-      return {
-        texto_traduzido: texto,
-        metadados: {
-          modelo_utilizado: this.GEMINI_MODEL,
-          tempo_processamento: 0,
-          confianca: 1,
-          idiomas_suportados: this.SUPPORTED_TRANSLATION_LANGUAGES,
-          idiomas_solicitados: {
-            origem: idiomaOrigem,
-            destino: idiomaDestino,
-          },
-          prompt_utilizado: "Bypass: idiomas de origem e destino são iguais",
-        },
-      };
-    }
-
-    const template =
-      params.promptTemplate && params.promptTemplate.trim().length > 0
-        ? params.promptTemplate
-        : `Traduza o texto abaixo de {{idioma_origem}} para {{idioma_destino}}.
-Responda somente com o texto traduzido sem comentários adicionais.
-
-Texto:
-{{texto}}`;
-
-    const prompt = template
-      .replace(/{{texto}}/g, texto)
-      .replace(/{{idioma_origem}}/g, idiomaOrigem)
-      .replace(/{{idioma_destino}}/g, idiomaDestino)
-      .trim();
-
-    const model = this.createGeminiModel(props);
-    const startTime = Date.now();
-
-    try {
-      context.log(
-        `Invoking Gemini Flash translation helper (${idiomaOrigem}->${idiomaDestino})`
-      );
-      const { text, content } = await generateText({
-        model,
-        prompt,
-        temperature: 0.2,
-      });
-
-      const contentText = content
-        ? content
-          .map((part: any) =>
-            typeof part?.text === "string" ? part.text : ""
-          )
-          .join(" ")
-          .trim()
-        : "";
-      const translatedText = (text || "").trim() || contentText || "";
-      if (!translatedText) {
-        throw new Error("Gemini Flash translation returned empty response");
-      }
-
-      return {
-        texto_traduzido: translatedText,
-        metadados: {
-          modelo_utilizado: this.GEMINI_MODEL,
-          tempo_processamento: Date.now() - startTime,
-          confianca: 0.85,
-          idiomas_suportados: this.SUPPORTED_TRANSLATION_LANGUAGES,
-          idiomas_solicitados: {
-            origem: idiomaOrigem,
-            destino: idiomaDestino,
-          },
-          prompt_utilizado: prompt,
-        },
-      };
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Unknown translation error";
-      context.log(`Gemini Flash translation failed: ${message}`);
-      context.setError(message);
-      throw error;
-    }
-  }
-
-  private async callGeminiFlashImage(
-    params: { prompt: string; estilo: string; resolucao: string },
-    props: Record<string, string>,
-    context: ExecutionContext
-  ): Promise<{
-    image_url: string;
-    image_base64: string;
-    media_type: string;
-    prompt_utilizado: string;
-    metadados: {
-      modelo_utilizado: string;
-      tempo_processamento: number;
-      estilo: string;
-      resolucao: string;
-    };
-  }> {
-    const prompt = params.prompt?.trim();
-    const estilo = params.estilo?.trim();
-    const resolucao = params.resolucao?.trim();
-
-    if (!prompt) {
-      throw new Error("Gemini Flash image helper requires a prompt");
-    }
-    if (!estilo) {
-      throw new Error("Gemini Flash image helper requires an estilo value");
-    }
-    if (!resolucao || !/^\d+x\d+$/.test(resolucao)) {
-      throw new Error(
-        "Gemini Flash image helper requires uma resolução no formato LARGURAxALTURA (ex: 1024x1024)"
-      );
-    }
-
-    const model = this.createGeminiImageModel(props);
-    const startTime = Date.now();
-
-    try {
-      context.log(
-        `Invoking Gemini Flash image helper (estilo=${estilo}, resolucao=${resolucao})`
-      );
-      const result = await experimental_generateImage({
-        model,
-        prompt,
-        size: resolucao as `${number}x${number}`,
-      });
-
-      const image = result.image;
-      if (!image?.base64 || !image.mediaType) {
-        throw new Error("Gemini Flash image helper returned an invalid file");
-      }
-
-      const normalizedBase64 = image.base64.replace(/\s+/g, "");
-      const imageUrl = `data:${image.mediaType};base64,${normalizedBase64}`;
-
-      return {
-        image_url: imageUrl,
-        image_base64: normalizedBase64,
-        media_type: image.mediaType,
-        prompt_utilizado: prompt,
-        metadados: {
-          modelo_utilizado: this.GEMINI_IMAGE_MODEL,
-          tempo_processamento: Date.now() - startTime,
-          estilo,
-          resolucao,
-        },
-      };
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Unknown image error";
-      context.log(`Gemini Flash image helper failed: ${message}`);
-      context.setError(message);
-      throw error;
-    }
-  }
 }
 
 // Singleton instance