Konfiguration

Eigene Tools fuer projektspezifische Aktionen entwickeln

Custom Tools kapseln Aktionen, die spezifisch fuer 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 verlaesslichen Bausteinen, die sowohl von Menschen als auch von Agenten genutzt werden koennen.

Eingabevalidierung

Jedes Custom Tool muss seine Eingaben strikt validieren. Unklare oder fehlende Parameter sollten zu einem sofortigen Fehler fuehren, nicht zu stillschweigenden Annahmen. Das verhindert, dass das Tool in unerwarteten Zustaenden Daten zerstoert 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 Zustaende enthaelt, muessen diese dokumentiert und bei der Validierung beruecksichtigt werden.

Sicherheitsgrenzen

Sicherheitspruefungen gehoeren ins Tool selbst, nicht in die aufrufende Logik. Ein Tool, das Dateien loescht, sollte intern pruefen, ob die Zieldatei wirklich loeschbar ist. Das verhindert, dass Fehler in der Aufrufkette zu katastrophalen Ergebnissen fuehren.

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 prueft, ob die Voraussetzungen erfuellt sind. Erst danach beginnt die eigentliche Ausfuehrung. 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 moechtest, 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 koennen 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 fuer 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.

Atomicitaet: Wenn moeglich, sollten Tools atomare Operationen ausfuehren. Entweder gelingt der gesamte Vorgang, oder er wird vollstaendig rueckgaengig 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: Aendere das Verhalten eines Tools nicht unangekuendigt. Wenn du Breaking Changes einfuehrst, gib dem Tool eine neue Version.

Custom Tools sind Investitionen in die Wiederverwendbarkeit deiner Arbeitsablaeufe. Ein gut gebautes Tool wird von verschiedenen Agenten und Menschen genutzt und zahlt sich durch Zeitersparnis und Qualitaet aus.