Développement d'Outils

Créez des outils personnalisés pour étendre les capacités de Gemini CLI. Apprenez à concevoir, implémenter, tester et déployer des outils qui s'intègrent parfaitement aux conversations IA.

Processus de Développement

Guide étape par étape pour créer des outils personnalisés

1

Définir l'Interface de l'Outil

Créer la définition de l'outil avec les paramètres et la description

Exemple:

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']
  }
};
2

Implémenter la Logique de l'Outil

Écrire la fonction d'exécution qui effectue la tâche de l'outil

Exemple:

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}`;
  }
};
3

Enregistrer l'Outil

Ajouter l'outil au registre d'outils de Gemini CLI

Exemple:

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));
4

Tester l'Outil

Testez votre outil pour vous assurer qu'il fonctionne correctement

Exemple:

// 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'] }
);

Modèle d'Outil

Utilisez ce modèle pour commencer rapidement votre développement d'outils personnalisés

Modèle d'Outil de Base

Copiez ce modèle et modifiez-le selon vos besoins. Assurez-vous de mettre à jour le nom, la description, les paramètres et la logique d'exécution.

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}`;
}

Meilleures Pratiques

Suivez ces directives pour créer des outils de haute qualité et fiables

Conception d'Outil

  • Gardez les outils concentrés sur une seule responsabilité
  • Utilisez des noms et descriptions clairs et descriptifs
  • Définissez des schémas de paramètres complets
  • Incluez des exemples dans les descriptions de paramètres
  • Gérez les cas limites avec élégance

Gestion d'Erreurs

  • Toujours envelopper l'exécution dans des blocs try-catch
  • Retourner des messages d'erreur significatifs
  • Valider les paramètres d'entrée
  • Gérer les timeouts et échecs réseau
  • Enregistrer les erreurs pour le débogage

Performance

  • Implémenter correctement les opérations asynchrones
  • Ajouter la gestion des timeouts pour les opérations longues
  • Mettre en cache les résultats quand approprié
  • Minimiser les dépendances externes
  • Utiliser le streaming pour les grandes réponses

Sécurité

  • Valider et nettoyer toutes les entrées
  • Éviter d'exécuter du code arbitraire
  • Limiter l'accès au système de fichiers
  • Utiliser des points de terminaison API sécurisés
  • Gérer les données sensibles avec précaution

Tester Vos Outils

Assurez-vous que vos outils fonctionnent correctement avant le déploiement

Tests Unitaires

// 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:/);
  });
});

Tests d'Intégration

// 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();

Tests et Débogage

Conseils pour assurer le fonctionnement fiable de vos outils

Stratégies de Test

  • Tester les fonctions d'outils en isolation
  • Tester avec divers paramètres d'entrée
  • Tester les conditions d'erreur et les cas limites
  • Vérifier l'intégration avec l'IA

Conseils de Débogage

  • Ajouter une journalisation détaillée
  • Utiliser console.log pour le débogage
  • Vérifier la validation des paramètres
  • Surveiller les métriques de performance

Modèles d'Outils Communs

Modèles réutilisables pour différents types d'outils

Outil d'Intégration API

Modèle pour les outils qui s'intègrent avec des API externes

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}`;
    }
  }
};

Outil de Traitement de Données

Modèle pour les outils qui traitent et transforment les données

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}`;
    }
  }
};

Ressources Connexes

Approfondissez le développement d'outils et l'intégration API

API OutilsOutils IntégrésAPI Plugin