Accès aux fichiers dans l'agent IA local : outils

Accès aux fichiers pour agents IA locaux : Outils et correctifs

Notre agent IA local, Doka, dispose désormais d'un accès aux fichiers, mais pas sans avoir corrigé un bug critique du cache KV dans llama.cpp. L'invite système commençait par Session started: ${new Date().toISOString()}, ce qui changeait à chaque itération. Cela invalidait tout le cache : le modèle recalculait 2000 jetons d'invite à partir de zéro sur 10 itérations, gaspillant 20 000 jetons supplémentaires.

Déplacer l'horodatage à la fin de l'invite ou du tour utilisateur a restauré le cache. Les tâches multi-étapes se sont accélérées de 2 à 3 fois sur des boucles de 8+ itérations. Ce schéma rejoint les recommandations d'Anthropic pour Claude, mais il est crucial pour les modèles locaux aussi.

Accès sécurisé aux fichiers avec des portes de permission

Les outils de lecture de fichiers sont simples, mais l'écriture nécessite des garde-fous. Chaque outil de la boîte à outils possède un drapeau dangerous :

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

Lorsqu'un outil dangereux est appelé, une boîte de dialogue s'affiche avec les arguments : chemin et contenu (premiers 500 caractères). Le bouton « Autoriser » n'est pas par défaut. Les refus renvoient une erreur à l'agent :

{
  "error": "L'utilisateur a refusé la permission pour write_file",
  "canRetry": false,
  "suggestion": "Demandez à l'utilisateur de confirmer le chemin du fichier visé"
}

Suite complète d'outils pour fichiers

Nous avons implémenté six outils :

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

edit_file applique un patch basé sur l'instruction (lire → patch → écrire → vérifier), évitant de faire passer de gros fichiers par le contexte.

Correction des erreurs liées aux chemins

L'agent confondait les fichiers de même nom dans différents répertoires à cause des chemins relatifs. La correction :

• Répertoire de travail par défaut spécifié dans l'invite système.
• Validation des chemins : sortir des limites déclenche une erreur.
• Instruction : demander à l'utilisateur si les chemins sont ambigus.

Le bug apparaissait aux tests 3-4 : l'agent choisissait notes.md à la racine au lieu du dossier cible.

Après write_file ou edit_file, nous avons ajouté une vérification automatique : un read_file automatique. Cela ajoute une étape mais évite les échecs silencieux (permissions, problèmes disque). MAX_TOOL_STEPS porté à 12 pour plan + lecture + écriture + vérification.

Chronologie de l'agent pour la transparence

Les utilisateurs se plaignaient du « boîte noire » : trois minutes d'attente sans visibilité sur les étapes. Nous avons ajouté une barre latérale de journal :

• Appels d'outils avec arguments.
• Résultats.
• Horodatages.

Les flux d'événements (tool_call_start / tool_call_end) s'affichent en temps réel en React. Indispensable pour l'accès fichiers : les utilisateurs voient les chemins exacts et opérations.

Erreurs structurées et logique de retry

Auparavant, les erreurs déversaient des traces de pile Node.js, menant à des retries infinis ou hallucinations. Désormais, elles sont structurées :

{
  "error": "Fichier non trouvé : /path/to/file.md",
  "canRetry": false,
  "suggestion": "Vérifiez si le chemin est correct avec list_dir d'abord"
}

canRetry réduit les boucles inutiles. Vrai pour timeouts réseau, faux pour fichiers inexistants.

Invite système restructurée

L'invite système est maintenant sectionnée :

• Rôle et limites : Capacités et restrictions.
• Règles prioritaires : Sécurité > précision > vitesse.
• Format de réponse : Structure pour différents types.
• Exemple few-shot : Raisonnement sur un cas limite.

Cette structure réduit les hallucinations dans les chaînes longues, surtout les refus basés sur règles.

Phase de planification : Penser → Planifier → Agir

Instruction avant outils :

Avant d'utiliser les outils, rédigez un court plan :
PENSER : [quelles infos ai-je besoin ?]
PLAN : [étape 1 → étape 2 → étape 3]
AGIR : [exécuter le plan]

Cela divise par deux les appels d'outils redondants. Force la définition d'objectifs avant action.

Points clés

• Déplacer les données dynamiques (horodatages) à la fin de l'invite accélère les boucles de 2-3x via le cache KV.
• Portes de permission avec dialogues et erreurs structurées minimisent les risques d'écriture.
• Vérification auto et validation des chemins éliminent les échecs silencieux des opérations fichiers.
• Chronologie de l'agent renforce la confiance via la transparence des étapes pour l'accès fichiers.
• Invites structurées avec planification boostent la fiabilité sur tâches multi-étapes.

— Editorial Team