Hooks d’agent dans Azure SRE Agent

Les hooks sont des points de contrôle personnalisés qui interceptent et contrôlent le comportement de l’agent à des moments clés. Utilisez des hooks pour appliquer des contrôles qualité sur les réponses de l’agent, auditer et contrôler l’utilisation des outils, bloquer les opérations dangereuses en appliquant des stratégies, et empêcher une fin de tâche prématurée en validant la sortie de l’agent.

La problématique

Votre agent exécute des tâches de manière autonome : examen des incidents, exécution d’outils et génération de réponses. Mais l’autonomie sans surveillance crée des risques :

Réponses incomplètes : L’agent dit « terminé » avant de traiter tout ce que vous avez demandé.
Utilisation des outils non vérifiés : vous n’avez aucune visibilité sur les outils que l’agent appelle ou les résultats qu’il obtient.
Pas d'application de la politique : les opérations dangereuses (commandes destructrices, modifications non autorisées) ne sont pas contrôlées.
Lacunes de qualité : les réponses ne manquent pas d’informations critiques, car il n’y a pas d’étape de validation.

Vous avez besoin d’un moyen d’intercepter le comportement de l’agent à des moments clés sans le ralentir ou supprimer entièrement son autonomie.

Fonctionnement des hooks d’agent

Les hooks sont des points de contrôle personnalisés que vous attachez à des événements spécifiques de l’agent. Lorsqu’un événement se déclenche, votre hook évalue la situation et décide d’autoriser ou de bloquer l’action.

Agent about to stop → Stop hook evaluates response → Allow or reject
Agent uses a tool   → PostToolUse hook checks result → Allow, block, or inject context

Deux événements de hook sont actuellement pris en charge :

Événement	Se déclenche lorsque	Ce que vous pouvez faire
Arrêter	L’agent est sur le point de retourner une réponse finale	Valider l’exhaustivité, rejeter et forcer l’agent à continuer
PostToolUse	Un outil a terminé son exécution avec succès.	Auditer l’utilisation, bloquer les résultats, injecter un contexte supplémentaire

Deux niveaux de crochets

Les crochets fonctionnent à deux niveaux :

Niveau	Où configurer	Étendue
Niveau de l’agent	Builder → Hooks dans le portail	S’applique à l’ensemble de l’agent, y compris tous les threads et tout agent personnalisé
Niveau d’agent personnalisé	Canevas de l’agent → agent personnalisé → Gérer les hooks ou via l’API REST v2	S’applique uniquement lorsque cet agent personnalisé spécifique s’exécute

Les deux niveaux peuvent coexister. Si un hook de niveau agent et un hook de niveau agent personnalisé correspondent tous deux au même événement, les deux s’exécutent. Les crochets au niveau de l’agent se déclenchent en premier.

Types d’exécutions

Vous pouvez implémenter des hooks à l’aide d’un LLM ou d’un script shell :

Type	Fonctionnement	Idéal pour
Prompt	Un LLM évalue votre requête et retourne une décision JSON	Validation nuanceée (« Cette réponse est-elle terminée ? »)
Commande	Un script Bash ou Python s’exécute dans un environnement en bac à sable (sandbox)	Vérifications déterministes, application de stratégie, audit

Hooks de prompt sont puissants pour une évaluation subjective, comme vérifier si une réponse traite toutes les préoccupations de l’utilisateur ou si une investigation est suffisamment approfondie. Ils utilisent l’espace réservé $ARGUMENTS pour recevoir le contexte complet du hook. S’il $ARGUMENTS n’est pas présent dans l’invite, le contexte est ajouté automatiquement. Lorsqu’une transcription de conversation est disponible, les hooks de type prompt reçoivent également les outils ReadFile et GrepSearch, ce qui permet au LLM de raisonner sur l’historique complet de la conversation.

Les crochets de commande sont préférables pour les vérifications déterministes, telles que la validation qu’une réponse contient des marqueurs requis, le blocage des commandes dangereuses ou l’utilisation de l’outil de journalisation sur un système externe.

Ce qui rend cette approche différente

Le tableau suivant compare le comportement de l’agent avec et sans hooks.

Sans crochets	Avec des crochets
L’agent décide quand il est « terminé »	Vous définissez ce que signifie « terminé »
L’utilisation des outils est invisible	Chaque appel d’outil peut être audité
Les commandes dangereuses s'exécutent silencieusement.	L’application de la stratégie les bloque automatiquement
La qualité dépend de l’ingénierie rapide seule	Les portes de qualité automatisées interceptent les lacunes

Les hooks ne remplacent pas les contrôles de sécurité du mode d’exécution, ils les complètent. Les modes d’exécution contrôlent ce que l’agent peut faire. Les hooks contrôlent la qualité de l’exécution et ce qu’il advient des résultats.

Avant et après

Scénario	Avant	Après
Qualité de la réponse	L’agent s’arrête quand il pense qu’il est terminé	Votre crochet d’arrêt valide l’exhaustivité avant que la réponse atteigne les utilisateurs
Visibilité des outils	Aucune piste d’audit de l’exécution de l’outil	Les hooks PostToolUse consignent et vérifient chaque appel d’outil.
Mise en application de la politique	Les commandes dangereuses s’exécutent non cochées	Les scripts bloquent automatiquement `rm -rf`, `sudo`, et d'autres modèles à risque.
Assurance qualité	L’ingénierie prompte est votre seul levier	Les hooks basés sur LLM évaluent les nuances ; les scripts appliquent des règles déterministes

Configurer des points d'ancrage

Le moyen le plus simple de créer des hooks consiste à utiliser l’interface utilisateur du portail :

Crochets au niveau de l’agent : Accédez à Builder → Hooks → sélectionnez Créer un hook.
Crochets au niveau de l’agent personnalisé : Accédez à Agent Canvas → sélectionnez un agent personnalisé → Gérer les hooks.

Conseil / Astuce

Vous pouvez également configurer des hooks via l’API REST v2 à l’aide PUT /api/v2/extendedAgent/agents/{agentName}de . Le format YAML dans la section suivante montre le schéma de configuration complet. Pour en savoir plus, consultez le didacticiel sur l’API.

L’onglet Agent Canvas YAML affiche le format v1 et ne montre pas les hooks. Utilisez la page Hooks sous Générateur pour afficher et gérer les crochets.

L’exemple suivant montre une configuration de hook complète :

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check if the response ends with "Task complete."
          $ARGUMENTS
          Respond with:
          - {"ok": true} if it does
          - {"ok": false, "reason": "End your response with 'Task complete.'"} if not
        timeout: 30

    PostToolUse:
      - type: command
        matcher: "Bash|ExecuteShellCommand"
        timeout: 30
        failMode: block
        script: |
          #!/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"}))

Format de réponse des hooks

Les hooks doivent générer JSON. Deux formats sont pris en charge.

Format simple (recommandé pour les hooks de prompt) :

{"ok": true}
{"ok": false, "reason": "Please include more details."}

Format développé (recommandé pour les hooks de commande) :

{"decision": "allow"}
{"decision": "block", "reason": "Dangerous command detected."}
{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Tool audit logged."}}

Les crochets de commande peuvent également utiliser des codes de sortie au lieu de la sortie JSON :

Code de sortie	Comportement
`0` sans sortie	Autoriser (aucune objection)
`0` avec JSON	Analyser JSON pour la décision
`2`	Toujours bloquer. stderr devient la raison
Autres	Utilise le paramètre `failMode` (`allow` ou `block`)

Avertissement

Pour les crochets Stop, un rejet sans raison est traité comme une approbation, et l’agent s’arrête normalement. Fournissez toujours un reason champ lors du rejet.

Note

Vous pouvez définir plusieurs hooks pour le même événement. Pour PostToolUse, chaque crochet avec un modèle correspondant matcher s’exécute indépendamment. Si plusieurs hooks fournissent additionalContext, le contexte du dernier hook est injecté dans la conversation.

Référence de configuration

Le tableau suivant décrit toutes les options de configuration de hook disponibles.

Choix	Type	Par défaut	Description
`type`	ficelle	`prompt`	`prompt` ou `command`
`prompt`	ficelle	—	Texte de prompt LLM (requis pour les hooks de prompt). Utiliser `$ARGUMENTS` pour l’injection de contexte.
`command`	ficelle	—	Commande shell inline (pour les hooks de commande, mutuellement exclusif avec `script`).
`script`	ficelle	—	Script multi-lignes (pour les hooks de commande, mutuellement exclusif avec `command`).
`matcher`	ficelle	—	Modèle Regex pour les noms d’outils (requis pour les hooks PostToolUse). `*` correspond à tous les outils. Les modèles sont ancrés comme `^(pattern)$` et sont évalués en respectant la casse. Vide ou null ne correspond à rien.
`timeout`	int	`30`	Délai d’expiration de l’exécution en secondes (doit être positif ; les valeurs supérieures à 300 sont marquées pendant la validation CLI).
`failMode`	ficelle	`allow`	Comment gérer les erreurs de hook : `allow` ou `block`.
`model`	ficelle	`ReasoningFast`	Modèle pour les hooks de prompt (nom du scénario ou nom du déploiement).
`maxRejections`	int	`3` (agent par défaut)	Nombre maximal de rejets avant l'arrêt forcé. Plage : 1 à 25. S’applique uniquement aux hooks Stop de type prompt. Les crochets d’arrêt de type commande n’ont aucune limite implicite. Lorsque plusieurs hooks d’invite spécifient des valeurs différentes, la valeur maximale est utilisée.

Schéma de contexte de hook

Les hooks reçoivent un contexte JSON structuré sur l’événement actuel. Hooks de prompt reçoivent le contexte via l’espace réservé $ARGUMENTS dans le texte du prompt. Les hooks de commande reçoivent le contexte en tant que JSON sur stdin.

Pour les deux types de hooks, le champ execution_summary contient un chemin de fichier vers la transcription de la conversation (et non un contenu inline). Pour les hooks de prompt, le LLM reçoit les outils ReadFile et GrepSearch pour accéder à ce fichier. Pour les hooks de commande, le fichier est disponible à l'emplacement spécifié dans le sandbox.

Champs communs

Tous les hooks reçoivent les champs suivants :

{
  "hook_event_name": "Stop",
  "agent_name": "my_agent",
  "current_turn": 5,
  "max_turns": 50,
  "execution_summary": "/path/to/transcript.txt"
}

Champs des hooks Stop

Les hooks Stop reçoivent des champs supplémentaires concernant la sortie finale de l’agent.

{
  "final_output": "Here is my response...",
  "stop_hook_active": false,
  "stop_rejection_count": 0
}

Champs des hooks PostToolUse

Les hooks PostToolUse reçoivent des informations supplémentaires sur l'exécution de l’outil.

{
  "tool_name": "ExecutePythonCode",
  "tool_input": { "code": "print(2+2)" },
  "tool_result": "4",
  "tool_succeeded": true
}

Limites

Les limites suivantes s’appliquent aux hooks d’agent.

Limite	Valeur
Taille du script	64 Ko maximum
Expiration du délai	1 à 300 secondes
Nombre maximal de rejets (hooks Stop de type prompt)	1 à 25 (par défaut : 3)
Shebangs de script pris en charge	`#!/bin/bash`, `#!/usr/bin/env python3`
Environnement d’exécution de script	Interpréteur de code dans un environnement sandbox

Exemple : Auditer toute l’utilisation de l’outil

Le hook PostToolUse suivant enregistre chaque appel d’outil et ajoute un message de contexte d’audit :

hooks:
  PostToolUse:
    - type: command
      matcher: "*"
      timeout: 30
      failMode: allow
      script: |
        #!/usr/bin/env python3
        import sys, json

        context = json.load(sys.stdin)
        tool_name = context.get('tool_name', 'unknown')

        print(f"Tool used: {tool_name}", file=sys.stderr)

        output = {
            "decision": "allow",
            "hookSpecificOutput": {
                "additionalContext": f"[AUDIT] Tool '{tool_name}' was executed."
            }
        }
        print(json.dumps(output))

Le additionalContext champ est ajouté en tant que message utilisateur dans la conversation, ce qui donne à l’agent une visibilité sur la piste d’audit.

Exemple : Exiger un marqueur d’achèvement

Le crochet d’arrêt suivant rejette les réponses qui ne se terminent pas par « Tâche terminée ».

hooks:
  Stop:
    - type: command
      timeout: 30
      failMode: allow
      script: |
        #!/bin/bash
        CONTEXT=$(cat)
        FINAL_OUTPUT=$(echo "$CONTEXT" | jq -r '.final_output // empty')

        if [[ "$FINAL_OUTPUT" == *"Task complete."* ]]; then
          exit 0
        else
          echo "Please end your response with 'Task complete.'" >&2
          exit 2
        fi

Bonnes pratiques

Suivez ces instructions lorsque vous configurez des hooks d’agent :

Fournissez toujours une raison lors du rejet. Traitez les rejet sans motifs comme des approbations.
Les accroches logicielles de longue durée ralentissent l'exécution de l'agent ; utilisez donc des délais d'expiration appropriés.
Gérer correctement les erreurs : utilisez failMode: allow sauf si une application stricte est requise.
Soyez précis avec les matchers : des matchers PostToolUse trop larges peuvent entraîner des problèmes de performance.
Testez les hooks de manière approfondie : les hooks qui rejettent systématiquement peuvent provoquer des boucles (atténuées par maxRejections).
Connectez-vous à stderr : utilisez stderr pour déboguer la sortie. Le système analyse stdout comme le résultat du hook.

Place à la pratique

La capture d’écran suivante montre un crochet d’arrêt en action. L’agent répond initialement avec seulement « 4 », mais le crochet rejette la réponse, car le marqueur d’achèvement est manquant. L’agent continue ensuite et ajoute le marqueur.

Get started

Ressource	Ce que vous allez découvrir
Configurer des hooks d’agent (API)	Configurer des hooks à l’aide de l’API REST v2 et YAML

Capacité	Comment il se rapporte
Modes d’exécution	Les hooks complètent les contrôles de sécurité du mode d’exécution. Les modes contrôlent ce qui s'exécute, les hooks contrôlent la façon dont cela s'exécute.
Outils Python	Créez des outils personnalisés que les hooks peuvent auditer et valider.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-04-01