PostToolUse et hooks d’appels sortants

Les invites orientent le modèle, mais elles sont probabilistes — fiables à environ 90 %. Cela convient pour la plupart des comportements. Cependant, certaines actions ne doivent jamais passer : effectuer un remboursement important, supprimer des données de production ou envoyer de l'argent.

Les hooks vous offrent une application 100 % déterministe. Ce sont des instructions qui s'exécutent autour de l'exécution des outils, en dehors du contrôle du modèle. Utilisez-les lorsqu'un échec a des conséquences financières, juridiques ou liées à la sécurité.

Cette leçon couvre deux points d'application :

• PostToolUse — s'exécute après l'exécution d'un outil et intercepte le résultat avant que le modèle ne le voie. Vous pouvez réduire, valider, anonymiser ou remodeler la sortie de l'outil.
• Hooks d'appels sortants — bloquent une action contraire à la politique avant qu'elle ne quitte votre système (par exemple, un remboursement supérieur à un seuil).

Ensemble, ils encadrent la partie dangereuse de la boucle agentique : le moment où le résultat d'un outil entre dans la conversation et celui où un effet secondaire pourrait en sortir.

Rappelez-vous la boucle agentique : envoyer la requête, examiner stop_reason et, lorsqu'il vaut tool_use, exécuter l'outil et ajouter le résultat à l'historique, puis recommencer jusqu'à end_turn.

Un hook PostToolUse enveloppe l'étape « exécuter l'outil ». Le modèle demande un appel d'outil ; votre code l'exécute ; avant d'ajouter le résultat à l'historique des messages, le hook l'examine et peut le modifier.

Une tâche PostToolUse courante et pratique consiste à réduire la sortie de l'outil aux champs pertinents. Les réponses brutes des API sont souvent volumineuses, et un contexte trop chargé provoque le problème de l'information perdue au milieu — les modèles prêtent davantage attention au début et à la fin du contexte qu'à son milieu.

Le hook remodèle le résultat de manière déterministe, afin que le modèle ne voie que les champs importants.

PostToolUse permet également de normaliser les erreurs. Un état générique comme "Operation failed" empêche la récupération — le modèle ne peut pas distinguer un problème temporaire d'un problème d'autorisation.

Remodelez les échecs en erreurs structurées afin que le modèle puisse les orienter intelligemment : un indicateur, une catégorie, la possibilité de réessayer et le contexte.

Voici une règle subtile que PostToolUse aide à faire respecter : un échec d'accès n'est pas la même chose qu'un résultat vide valide.

• Une requête ayant échoué (délai d'attente, authentification) est une erreur que le modèle peut réessayer.
• Un résultat vide (zéro commande correspondante) est une réponse légitime — réessayer ne change rien.

Encodez cette différence afin que le modèle ne gaspille jamais d'itérations à réessayer une requête qui ne trouve simplement aucune correspondance.

Abordons maintenant le cas d'utilisation principal. Le scénario du service client de l'examen comporte un outil process_refund. Règle : les remboursements supérieurs à 500 $ nécessitent l'intervention d'un humain.

Vous pourriez écrire cette règle dans l'invite — mais une invite est fiable à environ 90 %, et un seul remboursement manqué représente une perte financière réelle. Vous enveloppez donc l'appel sortant dans un hook qui bloque l'action de manière déterministe lorsque le seuil est dépassé. Le jugement du modèle n'a ici aucun poids.

Les hooks d'appels sortants imposent également des conditions préalables — des garanties d'ordre qu'une invite ne peut pas fournir de manière fiable. Exemple : ne traitez jamais un remboursement tant que get_customer n'a pas renvoyé une identité vérifiée.

Le hook vérifie un fait dans votre propre état, et non l'affirmation du modèle selon laquelle il aurait « déjà vérifié » l'identité. C'est la différence entre une garantie déterministe et une instruction fondée sur l'espoir.

Le blocage ne représente que la moitié du travail. Un hook qui absorbe silencieusement l'action laisse le modèle dans la confusion et la boucle à l'arrêt — c'est une dissimulation silencieuse, une mauvaise pratique.

Renvoyez plutôt le blocage sous la forme d'un résultat d'outil que le modèle peut lire et traiter. Un bon message de blocage indique la raison et l'étape suivante correcte (ici, escalate_to_human), afin que l'agent récupère proprement dans la même boucle.

Ne confondez pas les hooks d'application avec le filet de sécurité de la boucle. Une limite d'itérations arrête une boucle qui s'emballe, mais il s'agit d'un dispositif de secours — jamais du mécanisme de contrôle principal ni d'un substitut à l'application des règles.

Les hooks sont l'inverse : une garantie précise et intentionnelle concernant une action donnée. Le modèle continue de prendre les décisions ; les hooks réservent le code strict aux seules garanties qui comptent réellement.

Règle de décision pour l'examen et la production :

• Utilisez un hook lorsque l'échec est financier, juridique ou critique pour la sécurité, ou lorsque vous avez besoin d'une condition préalable ou d'un seuil déterministe (remboursement > 500 $, identité vérifiée avant le versement).
• Utilisez une invite pour les conseils souples, le ton et les quelque 90 % de comportements pour lesquels un oubli occasionnel est acceptable.

Hooks = déterministes. Invites = probabilistes. Choisissez l'outil en fonction du coût d'une erreur.

Points essentiels :

• PostToolUse intercepte les résultats des outils avant que le modèle ne les voie — réduisez les sorties verbeuses, normalisez les échecs génériques en erreurs structurées et distinguez l'échec d'accès d'un résultat vide valide.
• Les hooks d'appels sortants bloquent les actions contraires à la politique (remboursement > 500 $) et imposent les conditions préalables (identité vérifiée avant le versement).
• Hooks = 100 % déterministes ; invites = environ 90 % probabilistes. Utilisez des hooks lorsque l'échec est financier, juridique ou critique pour la sécurité.
• Renvoyez toujours un blocage sous la forme d'un résultat structuré — ne le masquez jamais silencieusement. Les limites d'itérations sont un filet de sécurité, pas un mécanisme d'application des règles.