Agent-Hooks im Azure SRE Agent

Hooks sind benutzerdefinierte Prüfpunkte, die das Verhalten des Agents in wichtigen Momenten abfangen und steuern. Verwenden Sie Hooks, um Quality-Gates für die Antworten von Agents zu erzwingen, die Verwendung von Tools zu überprüfen und zu steuern, gefährliche Operationen durch die Durchsetzung von Richtlinien zu blockieren und eine vorzeitige Aufgabenerledigung durch die Validierung der Agentenausgaben zu verhindern.

Das Problem

Ihr Agent führt Aufgaben autonom aus – Untersuchung von Vorfällen, Ausführen von Tools und Generieren von Antworten. Aber Autonomie ohne Aufsicht schafft Risiken:

• Unvollständige Antworten: Der Agent sagt "fertig", bevor er alles adressiert, was Sie angefordert haben.
• Nicht überprüfte Toolverwendung: Sie haben keinen Einblick in welche Tools der Agent aufruft oder welche Ergebnisse es erhält.
• Keine Richtlinienerzwingung: Gefährliche Vorgänge (destruktive Befehle, nicht autorisierte Änderungen) erfolgen unkontrolliert.
• Qualitätslücken: Antworten verpassen wichtige Informationen, da kein Überprüfungsschritt vorhanden ist.

Sie benötigen eine Möglichkeit, das Verhalten des Agenten in wichtigen Momenten abzufangen, ohne es zu verlangsamen oder seine Autonomie vollständig zu entfernen.

Funktionsweise von Agenten-Hooks

Hooks sind benutzerdefinierte Prüfpunkte, die Sie an bestimmte Agentereignisse anfügen. Wenn ein Ereignis ausgelöst wird, evaluiert der Hook die Situation und entscheidet, ob die Aktion zugelassen oder blockiert wird.

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

Derzeit werden zwei Hook-Ereignisse unterstützt:

Zwei Ebenen von Haken

Hooks funktionieren auf zwei Ebenen:

Beide Ebenen können koexistieren. Wenn ein Hook auf Agentebene und ein Hook auf benutzerdefinierter Agent-Ebene beide mit demselben Ereignis übereinstimmen, werden beide ausgeführt. Die Hooks auf Agentenebene werden zuerst ausgelöst.

Ausführungstypen

Sie können Hooks mithilfe eines LLM oder eines Shellskripts implementieren:

Eingabeaufforderungshaken eignen sich für subjektive Auswertungen, z. B. die Überprüfung, ob eine Antwort alle Bedenken des Benutzers behandelt oder überprüft, ob eine Untersuchung gründlich genug war. Sie verwenden den $ARGUMENTS Platzhalter, um den vollen Kontext des Hooks zu erhalten. Wenn $ARGUMENTS in der Eingabeaufforderung nicht vorhanden ist, wird der Kontext automatisch angefügt. Wenn ein Transkript der Kommunikation zur Verfügung steht, erhalten Prompt Hooks auch ReadFile und GrepSearch Tools, die dem LLM Rückschlüsse auf die gesamte Historie der Kommunikation ermöglichen.

Befehlshaken eignen sich besser für deterministische Überprüfungen, z. B. die Überprüfung, dass eine Antwort erforderliche Markierungen enthält, gefährliche Befehle blockieren oder die Verwendung des Protokollierungstools für ein externes System.

Was macht diesen Ansatz anders

In der folgenden Tabelle wird das Verhalten von Agenten mit und ohne Hooks verglichen.

Hooks ersetzen die Sicherheitskontrollen im Ausführungsmodus nicht – sie ergänzen sie. Ausführungsmodi steuern , was der Agent tun kann. Hooks steuern , wie gut es funktioniert und was mit den Ergebnissen passiert .

Vor und nachher

Hooks konfigurieren

Die einfachste Möglichkeit zum Erstellen von Hooks besteht in der Portal-UI:

1. Hooks auf Agentebene: Wechseln Sie zu Generator → Hooks , → Wählen Sie "Hook erstellen" aus.
2. Hooks auf benutzerdefinierter Agent-Ebene: Wechseln Sie zu "Agent Canvas" , → einen benutzerdefinierten Agent auswählen → Hooks verwalten.

Das folgende Beispiel zeigt eine vollständige Hook-Konfiguration:

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"}))

Hook-Antwortformat

Hooks müssen JSON ausgeben. Zwei Formate werden unterstützt.

Einfaches Format (empfohlen für Prompt-Hooks):

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

Erweitertes Format (empfohlen für Befehlshaken):

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

Befehlshaken können auch Exitcodes anstelle der JSON-Ausgabe verwenden:

Konfigurationsreferenz

In der folgenden Tabelle werden alle verfügbaren Hook-Konfigurationsoptionen beschrieben.

Hook-Kontextschema

Hooks empfangen strukturierten JSON-Kontext zu dem aktuellen Ereignis. Prompt-Hooks erhalten den Kontext über den Platzhalter $ARGUMENTS im Prompttext. Befehlshaken empfangen Kontext als JSON für stdin.

Für beide Hooktypen enthält das Feld execution_summary einen Dateipfad zum Transkript der Unterhaltung (nicht zu Inlineinhalten). Für Prompt-Hooks erhält das LLM ReadFile- und GrepSearch-Tools für den Zugriff auf diese Datei. Bei Befehlshaken ist die Datei im angegebenen Pfad im Sandkasten verfügbar.

Allgemeine Felder

Alle Hooks erhalten die folgenden Felder:

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

Felder für Stopp-Hooks

Stopp-Hooks erhalten zusätzliche Felder für die endgültige Ausgabe des Agents.

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

PostToolUse-Hookfelder

PostToolUse-Hooks erhalten zusätzliche Felder zur Toolausführung.

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

Einschränkungen

Die folgenden Limits gelten für Agent Hooks.

Beispiel: Überwachen der gesamten Toolverwendung

Der folgende PostToolUse-Hook protokolliert jeden Toolaufruf und fügt eine Überwachungskontextmeldung hinzu:

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))

Das additionalContext Feld wird in der Unterhaltung als Benutzernachricht hinzugefügt, sodass der Agent einen Einblick in den Überwachungspfad erhält.

Beispiel: Anfordern einer Vervollständigungsmarkierung

Der folgende Stopp-Hook lehnt Antworten ab, die nicht mit "Aufgabe abgeschlossen" enden:

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

Bewährte Methoden

Befolgen Sie die folgenden Richtlinien, wenn Sie Agent-Hooks konfigurieren:

1. Geben Sie beim Ablehnen immer einen Grund an. Behandeln Sie Ablehnungen ohne Gründe als Genehmigungen.
2. Verwenden Sie angemessene Timeouts: Lang laufende Hooks verlangsamen die Ausführung des Agents.
3. Behandeln Sie Fehler ordnungsgemäß: Verwenden Sie failMode: allow, es sei denn, strenge Durchsetzung ist erforderlich.
4. Sein Sie spezifisch mit Matchern: Zu weit gefasste PostToolUse-Matchers können Leistungsprobleme verursachen.
5. Testen Sie Hooks gründlich: Hooks, die immer ablehnen, können Schleifen verursachen (Behebung durch maxRejections).
6. In stderr protokollieren: Verwenden Sie stderr zur Fehlerbehebung der Ausgaben. Das System parst stdout als Ergebnis des Hooks.

Probieren Sie es selbst aus

Der folgende Screenshot zeigt einen Stopphaken in Aktion. Der Agent antwortet zunächst nur mit „4“. Der Hook lehnt die Antwort jedoch ab, weil der Completion-Marker fehlt. Der Agent fährt dann fort und fügt die Markierung hinzu.

Erste Schritte

Verwandte Inhalte