Tool-Entwicklung

Erstellen Sie benutzerdefinierte Tools, um die Fähigkeiten von Gemini CLI zu erweitern. Lernen Sie, wie Sie Tools entwerfen, implementieren, testen und bereitstellen, die sich nahtlos in KI-Gespräche integrieren.

Entwicklungsprozess

Schritt-für-Schritt-Anleitung zur Erstellung benutzerdefinierter Tools

1

Tool-Interface definieren

Erstellen Sie die Tool-Definition mit Parametern und Beschreibung

Beispiel:

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

Tool-Logik implementieren

Schreiben Sie die Ausführungsfunktion, die die Aufgabe des Tools ausführt

Beispiel:

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

Tool registrieren

Das Tool zur Tool-Registry von Gemini CLI hinzufügen

Beispiel:

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

Tool testen

Testen Sie Ihr Tool, um sicherzustellen, dass es korrekt funktioniert

Beispiel:

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

Tool-Vorlage

Verwenden Sie diese Vorlage, um schnell mit Ihrer benutzerdefinierten Tool-Entwicklung zu beginnen

Basis-Tool-Vorlage

Kopieren Sie diese Vorlage und ändern Sie sie entsprechend Ihren Bedürfnissen. Stellen Sie sicher, dass Sie Name, Beschreibung, Parameter und Ausführungslogik aktualisieren.

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

Bewährte Praktiken

Befolgen Sie diese Richtlinien, um hochwertige, zuverlässige Tools zu erstellen

Tool-Design

  • Halten Sie Tools auf eine einzige Verantwortung fokussiert
  • Verwenden Sie klare, beschreibende Namen und Beschreibungen
  • Definieren Sie umfassende Parameter-Schemas
  • Fügen Sie Beispiele in Parameterbeschreibungen ein
  • Behandeln Sie Grenzfälle elegant

Fehlerbehandlung

  • Ausführung immer in try-catch-Blöcke einschließen
  • Aussagekräftige Fehlermeldungen zurückgeben
  • Eingabeparameter validieren
  • Netzwerk-Timeouts und -Fehler behandeln
  • Fehler für Debugging protokollieren

Leistung

  • Asynchrone Operationen korrekt implementieren
  • Timeout-Behandlung für lange Operationen hinzufügen
  • Ergebnisse bei Bedarf zwischenspeichern
  • Externe Abhängigkeiten minimieren
  • Streaming für große Antworten verwenden

Sicherheit

  • Alle Eingaben validieren und bereinigen
  • Ausführung von beliebigem Code vermeiden
  • Dateisystemzugriff begrenzen
  • Sichere API-Endpunkte verwenden
  • Sensible Daten vorsichtig behandeln

Testen Sie Ihre Tools

Stellen Sie sicher, dass Ihre Tools vor der Bereitstellung korrekt funktionieren

Unit-Tests

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

Integrationstests

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

Testen und Debugging

Tipps, um sicherzustellen, dass Ihre Tools zuverlässig laufen

Test-Strategien

  • Tool-Funktionen isoliert testen
  • Mit verschiedenen Eingabeparametern testen
  • Fehlerbedingungen und Grenzfälle testen
  • Integration mit KI verifizieren

Debugging-Tipps

  • Detaillierte Protokollierung hinzufügen
  • console.log für Debugging verwenden
  • Parametervalidierung überprüfen
  • Leistungsmetriken überwachen

Häufige Tool-Muster

Wiederverwendbare Muster für verschiedene Tool-Typen

API-Integrations-Tool

Muster für Tools, die sich in externe APIs integrieren

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

Datenverarbeitungs-Tool

Muster für Tools, die Daten verarbeiten und transformieren

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

Verwandte Ressourcen

Vertiefen Sie sich in Tool-Entwicklung und API-Integration

Tools APIEingebaute ToolsPlugin API