Outils des Agents - Documentation Zileo Chat

Qu'est-ce qu'un outil ?

Un outil (tool) est une fonction exécutable définie par un schéma JSON (OpenAPI 3.0) qu'un agent peut invoquer. Chaque outil implémente le trait Tool avec les méthodes : definition(), execute(), validate_input() et requires_confirmation().

Chaque outil définit des opérations avec des paramètres valides selon son schéma d'entrée. L'agent sélectionne l'opération appropriée, fournit les paramètres requis, et reçoit le résultat structuré pour continuer son exécution.

Architecture des outils

Les modèles de langage génèrent du texte mais ne peuvent pas exécuter d'opérations concrètes. Les outils fournissent cette capacité via un système de validation d'entrées, d'exécution déterministe et de gestion d'erreurs structurées (9 types d'erreurs avec messages d'action corrective).

Outils de base

Ces outils sont disponibles pour tous les agents (principal et sous-agents). Ils couvrent les besoins fondamentaux : mémoire, organisation et calculs.

MemoryTool

Mémoire persistante avec recherche vectorielle

Tous les agents

Système de stockage persistant avec recherche sémantique via embeddings vectoriels (index HNSW 1024 dimensions). La recherche utilise un seuil de similarité configurable (défaut : 0.7) avec fallback automatique vers la recherche textuelle si les embeddings échouent.

Contraintes

Contenu maximum : 50 000 caractères
Résultats par défaut : 10 (maximum : 100)
Scope : workflow (isolé), general (global), ou both (combiné)

user_pref

Préférences et paramètres utilisateur

context

Informations spécifiques au workflow

knowledge

Faits et expertise du domaine

decision

Décisions et justifications

Opérations disponibles (8)

activate_workflow Scope workflow

activate_general Scope global

add Stocker avec embedding

get Récupérer par ID

list Filtrer par type/scope

search Recherche vectorielle

delete Supprimer par ID

clear_by_type Supprimer par type

Exemple d'utilisation

L'agent analyse un projet et stocke les informations clés (architecture, technologies, décisions) via add avec le type knowledge. Lors d'une question ultérieure, search retrouve les informations sémantiquement similaires pour contextualiser la réponse.

TodoTool

Gestion structurée des tâches avec dépendances

Tous les agents

Système de gestion de tâches isolé par workflow. Chaque tâche possède un statut, une priorité (1-5), un agent assigné optionnel, des dépendances vers d'autres tâches, et une durée d'exécution enregistrée à la complétion.

Contraintes

Nom de tâche : max 128 caractères
Description : max 1 000 caractères
Priorité : 1 (critique) à 5 (faible)
Liste par défaut : 1 000 résultats maximum

pending

Tâche non démarrée

in_progress

Tâche en cours d'exécution

completed

Tâche terminée

blocked

Tâche bloquée (dépendance)

Opérations disponibles (6)

create Créer avec priorité/deps

get Récupérer par ID

update_status Modifier le statut

list Filtrer par statut

complete Terminer + duration_ms

delete Supprimer la tâche

Exemple d'utilisation

L'agent décompose une refactorisation en tâches : "Analyser le code" (priorité 1), "Identifier les patterns" (priorité 2, dépendance sur la première), puis met à jour les statuts via update_status et enregistre la durée d'exécution avec complete.

CalculatorTool

Moteur de calcul scientifique

Tous les agents

Outil stateless (sans base de données) fournissant 39 opérations mathématiques précises. Gestion d'erreurs spécifiques : division par zéro, racine de négatif, logarithme de non-positif retournent des messages d'erreur explicites.

Format d'entrée

Unaire : {"operation": "sin", "value": 1.5708}
Binaire : {"operation": "add", "a": 10, "b": 5}
Constante : {"operation": "constant", "name": "pi"}

Opérations disponibles (39)

unary (22) sin, cos, tan, sqrt, ln, exp...

binary (11) add, subtract, multiply, pow...

constant (6) pi, e, tau, sqrt2, ln2, ln10

Trigonométrie

sin, cos, tan, asin, acos, atan, atan2

Hyperbolique

sinh, cosh, tanh

Exponentielles

exp, exp2, ln, log10, pow, log

Utilitaires

abs, floor, ceil, round, min, max

Exemple d'utilisation

Calcul du coût API : 1.5M tokens à 0.002 EUR/1000. L'agent utilise {"operation": "multiply", "a": 1500, "b": 0.002} pour obtenir un résultat structuré {"success": true, "result": 3.0}.

UserQuestionTool

Interaction utilisateur avec circuit breaker

Tous les agents

Permet aux agents de poser des questions à l'utilisateur et d'attendre une réponse. Implémente un circuit breaker qui bloque les questions après 3 timeouts consécutifs (cooldown de 60 secondes) pour éviter le spam lorsque l'utilisateur est absent.

Contraintes

Question : max 2 000 caractères
Options : max 20 (ID: 64 chars, label: 256 chars)
Réponse texte : max 10 000 caractères
Contexte : max 5 000 caractères
Timeout par défaut : 300 secondes (5 min)

checkbox

Sélection parmi options prédéfinies

text

Saisie libre avec placeholder optionnel

mixed

Options + saisie texte combinée

Opérations disponibles (1)

ask Poser une question et attendre

pending

En attente de réponse

answered

Réponse reçue

skipped

Question ignorée par l'utilisateur

timeout

Délai d'attente dépassé

Exemple d'utilisation

L'agent a besoin de clarification sur une tâche. Il utilise ask avec type checkbox pour proposer 3 options. Le polling utilise un backoff progressif (500ms, 1s, 2s, 5s max) pour minimiser la charge serveur.

Outils sous-agents

Outils d'orchestration permettant à l'agent principal de déléguer des tâches. Requièrent un AgentToolContext pour accéder aux dépendances système (Registry, Orchestrator, LLM Manager, MCP Manager, Tool Factory).

Contraintes d'orchestration

Maximum 3 sous-agents par workflow (partage entre Spawn + Delegate + Parallel)
Un seul niveau de hiérarchie (sous-agents sans accès aux outils d'orchestration)
Patron "Prompt In, Report Out" : prompt en entrée, rapport Markdown + métriques en sortie
Pas de partage de contexte, mémoire ou état entre agents
Timeout LLM : 300 secondes (5 min) - Timeout DB : 30 secondes

SpawnAgentTool

Création dynamique de sous-agents temporaires

Agent principal

Crée et exécute un sous-agent temporaire avec configuration personnalisable. Le sous-agent est automatiquement supprimé après exécution. Supporte les tokens d'annulation pour arrêt gracieux et circuit breaker optionnel pour la résilience.

Paramètres de spawn

name : nom du sous-agent (requis)
prompt : tâche complète à exécuter (requis)
system_prompt : instructions personnalisées (optionnel)
tools : outils disponibles (défaut : outils parent sans orchestration)
mcp_servers : serveurs MCP (défaut : serveurs parent)
provider / model : surcharge LLM (optionnel)

Opérations disponibles (3)

spawn Créer et exécuter

list_children Slots actifs/restants

terminate Forcer l'arrêt

Exemple d'utilisation

L'agent principal crée un sous-agent "SecurityAuditor" avec un system prompt spécialisé en sécurité. Le sous-agent retourne un rapport Markdown avec métriques (duration_ms, tokens_input, tokens_output).

DelegateTaskTool

Délégation vers agents permanents existants

Agent principal

Exécute une tâche via un agent permanent préexistant. L'agent cible utilise sa propre configuration (modèle, outils, system prompt). Contrairement à SpawnAgentTool, l'agent n'est pas créé dynamiquement et persiste après exécution.

Restrictions de délégation

Uniquement vers agents permanents (Lifecycle::Permanent)
Auto-délégation interdite (agent ne peut pas se déléguer à lui-même)
Agent temporaires exclus de la liste des cibles
Compte dans la limite de 3 sous-agents par workflow

Opérations disponibles (2)

delegate Exécuter via agent_id + prompt

list_agents Lister agents permanents (sans self)

Exemple d'utilisation

Un agent "db_agent" configuré avec expertise SQL reçoit une délégation pour analyser une requête. L'agent utilise sa configuration propre (modèle, outils) et retourne un rapport structuré via le patron "Prompt In, Report Out".

ParallelTasksTool

Exécution concurrente via JoinSet

Agent principal

Exécute plusieurs tâches simultanément via tokio::task::JoinSet. Le temps total correspond à la tâche la plus longue. Inclut retry avec backoff exponentiel par tâche et monitoring heartbeat pour tâches longues.

Paramètres du batch

tasks : tableau de {agent_id, prompt} (max 3)
wait_all : attendre la fin de toutes les tâches (toujours true)
Validation humaine requise avant exécution (human-in-the-loop)

Opérations disponibles (1)

execute_batch Lancer tâches en parallèle

Résultats individuels

success, report, error, metrics par agent

Rapport agrégé

aggregated_report en Markdown combiné

Exemple d'utilisation

Audit multi-dimension : sécurité (5s), accessibilité (3s), performance (4s) en parallèle. Temps total : 5s (max) au lieu de 12s (somme). Le résultat inclut un taux de réussite (all/some/none completed) et un rapport agrégé consolidant les trois analyses.

Outils MCP (serveurs externes)

MCP (Model Context Protocol) est un protocole JSON-RPC 2.0 sur stdio permettant la connexion à des serveurs d'outils externes. La découverte des outils s'effectue via la méthode tools/list qui retourne les définitions au format JSON Schema (OpenAPI 3.0).

Les agents accèdent aux outils MCP selon leur configuration mcp_servers. L'invocation s'effectue via tools/call avec le nom de l'outil et ses arguments.

Docker Desktop requis

Les serveurs MCP s'exécutent dans des conteneurs Docker pour garantir isolation et sécurité. Installez Docker Desktop avant de configurer des serveurs MCP.

1. Télécharger depuis docker.com 2. Installer et lancer Docker Desktop 3. Vérifier : docker --version

Serveurs MCP

Intégration JSON-RPC 2.0 pour outils externes

Les serveurs MCP exposent des outils via MCPToolDefinition : nom, description (pour sélection LLM), et schéma d'entrée JSON. L'exécution retourne un MCPToolCallResponse contenant du contenu (Text, Image, Resource) et un indicateur d'erreur optionnel.

Contrôle d'accès

Outils exposés uniquement si serveur dans agent.mcp_servers
Validation serveur via MCPManager::validate_server_names()
Noms d'outils invalides rejetés immédiatement
Requêtes paramétrées (pas d'injection SQL/RPC)

tools/list

Découverte des outils disponibles

tools/call

Invocation avec name + arguments

Validation humaine (mise à jour future)

Les outils MCP avec requires_confirmation: true nécessiteront une autorisation explicite avant exécution. Cette fonctionnalité n'est pas encore implémentée et sera ajoutée dans une mise à jour future.

Exemple : Serena (analyse de code)

Le serveur Serena expose des outils comme find_symbol, replace_symbol_body, search_for_pattern. L'agent utilise tools/call avec les arguments requis par le schéma, et reçoit le résultat structuré pour continuer son exécution.