Zelfstudie: Agenthook (API) configureren in Azure SRE Agent

In deze zelfstudie maakt u een aangepaste agent met een "stop hook", waardoor de agent verplicht is een voltooiingsmarkering aan elk antwoord toe te voegen. U configureert de hook via de REST API en test deze vervolgens in de speeltuin van de portal.

Geschatte tijd: 15 minuten

In deze handleiding leer je hoe je:

Vereiste voorwaarden

• Een Azure SRE-agent met de status Actief
• curl om de REST API aan te roepen
• Azure CLI aangemeld (az login) om een toegangstoken op te halen

Inzicht in de hook-API-indeling

In deze zelfstudie wordt de REST API v2 gebruikt om hooks te maken op een aangepaste agent. Op het YAML-editor tabblad van de portal wordt de v1-indeling weergegeven en de hooks die via de API zijn geconfigureerd worden niet getoond, maar de hooks blijven actief. U kunt deze controleren op de pagina Builder>Hooks of de testspeeltuin.

De API-URL van uw agent zoeken

De API-basis-URL van uw agent volgt dit patroon:

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

Om het te vinden:

1. Open sre.azure.com en selecteer uw agent.
2. Selecteer in de linkerzijbalk Builder>Agent Canvas.
3. Open de ontwikkelhulpprogramma's van uw browser (F12 of klik met de rechtermuisknop op > Controleren).
4. Ga naar het tabblad Netwerk , filter op API en zoek aanvragen naar een URL die eindigt op .azuresre.ai.
5. De basis-URL is alles vóór /api/....

U kunt ook het src kenmerk controleren op het tabblad Elementen. Zoek naar een <iframe> waarvan src begint met https://{agent-name}--.

Een toegangstoken opvragen

Voer de volgende opdracht uit om een toegangstoken op te halen voor de SRE Agent-API:

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

Een aangepaste agent maken met een stophook

Met deze stap maakt u een aangepaste agent die wordt aangeroepen my_hooked_agent met een stophook waarmee wordt gecontroleerd of het antwoord eindigt op === RESPONSE COMPLETE ===. Als de markering ontbreekt, weigert de haak het antwoord en geeft de agent de opdracht om de markering toe te voegen.

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

U ontvangt HTTP 202 Geaccepteerd met de volledige agentconfiguratie in de hoofdtekst van het antwoord.

In het volgende voorbeeld ziet u dezelfde configuratie in v2 YAML-indeling voor referentie:

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

Hoe de stophaak werkt

De stophook evalueert het antwoord van de agent voordat deze terugkeert naar de gebruiker:

• $ARGUMENTS Vervangt door de hookcontext JSON, die het uiteindelijke antwoord van de agent bevat.
• Het LLM evalueert de prompt en retourneert {"ok": true} of {"ok": false, "reason": "..."}.
• Als de agent wordt geweigerd, blijft de agent werken nadat de reden is ingevoerd in een gebruikersbericht.
• Na drie afwijzingen (de standaardinstelling) stopt de agent.

Test de hook in het portal

Volg deze stappen om de stophook te testen:

1. Ga naar uw agent in de portal en selecteer Builder>Agent Canvas.

2. Selecteer het keuzerondje Testomgeving.

3. Selecteer de vervolgkeuzelijst Subagent/Tool , zoek my_hooked_agent en selecteer Toepassen.

   

4. Typ What is 2+2? in de chat en selecteer Verzenden.

Bekijk wat er gebeurt:

• De agent reageert eerst met 4.
• De stophook evalueert en weigert het antwoord (geen voltooiingsmarkering).
• Er wordt een stap voor het gedachteproces weergegeven waar de agent doorgaat.
• Het uiteindelijke antwoord wordt weergegeven: 4 === ANTWOORD VOLTOOID ===.

De haak werkte. Het dwong de agent de markering toe te voegen voordat hij stopte.

Een PostToolUse-hook toevoegen voor controle

Voeg een PostToolUse-hook toe die elk hulpprogramma registreert dat door de agent wordt gebruikt. Werk dezelfde agent bij door een nieuwe PUT aanvraag met beide hooks te verzenden:

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: "*" betekent dat deze hook wordt uitgevoerd voor elke tool-aanroep. Het script registreert de naam van het hulpprogramma en injecteert een [AUDIT] bericht in het gesprek.

Als u de hook wilt testen, stelt u de agent een vraag die een hulpprogramma activeert (bijvoorbeeld 'Uitvoeren echo hello').

Gevaarlijke opdrachten blokkeren

Voeg een tweede PostToolUse-haak toe die rm -rf, sudo en chmod 777 blokkeert.

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

Belangrijkste verschillen ten opzichte van de audithook:

• matcher: "Bash|ExecuteShellCommand" wordt alleen uitgevoerd voor shellprogramma's (patroon is verankerd als ^(Bash|ExecuteShellCommand)$).
• failMode: block blokkeert het resultaat van het hulpprogramma als het script zelf vastloopt (strikte modus).
• Retourneert "block" met een reden wanneer een gevaarlijk patroon wordt gevonden.

Hook-antwoordindelingen

Prompthook en opdrachthook maken gebruik van verschillende antwoordindelingen.

Aanzet haken

Prompthook retourneert eenvoudige JSON:

{"ok": true}

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

Opdrachthook

Opdrachthaken geven uitgebreide JSON:

{"decision": "allow"}

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

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

Opdrachthaken kunnen ook afsluitcodes gebruiken in plaats van JSON:

Verifiëren

Nadat u de hooks hebt geconfigureerd en getest, bevestigt u de volgende voorwaarden:

• U configureert hooks op aangepast agentniveau met behulp van REST API v2. Ze zijn alleen van toepassing op die specifieke agent.
• U maakt haken op agentniveau in Builder > Hooks. Ze zijn van toepassing op de hele agent.
• De stophaak zorgt ervoor dat de agent de === RESPONSE COMPLETE === markering toevoegt voordat deze stopt.
• De PostToolUse audit hook registreert [AUDIT] berichten voor hulpprogramma-aanroepen.
• De beleidshook blokkeert gevaarlijke opdrachten zoals rm -rf en sudo.

Troubleshooting

De volgende tabel bevat veelvoorkomende problemen en oplossingen voor agenthooks.

Volgende stap

Verwante inhoud

• Overzicht van mogelijkheden voor agent hooks
• Hooks maken en beheren (portal)
• Uitvoeringsmodi
• Uitvoering van Python-code