Laisser un outil agir sur les vraies valeurs

En bref

• Un agent appelle des outils, par exemple pour envoyer un e-mail. Le modèle ne connaît que les jetons et les écrit dans l'appel.
• Par défaut, piighost remet les vraies valeurs dans les arguments juste avant l'exécution, puis masque le résultat de l'outil avant que le modèle le lise.
• Le résultat de l'outil passe par le repérage complet, donc une adresse que la conversation n'a jamais citée est masquée aussi.
• Trois autres réglages existent. Deux d'entre eux laissent le résultat partir en clair vers le modèle.
• Un jeton inventé par le modèle dans un argument bloque l'appel par défaut. L'outil ne s'exécute pas.

Besoins couverts, décrits dans Besoins par profil :

• Responsable conformité : DPO-1 DPO-1 Besoins par profil En tant que DPO, je veux qu'aucune donnée personnelle ni aucun secret ne parte en clair vers le LLM, afin de rester conforme au RGPD et de ne pas exposer d'identifiants d'accès.
• Développeur : DEV-4 DEV-4 Besoins par profil En tant que développeur, je veux que mes outils reçoivent les vraies valeurs alors que le LLM ne voit que des jetons, afin que les actions s'exécutent., DEV-8 DEV-8 Besoins par profil En tant que développeur, je veux décider quoi faire d'un jeton que le LLM a inventé, afin qu'il n'arrive pas tel quel à l'utilisateur.
• Utilisateur de l'application : USER-3 USER-3 Besoins par profil En tant qu'utilisateur, je veux que les actions de l'assistant utilisent mes vraies données, afin que l'e-mail parte à la bonne adresse.

Les termes sont définis dans le glossaire. Le branchement de piighost sur un agent est décrit dans Brancher la protection sur un agent et ses outils.

Pour le métier

piighost n'a pas d'écran. Le réglage d'outil se choisit dans le code de l'agent, pour tout l'agent. Ce que vous pouvez constater, c'est ce que reçoit l'outil et ce que lit le modèle.

Qui intervient

Le trajet d'un appel d'outil

Exemple : la conversation contient déjà « Écrivez à Jean Dupont, jean.dupont@exemple.fr ». Le modèle l'a lu sous la forme « Écrivez à <<PERSON:1>>, <<EMAIL:1>> ».

L'adresse connue reprend son jeton. L'adresse nouvelle prend le numéro suivant. L'e-mail est parti à la bonne adresse.

Comment vérifier : dans une trace de l'agent, l'argument reçu par l'outil porte la vraie adresse, et le message suivant envoyé au modèle ne contient aucune adresse en clair.

Choisir le réglage d'outil

Règles à connaître

BR-TOOL-01 BR-TOOL-01 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Complet », alors les arguments sont restaurés avant l'outil et son résultat est masqué avant le modèle.. Quand le réglage est « Complet », alors les arguments sont restaurés avant l'outil et son résultat est masqué avant le modèle. 1 emplacement · 4 tests directs

BR-TOOL-02 BR-TOOL-02 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Entrée seule », alors les arguments sont restaurés et le résultat part au modèle tel que l'outil l'a renvoyé.. Quand le réglage est « Entrée seule », alors les arguments sont restaurés et le résultat part au modèle tel que l'outil l'a renvoyé. 1 emplacement · 4 tests directs

BR-TOOL-03 BR-TOOL-03 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Sortie seule », alors l'outil reçoit les jetons et son résultat est masqué.. Quand le réglage est « Sortie seule », alors l'outil reçoit les jetons et son résultat est masqué. Par exemple, l'outil d'envoi reçoit <<EMAIL:1>> et enverrait l'e-mail à une adresse qui n'existe pas. 1 emplacement · 4 tests directs

BR-TOOL-04 BR-TOOL-04 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Aucun », alors piighost ne touche ni aux arguments ni au résultat.. Quand le réglage est « Aucun », alors piighost ne touche ni aux arguments ni au résultat. 1 emplacement · 4 tests directs

BR-TOOL-05 BR-TOOL-05 Laisser un outil agir sur les vraies valeurs Quand le résultat d'un outil est masqué, alors il passe par le repérage complet de la conversation.. Quand le résultat d'un outil est masqué, alors il passe par le repérage complet de la conversation. Une valeur connue reprend son jeton, une valeur nouvelle prend le numéro suivant. 2 emplacements · 11 tests directs

BR-TOOL-06 BR-TOOL-06 Laisser un outil agir sur les vraies valeurs Quand une valeur apparaît d'abord dans le résultat d'un outil, alors elle compte comme une valeur de l'utilisateur et reste masquée dans la suite de la conversation.. Quand une valeur apparaît d'abord dans le résultat d'un outil, alors elle compte comme une valeur de l'utilisateur et reste masquée dans la suite de la conversation. 2 emplacements · 11 tests directs

BR-TOOL-07 BR-TOOL-07 Laisser un outil agir sur les vraies valeurs Quand le modèle écrit dans un argument un jeton jamais émis, alors l'appel est refusé par défaut, avant l'exécution, avec le message Deanonymized text holds tokens the pipeline never issued: ['<<EMAIL:7>>'].. Quand le modèle écrit dans un argument un jeton jamais émis, alors l'appel est refusé par défaut, avant l'exécution, avec le message Deanonymized text holds tokens the pipeline never issued: ['<<EMAIL:7>>']. Aucun e-mail ne part. Avec le réglage de jeton inventé « retirer », l'outil reçoit {"to": ""}. Avec « garder », il reçoit {"to": "<<EMAIL:7>>"}. 2 emplacements

BR-TOOL-08 BR-TOOL-08 Laisser un outil agir sur les vraies valeurs Quand les arguments contiennent des listes ou des objets imbriqués, alors chaque texte qu'ils contiennent est restauré, et les autres valeurs (nombres, booléens) restent intactes.. Quand les arguments contiennent des listes ou des objets imbriqués, alors chaque texte qu'ils contiennent est restauré, et les autres valeurs (nombres, booléens) restent intactes. 1 emplacement

BR-TOOL-09 BR-TOOL-09 Laisser un outil agir sur les vraies valeurs Quand le modèle écrit lui-même une valeur en clair dans un argument, alors l'intégration LangChain masque à nouveau l'historique avant l'appel suivant.. Quand le modèle écrit lui-même une valeur en clair dans un argument, alors l'intégration LangChain masque à nouveau l'historique avant l'appel suivant. Une valeur connue reprend son jeton. Une valeur que le modèle a apportée lui-même reste en clair, comme toute valeur citée d'abord par l'assistant. 2 emplacements · 4 tests directs

BR-TOOL-10 BR-TOOL-10 Laisser un outil agir sur les vraies valeurs Quand l'agent garde son historique, alors l'appel d'outil y reste écrit avec ses jetons.. Quand l'agent garde son historique, alors l'appel d'outil y reste écrit avec ses jetons. Les vraies valeurs n'existent que pendant l'exécution de l'outil. 1 emplacement · 4 tests directs

Cette règle ne vaut que pour l'appel d'outil. Le texte des messages de l'utilisateur et du modèle est enregistré dans l'historique avec les vraies valeurs, voir les pièges de l'intégration.

BR-TOOL-11 BR-TOOL-11 Laisser un outil agir sur les vraies valeurs Quand le modèle coupe ou reformule un jeton dans un argument, alors seul un jeton écrit en entier est restauré.. Quand le modèle coupe ou reformule un jeton dans un argument, alors seul un jeton écrit en entier est restauré. L'outil reçoit le reste tel quel. 2 emplacements · 8 tests directs

Ce que voit l'utilisateur final

L'utilisateur voit le résultat de l'action. L'e-mail arrive à la bonne adresse, le dossier cherché est le bon. La réponse finale du modèle est restaurée comme décrit dans Suivre une conversation et restaurer la réponse.

Questions fréquentes

Un outil a reçu <<EMAIL:1>> au lieu de l'adresse. Le réglage d'outil est « Sortie seule » ou « Aucun » (BR-TOOL-03 BR-TOOL-03 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Sortie seule », alors l'outil reçoit les jetons et son résultat est masqué., BR-TOOL-04 BR-TOOL-04 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Aucun », alors piighost ne touche ni aux arguments ni au résultat.). Passez-le à « Complet » si l'outil doit agir sur la vraie adresse.

L'appel d'outil s'arrête avec Deanonymized text holds tokens the pipeline never issued. Le modèle a écrit un jeton inconnu dans un argument (BR-TOOL-07 BR-TOOL-07 Laisser un outil agir sur les vraies valeurs Quand le modèle écrit dans un argument un jeton jamais émis, alors l'appel est refusé par défaut, avant l'exécution, avec le message Deanonymized text holds tokens the pipeline never issued: ['<<EMAIL:7>>'].). Gardez le refus, parce qu'il évite un e-mail envoyé à une adresse inventée.

Le résultat d'un outil est parti en clair vers le modèle. Le réglage est « Entrée seule » ou « Aucun » (BR-TOOL-02 BR-TOOL-02 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Entrée seule », alors les arguments sont restaurés et le résultat part au modèle tel que l'outil l'a renvoyé., BR-TOOL-04 BR-TOOL-04 Laisser un outil agir sur les vraies valeurs Quand le réglage est « Aucun », alors piighost ne touche ni aux arguments ni au résultat.).

Un outil reçoit un jeton derrière le proxy OpenAI. Le proxy du serveur piighost-api ne restaure pas les arguments d'outil d'une réponse diffusée au fil de l'eau. C'est une limite connue (USER-3 USER-3 Besoins par profil En tant qu'utilisateur, je veux que les actions de l'assistant utilisent mes vraies données, afin que l'e-mail parte à la bonne adresse.).

Pour les développeurs

Le guide technique décrit les réglages d'outil dans Stratégies d'appel outil.

Où vivent les règles

from piighost.integrations.langchain import (
    InventedPlaceholderStrategy,
    PIIAnonymizationMiddleware,
    ToolCallStrategy,
)

middleware = PIIAnonymizationMiddleware(
    pipeline,
    tool_strategy=ToolCallStrategy.FULL,
    invented_strategy=InventedPlaceholderStrategy.RAISE,
)

Pièges

• Pydantic AI diffère de LangChain sur deux points. pii_hooks masque aussi un résultat structuré (dictionnaire, liste), et ne masque pas à nouveau les arguments des appels d'outil de l'historique (BR-TOOL-09 BR-TOOL-09 Laisser un outil agir sur les vraies valeurs Quand le modèle écrit lui-même une valeur en clair dans un argument, alors l'intégration LangChain masque à nouveau l'historique avant l'appel suivant.).
• LangChain ne masque que le texte d'un résultat. Les blocs non textuels d'un ToolMessage passent tels quels.
• assistant_strategy=EntityCreateByAssistantStrategy.IGNORE désactive BR-TOOL-09 BR-TOOL-09 Laisser un outil agir sur les vraies valeurs Quand le modèle écrit lui-même une valeur en clair dans un argument, alors l'intégration LangChain masque à nouveau l'historique avant l'appel suivant..
• Le middleware exige un pipeline dont la fabrique expose un recognizer, sinon il lève UnrecognizableFactoryError à la construction.
• Le refus d'un jeton inventé lève InventedPlaceholderError depuis awrap_tool_call. L'outil n'est pas appelé, et l'erreur remonte à l'agent.

Tests