Outils de développement (adk-devtools)

adk-devtools est l’ensemble d’outils de boucle interne dont un agent de codage a besoin — lire, modifier, rechercher et exécuter — avec chaque opération limitée à un répertoire de travail. C’est un crate autonome publiable, ne dépendant que de adk-core, donc il s’intègre avec n’importe quel LlmAgent (le CodingAgent le configure pour vous).

Les outils

DevToolset est un Toolset regroupant six outils :

Deux comportements de sécurité à connaître :

• edit_file nécessite un read_file préalable de ce fichier dans la session, et par défaut la chaîne cible doit apparaître exactement une fois (replace_all pour outrepasser cela). Cela protège contre les écrasements aveugles.
• grep ignore les répertoires de build/VCS courants (target, .git, node_modules, …) ainsi que les fichiers binaires/surdimensionnés.

L’outil bash streame sa sortie stdout/stderr ligne par ligne via ToolContext::emit_progress pendant l’exécution de la commande, afin que les UIs puissent afficher un terminal en direct. Chaque bloc arrive comme un événement partiel sur le EventStream de l’agent (détectez-le avec event.tool_progress_stream()) ; la sortie complète est toujours renvoyée comme résultat final de l’outil. Voir l’ streaming_bash exemple et Streaming Progress from a Tool.

Le Workspace

Un Workspace ancre chaque opération dans un répertoire et applique une petite politique :

use adk_devtools::Workspace;
use std::time::Duration;

let ws = Workspace::new("./my-repo");              // read-write, bash enabled
let ws = Workspace::read_only("./my-repo");        // explore/plan: no writes, no bash
let ws = Workspace::new("./my-repo")
    .allow_bash(false)                              // file edits, but no shell
    .bash_timeout(Duration::from_secs(60))
    .max_output_bytes(512 * 1024);

• Contenance du chemin — tout chemin qui se résout en dehors de la racine est rejeté, donc l’agent ne peut pas lire ou écrire ../../etc/.... La contenance est appliquée au chemin résolu, pas seulement au chemin littéral : un lien symbolique pointant hors de la racine est rejeté même s’il se trouve lexicalement à l’intérieur. Cela couvre un composant final lié par symlink et un répertoire parent lié par symlink, donc la création via un répertoire redirigé est aussi refusée. Un symlink dont la cible reste à l’intérieur de l’espace de travail continue de fonctionner, puisque les dépôts contiennent légitimement des liens internes.

  La vérification n’est pas un verrou. Un symlink placé entre la vérification et l’ouverture suivante serait quand même suivi ; pour fermer cette fenêtre, il faut un parcours relatif aux descripteurs avec les sémantiques no-follow de la plateforme. Considérez les outils de fichiers comme une contenance face à un agent qui erre, et non comme une isolation face à un adversaire qui peut écrire simultanément dans l’espace de travail.

• Mode lecture seule — Workspace::read_only(..) masque entièrement les outils modifiants (le modèle ne voit que read_file/glob/grep).

• L’environnement de bash est vidé — la commande reçoit seulement PATH, HOME, LANG, LC_ALL, TMPDIR, TERM, USER et SHELL, donc les clés API du fournisseur détenues par le processus de l’agent ne sont pas lisibles avec env. Workspace::inherit_env(true) rétablit l’ancien comportement consistant à tout transmettre, et env_allowlist remplace l’ensemble.

• Délai d’attente de bash + limites de sortie — les commandes longues ou bavardes sont bornées. Une commande arrivée au timeout est tuée comme un groupe de processus, donc tout ce qu’elle a lancé est tué aussi ; auparavant seul l’enfant direct était signalé et les descendants survivaient.

L’utiliser directement

Attachez l’ensemble d’outils à n’importe quel agent :

use adk_devtools::{DevToolset, Workspace};
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let agent = LlmAgentBuilder::new("coder")
    .model(model)
    .toolset(Arc::new(DevToolset::new(Workspace::new("./my-repo"))))
    .build()?;

DevToolset n’expose que les outils autorisés par l’espace de travail, donc un espace de travail en lecture seule donne automatiquement un agent en lecture seule.

Modèle de sandboxing

La phase 1 exécute bash localement sur l’hôte (sh -c, répertoire de travail fixé à la racine) avec un délai d’attente et un environnement vidé. Ce que cela vous apporte, et ce que cela ne vous apporte pas :

Il est donc contenu dans le chemin, isolé de l’environnement et borné, mais pas isolé du système d’exploitation. Le vocabulaire de la politique s’aligne sur adk-code et SandboxPolicy ; pour une isolation forte, exécutez bash derrière un exécuteur conteneurisé (voir le design doc). Combinez-le avec adk-guardrail (listes d’autorisations des commandes, redaction des secrets) et adk-auth pour les outils avec jeton (p. ex. GitHub).

Suivant : The harness →