Tutoriel : Créer et gérer des hooks dans le portail

Dans ce tutoriel, vous créez deux hooks de gouvernance à l’aide du portail : un hook Stop qui applique le formatage des données (tables markdown avec des en-têtes en gras) et un hook PostToolUse qui bloque les commandes d’interpréteur de commandes dangereuses. Vous configurez des hooks au niveau de l’agent (s’applique à tous les threads et sous-éléments) et au niveau sous-agent (s’applique à un sous-groupe spécifique).

Durée estimée : 10 minutes

Dans ce tutoriel, vous allez apprendre à :

Prerequisites

• Agent Azure SRE en cours d’exécution
• Rôle contributeur ou supérieur sur la ressource Agent SRE

Comprendre où se trouvent les hooks dans le portail

Les crochets fonctionnent à deux niveaux. Comprendre cette distinction est un concept architectural clé.

Créer des hooks au niveau de l’agent

Les hooks au niveau de l’agent s’appliquent à l’ensemble de l’agent, y compris à chaque thread et à chaque sous-agent. Ils ont des modes d’activation qui contrôlent quand ils sont actifs.

Ouvrir la page Hooks

Suivez ces étapes pour accéder à la page Hooks.

1. Accédez à sre.azure.com et sélectionnez votre agent.
2. Dans la barre latérale, développez Générateur.
3. Sélectionnez Hooks.

Vous voyez le titre Hooks avec une description, un bouton Créer un crochet et une grille de données vide (ou une liste de crochets existants).

Créer un crochet d’arrêt

Un hook Stop se déclenche lorsque l’agent est sur le point de retourner une réponse finale. Utilisez-la pour valider la qualité de la réponse et appliquer des règles de mise en forme.

1. Sélectionnez Créer un hook.

2. Renseignez les champs du formulaire :

   Champ	Valeur
   Nom	require-table-format
   Type d’événement	Arrêter
   Mode d’activation	Toujours
   Description	Garantit que les réponses présentent des données structurées sous forme de tables Markdown avec des en-têtes gras

3. Sous Définition de hook, laissez Type de hook défini sur Prompt.

4. Conservez le modèle défini sur Raisonnement rapide (valeur par défaut).

5. Dans l’éditeur Prompt, entrez le texte suivant :

   Check the agent response below.
   
   $ARGUMENTS
   
   Does the response present any structured data (lists of items, comparisons, metrics) as a markdown table with **bold** column headers?
   If no structured data is present, approve.
   If structured data IS present as a table with bold headers: {"ok": true}
   If structured data is present but NOT formatted as a table: {"ok": false, "reason": "Reformat the structured data as a markdown table with **bold** column headers."}
   

6. Laissez le délai d’expiration (s) à 30, le mode d’échec à Allow, et les rejets max à 3.

7. Cliquez sur Enregistrer.

La boîte de dialogue se ferme avec une notification de réussite. Le hook apparaît dans la grille de données avec le type d’événement Stop et Activation Always.

Tester le crochet d’arrêt

Suivez ces étapes pour vérifier que le hook Stop fonctionne correctement.

1. Dans la barre latérale, sélectionnez Chat.
2. Tapez Comparer les avantages et les inconvénients de Python et Go pour générer des microservices , puis sélectionnez Envoyer.
3. Regardez la réponse de l’agent :
   • L’agent répond initialement avec une comparaison de texte brut.
   • Le crochet d’arrêt évalue et rejette la réponse, car les données ne se trouvent pas dans une table.
   • L’agent reformate sa réponse sous la forme d’un tableau markdown avec des en-têtes en gras.

La réponse finale présente la comparaison sous la forme d’une table mise en forme semblable à l’exemple suivant :

Créer un hook PostToolUse

Un hook PostToolUse se déclenche une fois qu’un outil a terminé son exécution. Utilisez-le pour auditer l’utilisation des outils, bloquer les commandes dangereuses ou ajouter un contexte supplémentaire.

1. Revenez à Builder>Hooks.

2. Sélectionnez Créer un hook.

3. Renseignez le formulaire :

   Champ	Valeur
   Nom	block-dangerous-commands
   Type d’événement	Post Tool Use
   Mode d’activation	Toujours
   Description	Bloque rm -rf, sudo et chmod 777 dans les commandes shell
   Type de crochet	Commande
   Composant tool matcher	Bash\|ExecuteShellCommand

4. Sélectionnez Python comme langage de script.

5. Dans l’éditeur de script , entrez le script suivant :

   #!/usr/bin/env python3
   import sys, json, re
   
   context = json.load(sys.stdin)
   command = context.get('tool_input', {}).get('command', '')
   
   dangerous = [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']
   for pattern in dangerous:
       if re.search(pattern, command):
           print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
           sys.exit(0)
   
   print(json.dumps({"decision": "allow"}))
   

6. Définissez le mode Échec sur Bloquer (si le script se bloque, le résultat de l’outil est bloqué).

7. Cliquez sur Enregistrer.

Les deux hooks apparaissent désormais dans la grille de données Hooks.

Tester le hook PostToolUse

Suivez ces étapes pour vérifier que le hook PostToolUse fonctionne correctement.

1. Dans la barre latérale, sélectionnez Chat.
2. Demandez à l’agent d’exécuter une commande sécurisée : « Exécuter echo hello ». Le hook autorise cette commande.
3. Demandez à l’agent d’exécuter une commande dangereuse : « Exécuter rm -rf /tmp/test ». Le hook bloque cette commande.

La commande sécurisée s’exécute normalement. La commande dangereuse est bloquée et l’agent reçoit un message expliquant pourquoi.

Modifier et supprimer des hooks au niveau de l’agent

Vous pouvez modifier ou supprimer des crochets existants de la grille de données Hooks.

• Modifier : sélectionnez l’icône de modification sur n’importe quelle ligne de crochet dans la grille de données, modifiez les champs, puis sélectionnez Enregistrer.
• Supprimer : cochez la case en regard des crochets à supprimer, sélectionnez Supprimer dans la barre d’outils, puis confirmez.

La grille de données reflète immédiatement vos modifications.

Créer des hooks au niveau du sous-agent

Vous configurez les hooks au niveau du sous-agent directement dans la définition du sous-agent. Ils ne s’appliquent que lorsque ce sous-agent spécifique s’exécute, et non à l’agent principal ou à d’autres sous-agents.

Ouvrir le panneau des hooks du sous-agent

Suivez ces étapes pour accéder à la configuration du hook pour un sous-agent spécifique.

1. Dans la barre latérale, développez Générateur et sélectionnez Sous-générateur.
2. Sélectionnez un sous-agent existant pour le modifier, ou sélectionnez Créer pour en démarrer un nouveau.
3. Dans le formulaire du sous-agent, faites défiler la page jusqu’à la section Hooks.
4. Sélectionnez Gérer les hooks.

Un panneau latéral s’ouvre avec les sections Stop et Post Tool Use. Si aucun hook n’est configuré, vous voyez des états vides avec du texte d’aide.

Ajouter un hook à un sous-agent

Les étapes suivantes ajoutent un crochet Stop qui garantit que ce sous-agent répond toujours avec une section récapitulative.

1. Dans le panneau Gérer les crochets , sélectionnez Ajouter un crochet en bas du panneau.

2. Dans la boîte de dialogue, renseignez le formulaire de raccordement :

   Champ	Valeur
   Type d’événement	Arrêter
   Type de crochet	Prompt
   Prompt	Check the response below. $ARGUMENTS Does it include a clear summary section at the end? If yes: {"ok": true} If no: {"ok": false, "reason": "Add a Summary section at the end of your response."}
   Délai d’expiration (s)	30
   Mode d’échec	Permettre
   Nombre maximal de rejets	3

3. Sélectionnez Enregistrer sur le hook.

4. Sélectionnez Créer (ou Enregistrer) sur le sous-agent pour enregistrer la configuration complète.

Le hook apparaît dans le panneau Gérer les hooks dans la section Arrêter. Le formulaire subagent affiche Manage Hooks (1) sur le bouton.

Gérer les hooks par thread

Les hooks au niveau de l’agent avec une activation Always sont actifs par défaut dans chaque conversation. Vous devez activer manuellement les hooks avec une activation On demand pour chaque thread.

Activer/désactiver des crochets dans une conversation

Suivez ces étapes pour activer ou désactiver des hooks dans un thread spécifique.

1. Ouvrez un thread de conversation .
2. Sélectionnez le + bouton dans le pied de page de conversation.
3. Sélectionnez Gérer les hooks.
4. Activer ou désactiver les crochets pour le thread actuel.

Vous pouvez désactiver temporairement les hooks Always . Vous pouvez activer les hooks à la demande si nécessaire. Vous ne pouvez pas activer ou désactiver les hooks système requis.

Les modifications de hook prennent effet immédiatement dans le thread actuel.

Résolution des problèmes

Le tableau suivant répertorie les problèmes courants et les solutions lorsque vous créez et gérez des hooks dans le portail.

Étape suivante

Contenu connexe

• Vue d’ensemble des fonctionnalités de hooks d’agent
• Tutoriel : Configurer des hooks d’agent via l’API REST
• Modes d’exécution