Konfiguration

Eigene Tools für projektspezifische Aktionen entwickeln

Custom Tools kapseln Aktionen, die spezifisch für dein Projekt oder deinen Workflow sind. Sie unterscheiden sich von allgemeinen Tools dadurch, dass sie direkt auf deine Codebasis, deine Infrastruktur oder deine Prozesse zugeschnitten sind.

Ein Custom Tool ist mehr als ein Shell-Skript. Es ist eine sauber definierte Schnittstelle mit klarer Input-Validierung, deterministischem Verhalten und eingebauten Sicherheitsgrenzen. Wenn du Custom Tools richtig baust, werden sie zu verlässlichen Bausteinen, die sowohl von Menschen als auch von Agenten genutzt werden können.

Eingabevalidierung

Jedes Custom Tool muss seine Eingaben strikt validieren. Unklare oder fehlende Parameter sollten zu einem sofortigen Fehler führen, nicht zu stillschweigenden Annahmen. Das verhindert, dass das Tool in unerwarteten Zuständen Daten zerstört oder falsche Ergebnisse liefert.

Deterministische Ausgaben

Ein gutes Custom Tool produziert bei gleichem Input immer denselben Output. Das macht es testbar und vorhersagbar. Wenn ein Tool Zufallselemente oder externe Zustände enthält, müssen diese dokumentiert und bei der Validierung berücksichtigt werden.

Sicherheitsgrenzen

Sicherheitsprüfungen gehören ins Tool selbst, nicht in die aufrufende Logik. Ein Tool, das Dateien löscht, sollte intern prüfen, ob die Zieldatei wirklich löschbar ist. Das verhindert, dass Fehler in der Aufrufkette zu katastrophalen Ergebnissen führen.

Struktur eines Custom Tools

Ein wiederverwendbares Custom Tool folgt einer klaren Struktur: Input-Definition, Validierung, Kernlogik, Fehlerbehandlung und Output-Formatierung. Diese Trennung macht das Tool wartbar und erlaubt es anderen, es zu verstehen und anzupassen.

// Beispiel-Struktur eines Custom Tools
{
  "name": "deploy-staging",
  "description": "Deployt den aktuellen Branch auf Staging",
  "inputs": {
    "branch": {
      "type": "string",
      "required": true,
      "pattern": "^[a-z0-9-]+$"
    },
    "skip_tests": {
      "type": "boolean",
      "default": false
    }
  },
  "validation": [
    "branch must exist in remote",
    "no uncommitted changes",
    "user must have deploy permissions"
  ],
  "outputs": {
    "deployment_id": "string",
    "url": "string",
    "status": "enum: pending, success, failed"
  }
}

Die Input-Definition legt fest, was das Tool erwartet. Die Validierungsschicht prüft, ob die Voraussetzungen erfüllt sind. Erst danach beginnt die eigentliche Ausführung. Das Output-Format bleibt konsistent, egal ob das Tool erfolgreich war oder fehlgeschlagen ist.

Custom Tools in QuantenRam integrieren

Wenn du Custom Tools mit QuantenRam nutzen möchtest, solltest du sie so gestalten, dass sie ueber Standard-Schnittstellen (HTTP, CLI) erreichbar sind. Das erlaubt es Agenten, sie aufzurufen, ohne projektspezifische Details zu kennen. Die Tool-Beschreibung selbst wird in der Konfiguration hinterlegt.

# Integration in oh-my-quantenram Konfiguration
{
  "custom_tools": {
    "lint-project": {
      "command": "./scripts/lint.sh",
      "cwd": "${workspace}",
      "env": {
        "LINT_STRICT": "true"
      }
    },
    "generate-api-docs": {
      "command": "python manage.py generate_api_docs",
      "requires": ["django", "drf"]
    }
  }
}

Agenten können diese Tools dann ueber ihre Namen aufrufen, ohne die genauen Implementierungsdetails zu kennen. Das schafft eine saubere Trennung zwischen Tool-Logik und Agenten-Workflow. Wichtig ist, dass jedes Tool ausreichend dokumentiert ist, damit Agenten verstehen, wann sie es einsetzen sollen.

Best Practices für Custom Tools

Die besten Custom Tools sind diejenigen, die nie ueberraschen. Sie tun genau das, was ihre Beschreibung verspricht, und sie scheitern lautstark, wenn etwas nicht stimmt. Investiere Zeit in gute Fehlermeldungen - sie sind die Schnittstelle zwischen Tool und Mensch, wenn etwas schiefgeht.

Atomicität: Wenn möglich, sollten Tools atomare Operationen ausführen. Entweder gelingt der gesamte Vorgang, oder er wird vollständig rückgängig gemacht.
Idempotenz: Das mehrfache Aufrufen desselben Tools mit denselben Parametern sollte dasselbe Ergebnis liefern. Das macht Tools robust gegen wiederholte Aufrufe.
Logging: Jedes Tool sollte dokumentieren, was es tut. Das erleichtert das Debugging und macht die Wirkung des Tools nachvollziehbar.
Versionierung: Ändere das Verhalten eines Tools nicht unangekündigt. Wenn du Breaking Changes einführst, gib dem Tool eine neue Version.

Custom Tools sind Investitionen in die Wiederverwendbarkeit deiner Arbeitsabläufe. Ein gut gebautes Tool wird von verschiedenen Agenten und Menschen genutzt und zahlt sich durch Zeitersparnis und Qualität aus.