Desarrollo de Herramientas

Crea herramientas personalizadas para extender las capacidades de Gemini CLI. Aprende a diseñar, implementar, probar y desplegar herramientas que se integren perfectamente con conversaciones de IA.

Proceso de Desarrollo

Guía paso a paso para crear herramientas personalizadas

Definir Interfaz de Herramienta

Crear la definición de herramienta con parámetros y descripción

Ejemplo:

const toolDefinition = {
  name: 'calculate_age',
  description: 'Calculate age based on birth date',
  parameters: {
    type: 'object',
    properties: {
      birthDate: {
        type: 'string',
        format: 'date',
        description: 'Birth date in YYYY-MM-DD format'
      },
      currentDate: {
        type: 'string',
        format: 'date',
        description: 'Current date (optional, defaults to today)'
      }
    },
    required: ['birthDate']
  }
};

Implementar Lógica de Herramienta

Escribir la función de ejecución que realiza la tarea de la herramienta

Ejemplo:

const executeFunction = async ({ birthDate, currentDate }) => {
  try {
    const birth = new Date(birthDate);
    const current = currentDate ? new Date(currentDate) : new Date();
    
    if (birth > current) {
      throw new Error('Birth date cannot be in the future');
    }
    
    const ageMs = current.getTime() - birth.getTime();
    const ageYears = Math.floor(ageMs / (1000 * 60 * 60 * 24 * 365.25));
    
    return `Age: ${ageYears} years old`;
  } catch (error) {
    return `Error: ${error.message}`;
  }
};

Registrar la Herramienta

Agregar la herramienta al registro de herramientas de Gemini CLI

Ejemplo:

import { GeminiCLI } from '@google/generative-ai-cli';

const cli = new GeminiCLI();

// Create complete tool
const ageTool = {
  ...toolDefinition,
  execute: executeFunction
};

// Register the tool
cli.registerTool(ageTool);

// Verify registration
console.log('Registered tools:', cli.listTools().map(t => t.name));

Probar la Herramienta

Prueba tu herramienta para asegurar que funciona correctamente

Ejemplo:

// Test the tool directly
const result = await cli.executeTool('calculate_age', {
  birthDate: '1990-05-15'
});
console.log(result); // "Age: 34 years old"

// Test with AI
const response = await cli.ask(
  "How old would someone born on May 15, 1990 be today?",
  { tools: ['calculate_age'] }
);

Plantilla de Herramienta

Usa esta plantilla para comenzar rápidamente tu desarrollo de herramientas personalizadas

Plantilla de Herramienta Básica

Copia esta plantilla y modifícala según tus necesidades. Asegúrate de actualizar el nombre, descripción, parámetros y lógica de ejecución.

import { Tool, ToolDefinition } from '@google/generative-ai-cli';

export const myCustomTool: ToolDefinition = {
  name: 'my_custom_tool',
  description: 'Description of what this tool does',
  parameters: {
    type: 'object',
    properties: {
      // Define your parameters here
      input: {
        type: 'string',
        description: 'Input parameter description'
      }
    },
    required: ['input']
  },
  execute: async (params) => {
    try {
      // Your tool logic here
      const { input } = params;
      
      // Process the input
      const result = processInput(input);
      
      // Return the result
      return result;
    } catch (error) {
      // Handle errors gracefully
      return `Error: ${error.message}`;
    }
  }
};

function processInput(input: string): string {
  // Your processing logic
  return `Processed: ${input}`;
}

Mejores Prácticas

Sigue estas pautas para crear herramientas de alta calidad y confiables

Diseño de Herramienta

Mantener las herramientas enfocadas en una sola responsabilidad
Usar nombres y descripciones claros y descriptivos
Definir esquemas de parámetros integrales
Incluir ejemplos en las descripciones de parámetros
Manejar casos límite con elegancia

Manejo de Errores

Siempre envolver la ejecución en bloques try-catch
Devolver mensajes de error significativos
Validar parámetros de entrada
Manejar timeouts y fallos de red
Registrar errores para depuración

Rendimiento

Implementar operaciones asíncronas correctamente
Agregar manejo de timeout para operaciones largas
Cachear resultados cuando sea apropiado
Minimizar dependencias externas
Usar streaming para respuestas grandes

Seguridad

Validar y limpiar todas las entradas
Evitar ejecutar código arbitrario
Limitar el acceso al sistema de archivos
Usar endpoints de API seguros
Manejar datos sensibles con cuidado

Probar Sus Herramientas

Asegúrate de que tus herramientas funcionen correctamente antes del despliegue

Pruebas Unitarias

// Test tool execution directly
import { myCustomTool } from './my-tool';

describe('myCustomTool', () => {
  test('should process input correctly', async () => {
    const result = await myCustomTool.execute({
      input: 'test data'
    });

    expect(result).toBe('Processed: test data');
  });

  test('should handle errors gracefully', async () => {
    const result = await myCustomTool.execute({
      input: null
    });

    expect(result).toMatch(/Error:/);
  });
});

Pruebas de Integración

// Test tool with Gemini CLI
import { GeminiCLI } from '@google/generative-ai-cli';

const cli = new GeminiCLI();
cli.registerTool(myCustomTool);

// Test tool registration
const tools = cli.listTools();
expect(tools.find(t => t.name === 'my_custom_tool')).toBeDefined();

// Test tool execution
const result = await cli.executeTool('my_custom_tool', {
  input: 'test'
});
expect(result).toBeDefined();

Pruebas y Depuración

Consejos para asegurar que tus herramientas funcionen de manera confiable

Estrategias de Prueba

Probar funciones de herramientas en aislamiento
Probar con varios parámetros de entrada
Probar condiciones de error y casos límite
Verificar integración con IA

Consejos de Depuración

Agregar registro detallado
Usar console.log para depuración
Verificar validación de parámetros
Monitorear métricas de rendimiento

Patrones de Herramientas Comunes

Patrones reutilizables para diferentes tipos de herramientas

Herramienta de Integración API

Patrón para herramientas que se integran con APIs externas

const apiTool = {
  name: 'api_call',
  description: 'Make API calls to external services',
  parameters: {
    type: 'object',
    properties: {
      endpoint: { type: 'string', description: 'API endpoint URL' },
      method: { type: 'string', enum: ['GET', 'POST'], default: 'GET' },
      data: { type: 'object', description: 'Request payload' }
    },
    required: ['endpoint']
  },
  execute: async ({ endpoint, method = 'GET', data }) => {
    try {
      const response = await fetch(endpoint, {
        method,
        headers: { 'Content-Type': 'application/json' },
        body: data ? JSON.stringify(data) : undefined
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }

      return await response.json();
    } catch (error) {
      return `API Error: ${error.message}`;
    }
  }
};

Herramienta de Procesamiento de Datos

Patrón para herramientas que procesan y transforman datos

const processingTool = {
  name: 'data_processor',
  description: 'Process and transform data',
  parameters: {
    type: 'object',
    properties: {
      data: { type: 'array', description: 'Data to process' },
      operation: {
        type: 'string',
        enum: ['sort', 'filter', 'map', 'reduce'],
        description: 'Operation to perform'
      },
      criteria: { type: 'string', description: 'Processing criteria' }
    },
    required: ['data', 'operation']
  },
  execute: async ({ data, operation, criteria }) => {
    try {
      switch (operation) {
        case 'sort':
          return data.sort();
        case 'filter':
          return data.filter(item => item.includes(criteria));
        case 'map':
          return data.map(item => `${criteria}: ${item}`);
        case 'reduce':
          return data.reduce((acc, item) => acc + item, '');
        default:
          throw new Error(`Unknown operation: ${operation}`);
      }
    } catch (error) {
      return `Processing Error: ${error.message}`;
    }
  }
};

Recursos Relacionados

Profundiza en el desarrollo de herramientas e integración de API

API de Herramientas Herramientas Integradas API de Plugin