Concevoir un Agent Tool
Un Tool est une capacité agent-facing curatée. Il doit être facile à sélectionner correctement, strictement validé et assez borné pour qu’un modèle ne puisse pas élargir son autorité en jouant sur les arguments.
Quand introduire un Tool
Un endpoint, un node ou une fonction réutilisable n’implique jamais automatiquement un Tool.
- la tâche Agent représentative est identifiée ;
- l’autorité nécessaire est légitime et déclarable ;
- l’intention est distincte des Tools voisins ;
- la granularité réduit du plumbing sans cacher un workflow ;
- la valeur peut être évaluée sur des tâches complètes.
Évitez les Tools universels du type manage_resource qui combinent arbitrairement type d’objet, opération et champs. Réduire le nombre de Tools n’est pas un objectif si cela augmente l’ambiguïté.
Qui contrôle les paramètres ?
Chaque paramètre déclaré doit appartenir explicitement à un contrôleur :
| Contrôle | Usage | Exemples |
|---|---|---|
model | Choix métier réellement délégué au modèle et validable par le Tool. | Sujet d’un email, critères de recherche bornés, motif métier. |
designer | Valeur choisie ou verrouillée par le designer, non modifiable par le modèle. | Configuration d’extension, compte d’envoi, ressource gouvernée. |
Le contexte runtime fiable — marchand, credentials, identité d’exécution, snapshot d’autorité — ne doit pas être ajouté comme pseudo-paramètre contrôlable. Il est fourni hors de la surface d’arguments du Tool.
Une configuration provider est designer-only par défaut : elle sélectionne credentials, identité du fournisseur et frontière de disclosure.
Observations et complétude
- choisissez les outputs pour la prochaine décision de l’Agent, pas pour refléter un payload provider complet ;
- ne nommez jamais une projection partielle
platform.*; - bornez nombre de résultats, profondeur, texte et plage de recherche ;
- signalez explicitement une réponse partielle et son mécanisme de continuation ;
- préservez classification et provenance lors des résumés, joins ou flattenings.
Un résultat vide, un champ optionnel absent, une section indisponible et un échec sont quatre situations différentes. Le contrat doit les distinguer.
Mutations et répétition
Préférez un engagement métier identifiable par Tool mutatif. Ne cachez pas plusieurs effets indépendants derrière un appel « pratique » sauf si l’opération composite possède un véritable contrat métier.
Un Agent peut rappeler un Tool. L’idempotence doit provenir du service canonique, d’une identité d’opération ou du protocole partenaire ; ne simulez pas un exactly-once en mémorisant seulement le hash des arguments.
Après une erreur de transport sur une mutation, l’état peut être incertain. Fournissez un chemin de lecture/réconciliation plutôt que de conseiller un retry aveugle.
Lifecycle du catalogue
Les Tools fournis par une extension utilisent <extension_key>.<snake_case> et le préfixe correspond exactement à metadata.name du manifeste. Une extension ne peut pas prendre l’identité réservée ormuz, utilisée par les exécutables Core de plateforme. Un Tool peut partager un comportement sous-jacent avec un node sans dépendre de son identité ni être créé automatiquement par symétrie.
Modifier arguments, outputs, effets ou risk_level constitue un changement de contrat. Les activités existantes ne doivent pas être silencieusement retargetées vers une capacité plus large.