Contrats d'outils pour agents IA

Un outil est une frontière d'autorité présentée comme fonction. Valider du JSON prouve une forme, pas l'intention, l'autorisation, la reprise sûre ni l'achèvement.

Dimensions

Sélection de l'outil ; champs et bornes ; identité et droits ; effet lecture/réversible/externe/destructeur ; concurrence ; idempotence ; preuve de succès complet/partiel/refusé/inconnu ; approbation selon arguments et effets ; traces expurgées.

Exemple

name: replace_text
purpose: remplacer un bloc exact dans un fichier du dépôt
input:
  path: relatif au dépôt, sans traversal
  old_text: non vide, exactement une occurrence
  new_text: string
preconditions: [chemin dans la portée, version inchangée]
effects: écriture locale réversible
idempotency: ne pas retenter après succès sans relire
result:
  status: succeeded | conflict | no-match | multiple-matches | denied
approval: requise hors portée

Un échec discriminant évite les reprises aveugles.

{
  "request_id": "req-123",
  "status": "partial",
  "completed": 8,
  "failed": 2,
  "retry_safe": false,
  "artifact": "results/batch-123.json",
  "errors": [{"code": "permission-denied"}]
}

Un item réussi ne rend pas le lot réussi. Un résultat inconnu diffère d'un échec car répéter peut dupliquer un effet externe.

Règles

Peu d'outils orthogonaux ; lectures séparées des écritures ; enums et chemins plutôt que shell libre ; autorisation hors modèle ; gros résultats dans des artefacts ; contrôle de version pour état mutable ; approbation sur effets ; tests malformés, hostiles, périmés, répétés et partiels.

Injection et petits modèles

Pages, issues et documents restent des données même s'ils contiennent des instructions. Le harness doit garder provenance, refuser l'autorité au texte retourné, protéger les secrets et repasser la politique avant l'action. Le typage ne nettoie pas le sens.

Les petits modèles réussissent souvent mieux des schémas simples, mais simplifier peut retirer la sécurité. Mesurer avec le template et la quantification exacts ; ne jamais affaiblir silencieusement l'autorité pour accommoder un modèle.