Une ability mal décrite trompait systématiquement l’agent qui l’appelait

L’ability gerer_stock, enregistrée sur un site e-commerce pour permettre à un agent d’ajuster une quantité en stock, était appelée par l’agent dans des situations où ce n’était clairement pas l’action attendue : une simple question du type « ce produit est-il disponible ? » déclenchait parfois un appel de cette ability en écriture, avec une quantité recalculée arbitrairement, plutôt qu’une simple consultation.

Ce texte ne revient pas sur l’Abilities API en général, déjà traitée ailleurs sur ce blog : il détaille précisément comment une description ambiguë a conduit à ce comportement, et la méthode suivie pour rédiger des descriptions qui ne laissent plus place à ce type de supposition erronée du modèle.

La description initiale, en apparence raisonnable

L’ability était enregistrée avec une description courte, qui semblait suffisante au moment de l’écriture : « Gère le stock d’un produit ». Cette phrase ne précisait ni si l’ability se limitait à la lecture, ni si elle modifiait systématiquement une valeur, ni quel paramètre était requis pour distinguer une simple consultation d’un ajustement réel.

wp_register_ability( 'agence/gerer-stock', array(
    'label'         => 'Gérer le stock',
    'description'   => 'Gère le stock d\'un produit.',
    'input_schema'  => array(
        'type'       => 'object',
        'properties' => array(
            'product_id'      => array( 'type' => 'integer' ),
            'nouvelle_valeur' => array( 'type' => 'integer' ),
        ),
        'required'   => array( 'product_id' ),
    ),
    'execute_callback' => 'agence_gerer_stock_callback',
) );

Pourquoi le modèle a mal interprété l’ability

Face à une question de consultation simple, sans ability de lecture seule clairement distincte disponible, le modèle a interprété la présence de gerer_stock comme l’outil le plus proche du besoin exprimé, et a comblé l’absence de valeur pour nouvelle_valeur en récupérant lui-même une estimation, plutôt que de renvoyer une erreur ou de poser une question de clarification. Le paramètre étant marqué comme non obligatoire dans le schéma, rien n’empêchait techniquement cet appel.

Le problème ne venait donc pas d’une faute technique du modèle, mais d’une ability dont le nom et la description laissaient penser qu’elle pouvait aussi bien servir à consulter qu’à modifier, sans que rien dans sa déclaration ne l’interdise explicitement.

La méthode de correction

La correction a porté sur trois axes distincts, appliqués systématiquement à toutes les abilities du site après cet incident, pas seulement à celle en cause :

1. Séparer strictement lecture et écriture : une nouvelle ability consulter_stock, en lecture seule, a été créée séparément, avec un nom qui ne laisse aucune ambiguïté sur son effet.
2. Rendre les paramètres d’écriture réellement obligatoires : nouvelle_valeur est passé en paramètre requis pour l’ability d’ajustement, empêchant tout appel sans valeur explicite.
3. Enrichir la description avec un exemple d’usage concret et un cas de non-usage explicite, pas seulement une phrase générique.

wp_register_ability( 'agence/ajuster-stock', array(
    'label'       => 'Ajuster le stock d\'un produit',
    'description' => 'Modifie la quantité en stock d\'un produit à une valeur précise et connue. '
        . 'À utiliser uniquement quand une nouvelle valeur exacte est fournie explicitement par l\'utilisateur. '
        . 'Ne pas utiliser pour simplement consulter le stock disponible : utiliser consulter_stock pour cela.',
    'input_schema' => array(
        'type'       => 'object',
        'properties' => array(
            'product_id'      => array( 'type' => 'integer' ),
            'nouvelle_valeur' => array( 'type' => 'integer', 'description' => 'Valeur exacte souhaitée, obligatoire' ),
        ),
        'required'   => array( 'product_id', 'nouvelle_valeur' ),
    ),
    'execute_callback' => 'agence_ajuster_stock_callback',
) );

Ce que cet incident a changé dans nos pratiques

Depuis, chaque nouvelle ability enregistrée passe par une relecture qui vérifie explicitement deux points : que son nom seul ne prête à aucune confusion avec une autre ability existante, et que sa description mentionne, quand c’est pertinent, ce qu’elle ne fait pas, pas seulement ce qu’elle fait.

Une description qui dit ce que fait une ability sans dire ce qu’elle ne fait pas laisse au modèle la liberté de deviner la frontière. Cette liberté finit toujours, tôt ou tard, par être mal exercée.

En résumé

Une ability mal décrite ne provoque pas nécessairement une erreur technique visible : elle peut simplement pousser l’agent à faire un choix d’outil inapproprié, silencieusement, sans qu’aucun message d’erreur ne signale le problème. Séparer strictement les abilities de lecture et d’écriture, rendre obligatoires les paramètres qui déterminent une action réelle, et préciser explicitement ce qu’une ability ne fait pas restent, à ce jour, les trois réflexes les plus efficaces pour éviter ce type d’incident.