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 :

Deux niveaux de crochets

Les crochets fonctionnent à deux niveaux :

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 :

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.

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

Configurer des points d'ancrage

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

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

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 :

Référence de configuration

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

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.

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 :

1. Fournissez toujours une raison lors du rejet. Traitez les rejet sans motifs comme des approbations.
2. Les accroches logicielles de longue durée ralentissent l'exécution de l'agent ; utilisez donc des délais d'expiration appropriés.
3. Gérer correctement les erreurs : utilisez failMode: allow sauf si une application stricte est requise.
4. Soyez précis avec les matchers : des matchers PostToolUse trop larges peuvent entraîner des problèmes de performance.
5. Testez les hooks de manière approfondie : les hooks qui rejettent systématiquement peuvent provoquer des boucles (atténuées par maxRejections).
6. 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

Contenu connexe