Outils : Vue d’ensemble

Les Outils sont les mains de l’agent. Un outil est une capacité que le modèle peut invoquer en cours de conversation, exécuter une commande shell, récupérer une URL HTTP, ouvrir un navigateur, écrire un fichier ou lire un capteur. Chaque appel d’outil est soumis à la politique de sécurité. Les exécutions réussies peuvent inclure un reçu d’outil lorsque les reçus sont activés.

Les outils ne doivent pas être confondus avec les sous-commandes CLI de zeroclaw. Les commandes CLI sont destinées aux opérateurs ; les outils sont destinés à l’agent.

Un agent obtient ses outils via les bundles de compétences, de connaissances et de MCP qu’il référence ; consultez Agents pour savoir comment les bundles sont attachés à un agent. Pour le chemin au niveau de chaque tour, de l’appel d’outil du fournisseur à l’approbation, au dispatch, à la réception, à l’événement observateur et à l’entrée d’historique, consultez Cycle d’exécution des outils.

Avant d’ajouter un outil intégré ou de remplacer l’un d’eux par une intégration externe, consultez l’Inventaire des outils intégrés pour choisir le cadre le plus sobre et pérenne.

Outils intégrés

Une build minimale comprend :

Toujours enregistrés aux côtés des éléments intégrés :

Enregistré de manière conditionnelle :

Protocoles d’extension

Au-delà des outils intégrés, ZeroClaw prend en charge la surface d’extension MCP (Model Context Protocol). Connectez n’importe quel serveur MCP (le système de fichiers de Claude Code, Playwright, le vôtre) et l’agent récupère ses outils au démarrage.

Pour une intégration côté IDE où un éditeur pilote ZeroClaw en tant que sous-processus, consultez ACP : Agent Client Protocol se trouve sous channels car il s’agit d’une surface entrante de gestion de sessions, et non d’un outil que l’agent invoque.

Création d’un outil

Implémentez le trait Tool dans zeroclaw-api :

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;   // Schéma JSON pour les arguments
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

Chaque Tool est également Attributable, de sorte que les émissions de journaux et les traces d’audit d’un appel d’outil portent la même attribution <kind>.<alias> que celle utilisée par le reste du runtime.

Enregistrez-vous via l’usine d’outils du runtime. Consultez Développement → Protocole des plugins pour le modèle complet.

Décrire des outils au modèle

Les descriptions d’outils sont des chaînes Mozilla Fluent : une par outil, localisée par locale. Cela permet de garder les descriptions d’outils concises dans la fenêtre de contexte du modèle tout en autorisant la localisation de l’interface utilisateur.

Source of truth : crates/zeroclaw-runtime/locales/en/tools.ftl. Les traductions sont générées et maintenues via cargo fluent fill --locale <code> (voir Maintainers → Docs & Translations).

Risques et approbation

Chaque invocation d’outil est classée par niveau de risque :

• Faible (lecture seule, sans effets de bord) : file_read, memory_recall, http_request GET vers les domaines autorisés
• Moyen (modifie l’état local) : file_write, shell avec des commandes connues comme sûres
• Élevé (effets de bord destructeurs ou distants) : shell avec des commandes inconnues, http_request POST vers des URL non restreintes

Le niveau d’autonomie détermine ce que chaque niveau de risque peut faire sans l’approbation de l’opérateur. Par défaut (Supervised) : les exécutions de faible intensité sont autorisées, celles de moyenne intensité demandent une vérification, et celles de haute intensité sont bloquées.

Lorsque les reçus sont activés, les exécutions réussies reçoivent un reçu d’outil. Les appels refusés, bloqués, remplacés, échoués ou interrompus ne reçoivent pas de reçus.

Désactivation des outils sur les canaux non-CLI

Le schéma ne possède pas de champ tools_allow / tools_deny par canal. Le contrôle d’accès aux outils se trouve dans le profil de risque de l’agent ([risk_profiles.<alias>]) :

• excluded_tools supprime les outils répertoriés de chaque canal non-CLI (Discord, Telegram, Bluesky, Matrix, Slack, etc.) tout en laissant l’interface CLI locale intacte. La granularité est binaire (CLI vs non-CLI), et non par canal. Cela soustrait également les éléments de la liste d’autorisation des délégués agentiques résolue au moment de l’exécution, ce qui constitue le seul moyen de bloquer les noms MCP <server>__<tool> individuels qui seraient autrement automatiquement admis par la règle ci-dessous.
• allowed_tools est l’inverse : une liste d’autorisation des outils que l’agent peut appeler en mode agentique (vide ou omis signifie aucune contrainte d’autorisation ; la configuration TOML ne distingue pas les deux cas).
• Exception MCP : lorsque allowed_tools n’est pas vide, les outils MCP découverts au moment de l’exécution (tout nom contenant __, selon la convention <server>__<tool>) sont automatiquement admis dans la liste d’autorisation effective sans avoir à y être répertoriés individuellement. Cela permet de conserver l’utilisation du comportement MCP par défaut postérieur au #7464 pour les agents qui définissent déjà une liste d’autorisation explicite. Pour bloquer des outils MCP individuels, répertoriez-les dans excluded_tools.
• L’exception MCP s’applique uniquement au champ allowed_tools du profil de risque. Les listes d’autorisation par exécution fournies par l’appelant (le allowed_tools d’une tâche cron, les invocations de délégué restreintes, etc.) sont toujours traitées comme des intersections strictes de listes explicites. Une tâche qui se restreint elle-même à allowed_tools = ["cron_add"] n’exposera pas les wrappers MCP découverts au moment de l’exécution qu’elle n’a pas nommés, même lorsque le profil de risque de l’agent les admettrait automatiquement.

Si vous avez besoin d’un contrôle plus fin, abaissez le level du profil à read_only ou supervised et appuyez-vous sur les listes auto_approve / always_ask propres à chaque profil pour soumettre les outils sensibles à l’approbation d’un opérateur.

Consultez Niveaux d’autonomie pour l’ensemble complet des champs par profil.

Voir aussi

• MCP
• Cycle de vie d’exécution des outils
• ACP
• Automatisation du navigateur
• Sécurité → Aperçu