Lernprogramm: Konfigurieren von Agent-Hooks (API) in Azure SRE-Agent

In diesem Lernprogramm erstellen Sie einen benutzerdefinierten Agent mit einem Stopp-Hook, der den Agent zwingt, jeder Antwort eine Abschlussmarkierung hinzuzufügen. Sie konfigurieren den Hook über die REST-API und testen ihn dann im Playground des Portals.

Geschätzte Zeit: 15 Minuten

In diesem Tutorial erfahren Sie, wie:

Voraussetzungen

• Ein Azure SRE-Agent im Zustand "Ausgeführt"
• Curl zum Aufrufen der REST-API
• Azure CLI-Anmeldung (az login), um ein Zugriffstoken zu erhalten

Grundlegendes zum Hook-API-Format

In diesem Lernprogramm wird die REST-API v2 verwendet, um Hooks für einen benutzerdefinierten Agent zu erstellen. Die Registerkarte YAML-Editor des Portals zeigt das Format v1 an und zeigt die über die API konfigurierten Hooks nicht an, aber die Hooks sind trotzdem aktiv. Sie können sie auf der Builder>Hooks Seite oder im Test playground überprüfen.

Suchen der API-URL Ihres Agents

Die API-Basis-URL Ihres Agents folgt diesem Muster:

https://{agent-name}--{hash}.{hash}.{region}.azuresre.ai

So finden Sie sie:

1. Öffnen Sie sre.azure.com , und wählen Sie Ihren Agenten aus.
2. Wählen Sie in der linken Randleiste Builder>Agent Canvas aus.
3. Öffnen Sie die Entwicklertools Ihres Browsers (F12 oder klicken Sie mit der rechten Maustaste auf > Inspect).
4. Wechseln Sie zur Registerkarte "Netzwerk", filtern Sie nach "api" und suchen Sie nach Anfragen an eine URL, die auf .azuresre.ai endet.
5. Die Basis-URL ist alles, bevor /api/....

Alternativ können Sie das src-Attribut auf der Registerkarte Elemente überprüfen. Suchen Sie nach einem <iframe>, dessen src mit https://{agent-name}-- beginnt.

Zugriffstoken erhalten

Führen Sie den folgenden Befehl aus, um ein Zugriffstoken für die SRE-Agent-API abzurufen:

TOKEN=$(az account get-access-token \
  --resource <RESOURCE_ID> \
  --query accessToken -o tsv)

Erstellen eines benutzerdefinierten Agents mit einem Stopphaken

Dieser Schritt erstellt einen benutzerdefinierten Agenten namens my_hooked_agent mit einem Stop-Hook, der überprüft, ob die Antwort mit === RESPONSE COMPLETE === endet. Wenn der Marker fehlt, lehnt der Hook die Antwort ab und fordert den Agent auf, den Marker hinzuzufügen.

AGENT_URL="https://your-agent--xxxxxxxx.yyyyyyyy.region.azuresre.ai"

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ]
    }
  }
}
EOF

Sie erhalten HTTP 202 Akzeptiert mit der vollständigen Agent-Konfiguration im Antworttext.

Das folgende Beispiel zeigt die gleiche Konfiguration im v2 YAML-Format für Referenz:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant. Be concise.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check the agent response below.

          $ARGUMENTS

          Does it end with === RESPONSE COMPLETE ===?
          If yes: {"ok": true}
          If no: {"ok": false, "reason": "Add === RESPONSE COMPLETE === at the end."}
        timeout: 30

Funktionsweise des Stopphakens

Der Stopp-Hook wertet die Antwort des Agents aus, bevor er an den Benutzer zurückkehrt:

• Ersetzt $ARGUMENTS durch das Kontext-JSON des Hooks, das die endgültige Antwort des Agents enthält.
• Das LLM wertet die Eingabeaufforderung aus und gibt {"ok": true} oder {"ok": false, "reason": "..."} zurück.
• Wenn der Agent ablehnt, arbeitet er weiterhin, nachdem der Grund als Benutzernachricht eingefügt wurde.
• Nach drei Ablehnungen (Standardeinstellung) stoppt der Agent.

Teste den Hook im Portal

Führen Sie die folgenden Schritte aus, um den Stopphaken zu testen:

1. Wechseln Sie im Portal zu Ihrem Agenten und wählen Sie Builder>Agent Canvas aus.

2. Aktivieren Sie das Optionsfeld Playground testen.

3. Wählen Sie das Dropdownmenü Subagent/Tool aus, suchen Sie my_hooked_agent, und wählen Sie Anwenden aus.

   

4. Geben Sie What is 2+2? im Chat ein, und wählen Sie Senden aus.

Schauen Sie sich an, was passiert:

• Der Agent antwortet zuerst mit 4.
• Der Stopp-Hook wertet die Antwort aus und lehnt sie ab (keine Vervollständigungsmarkierung).
• Anschließend wird ein Gedankenprozess-Schritt angezeigt, mit dem der Agent fortfährt.
• Die endgültige Antwort wird angezeigt: 4 === ANTWORT ABGESCHLOSSEN ===.

Der Haken funktionierte. Der Agent wurde gezwungen, den Marker hinzuzufügen, bevor er gestoppt wurde.

Hinzufügen eines PostToolUse-Hooks für die Überwachung

Fügen Sie einen PostToolUse-Hook hinzu, der jedes tool protokolliert, das der Agent verwendet. Aktualisieren Sie denselben Agent, indem Sie eine neue PUT Anforderung mit beiden Hooks senden:

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ],
      "PostToolUse": [
        {
          "type": "command",
          "matcher": "*",
          "timeout": 30,
          "failMode": "allow",
          "script": "#!/usr/bin/env python3\nimport sys, json\ncontext = json.load(sys.stdin)\ntool = context.get('tool_name', 'unknown')\nprint(json.dumps({'decision': 'allow', 'hookSpecificOutput': {'additionalContext': f'[AUDIT] {tool} executed.'}}))"
        }
      ]
    }
  }
}
EOF

matcher: "*" bedeutet, dass dieser Hook für jeden Toolaufruf ausgeführt wird. Das Skript protokolliert den Toolnamen und fügt eine [AUDIT] Nachricht in die Unterhaltung ein.

Um den Hook zu testen, stellen Sie dem Agent eine Frage, die ein Tool auslöst (z. B. "Ausführen echo hello").

Gefährliche Befehle blockieren

Fügen Sie einen zweiten PostToolUse-Hook hinzu, der blockiert rm -rf, sudound chmod 777:

PostToolUse:
  # Audit hook (runs for all tools)
  - type: command
    matcher: "*"
    timeout: 30
    failMode: allow
    script: |
      #!/usr/bin/env python3
      import sys, json
      context = json.load(sys.stdin)
      tool = context.get('tool_name', 'unknown')
      print(json.dumps({"decision": "allow",
        "hookSpecificOutput": {"additionalContext": f"[AUDIT] {tool} executed."}}))

  # Policy hook (only for shell tools)
  - 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', '')
      for pattern in [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']:
          if re.search(pattern, command):
              print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
              sys.exit(0)
      print(json.dumps({"decision": "allow"}))

Die wichtigsten Unterschiede zum Audit-Hook:

• matcher: "Bash|ExecuteShellCommand" wird nur für Shell-Tools ausgeführt (das Muster ist verankert als ^(Bash|ExecuteShellCommand)$).
• failMode: block blockiert das Toolergebnis, wenn das Skript selbst abstürzt (strenger Modus).
• Gibt "block" mit einem Grund zurück, wenn ein gefährliches Muster gefunden wird.

Hook-Antwortformate

Eingabeaufforderungshaken und Befehlshaken verwenden unterschiedliche Antwortformate.

Eingabeaufforderungshaken

Eingabeaufforderungshaken geben einfaches JSON zurück:

{"ok": true}

{"ok": false, "reason": "Please fix X."}

Befehlshaken

Befehlshaken geben erweiterte JSON zurück:

{"decision": "allow"}

{"decision": "block", "reason": "Dangerous command."}

{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Audit note."}}

Befehlshaken können auch Exitcodes anstelle von JSON verwenden:

Überprüfen

Nachdem Sie die Hooks konfiguriert und getestet haben, bestätigen Sie die folgenden Bedingungen:

• Sie konfigurieren Hooks auf benutzerdefinierter Agent-Ebene mithilfe der REST-API v2. Sie gelten nur für den kundenspezifischen Agent.
• Sie erstellen agentenspezifische Hooks in Builder > Hooks. Sie gelten für den gesamten Agent.
• Der Stopphaken bewirkt, dass der Agent die === RESPONSE COMPLETE === Markierung vor dem Beenden hinzu fügt.
• Der PostToolUse-Überwachungshaken protokolliert [AUDIT] Nachrichten für Toolaufrufe.
• Der Richtlinienhaken blockiert gefährliche Befehle wie rm -rf und sudo.

Problembehandlung

In der folgenden Tabelle sind häufige Probleme und Lösungen für Agent-Hooks aufgeführt.

Nächster Schritt

Verwandte Inhalte

• Übersicht über Agent-Hooks-Funktionen
• Erstellen und Verwalten von Hooks (Portal)
• Ausführungsmodi
• Python-Codeausführung