Dateizugriff im lokalen AI-Agent: Tools

Dateizugriff für lokale KI-Agenten: Tools und Fehlerbehebungen

Unser lokaler KI-Agent Doka kann jetzt auf Dateien zugreifen – aber erst nach der Behebung eines kritischen KV-Cache-Fehlers in llama.cpp. Der Systemprompt begann mit Session started: ${new Date().toISOString()}, was sich bei jeder Iteration änderte. Dadurch wurde der gesamte Cache ungültig: Das Modell berechnete 2000 Prompt-Tokens bei 10 Iterationen immer wieder von vorne und verschwendete 20.000 zusätzliche Tokens.

Durch Verschieben des Zeitstamps ans Ende des Prompts oder der Benutzerabfrage wurde der Cache wieder nutzbar. Mehrstufige Aufgaben beschleunigten sich bei Schleifen mit 8+ Iterationen um das 2–3-Fache. Dieses Muster entspricht den Empfehlungen von Anthropic für Claude, ist aber für lokale Modelle ebenso entscheidend.

Sicherer Dateizugriff mit Berechtigungsschranken

Dateilesetools sind unkompliziert, aber Schreibzugriffe brauchen Schutzmechanismen. Jedes Tool in der Toolbox hat eine dangerous-Markierung:

const fileTools: Tool[] = [
  {
    name: 'read_file',
    dangerous: false,
  },
  {
    name: 'write_file',
    dangerous: true,
  },
  {
    name: 'edit_file',
    dangerous: true,
  },
  {
    name: 'delete_file',
    dangerous: true,
  },
];

Bei Aufruf eines gefährlichen Tools erscheint ein Dialog mit den Argumenten: Pfad und Inhalt (erste 500 Zeichen). Der „Zulassen“-Button ist nicht voreingestellt. Ablehnungen liefern dem Agenten einen Fehler zurück:

{
  "error": "Benutzer hat write_file verweigert",
  "canRetry": false,
  "suggestion": "Fragen Sie den Benutzer nach Bestätigung des Pfads"
}

Vollständige Palette an Dateitools

Wir haben sechs Tools implementiert:

• read_file(path: string): string
• write_file(path: string, content: string): void (gefährlich)
• edit_file(path: string, instruction: string): void (gefährlich)
• list_dir(path: string): FileEntry[]
• move_file(from: string, to: string): void (gefährlich)
• delete_file(path: string): void (gefährlich)

edit_file wendet einen Patch basierend auf der Anweisung an (lesen → patchen → schreiben → prüfen) und vermeidet so die Weitergabe großer Dateien über den Kontext.

Behebung von Pfadbezogenen Fehlern

Der Agent verwechselte Dateien mit gleichem Namen in verschiedenen Verzeichnissen durch relative Pfade. Die Lösung:

• Standardarbeitsverzeichnis im Systemprompt festgelegt.
• Pfadvalidierung: Ausgehen der Grenzen löst einen Fehler aus.
• Anweisung: Bei mehrdeutigen Pfaden nachfragen.

Der Fehler trat in Tests 3–4 auf: Der Agent griff auf notes.md im Root zu statt im Zielordner.

Nach write_file oder edit_file kommt eine Auto-Überprüfung: automatisches read_file. Das fügt einen Schritt hinzu, verhindert aber stille Fehlschläge (Berechtigungen, Festplattenprobleme). MAX_TOOL_STEPS auf 12 erhöht für Plan + Lesen + Schreiben + Prüfen.

Agenten-Zeitstrahl für Transparenz

Benutzer bemängelten die „Blackbox“: Drei Minuten Warten ohne Einblick in die Schritte. Wir haben ein Seitenleisten-Log hinzugefügt:

• Tool-Aufrufe mit Argumenten.
• Ergebnisse.
• Zeitstempel.

Event-Streams (tool_call_start / tool_call_end) werden in React in Echtzeit gerendert. Unverzichtbar für Dateizugriff: Benutzer sehen exakte Pfade und Operationen.

Strukturierte Fehler und Wiederholungslogik

Früher spuckten Fehler Node.js-Stacktraces aus, was zu Endlosschleifen oder Halluzinationen führte. Jetzt sind sie strukturiert:

{
  "error": "Datei nicht gefunden: /path/to/file.md",
  "canRetry": false,
  "suggestion": "Überprüfen Sie mit list_dir, ob der Pfad korrekt ist"
}

canRetry vermeidet sinnlose Schleifen. True bei Netzwerk-Timeouts, false bei nicht existierenden Dateien.

Umstrukturierter Systemprompt

Der Systemprompt ist nun gegliedert:

• Rolle und Grenzen: Fähigkeiten und Limits.
• Priorisierte Regeln: Sicherheit > Genauigkeit > Geschwindigkeit.
• Antwortformat: Struktur für verschiedene Typen.
• Few-shot-Beispiel: Denken über Edge-Case.

Diese Struktur reduziert Halluzinationen in langen Ketten, besonders bei regelbasierten Ablehnungen.

Planungsphase: Denken → Planen → Handeln

Anweisung vor Tools:

Bevor Sie Tools nutzen, schreiben Sie einen kurzen Plan:
DENKEN: [Welche Infos brauche ich?]
PLANEN: [Schritt 1 → Schritt 2 → Schritt 3]
HANDELN: [Plan ausführen]

Halbiert redundante Tool-Aufrufe. Erzwingt Zielsetzung vor der Aktion.

Wichtige Erkenntnisse

• Dynamische Daten (Zeitstempel) ans Prompt-Ende verschieben beschleunigt Schleifen um das 2–3-Fache durch KV-Cache.
• Berechtigungsschranken mit Dialogen und strukturierten Fehlern minimieren Schreibrisiken.
• Auto-Überprüchung und Pfadvalidierung eliminieren stille Dateifehler.
• Agenten-Zeitstrahl schafft Vertrauen durch Schritttransparenz beim Dateizugriff.
• Strukturierte Prompts mit Planung steigern Zuverlässigkeit bei mehrstufigen Aufgaben.

— Editorial Team