Självstudie: Konfigurera agentkrokar (API) i Azure SRE-agent

I den här handledningen skapar du en anpassad agent med en stophook som tvingar agenten att infoga en kompletteringsmarkör för varje svar. Du konfigurerar kroken via REST-API:et och testar den sedan i portalens lekplats.

Uppskattad tid: 15 minuter

I den här tutorialen lär du dig följande:

Förutsättningar

• En Azure SRE-agent i körningstillstånd
• curl för att anropa REST-API:et
• Azure CLI loggade in (az login) för att hämta en åtkomsttoken

Förstå hook-API-formatet

I den här självstudien används REST API v2 för att skapa hookar på en anpassad agent. Portalens YAML-redigerarflik visar v1-format och visar inte krokar som konfigurerats via API:et, men krokarna är fortfarande aktiva. Du kan verifiera dem på sidan Builder>Hooks eller testlekplatsen.

Hitta agentens API-URL

Agentens API-bas-URL följer det här mönstret:

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

Så här hittar du den:

1. Öppna sre.azure.com och välj din agent.
2. I det vänstra sidofältet väljer du Builder>Agent Canvas.
3. Öppna webbläsarens utvecklarverktyg (F12 eller högerklicka på > Inspektera).
4. Gå till fliken Nätverk , filtrera efter "api" och leta efter begäranden till en URL som slutar på .azuresre.ai.
5. Bas-URL:en är allt före /api/....

Du kan också kontrollera src attributet på fliken Element . Leta efter en <iframe> vars src börjar med https://{agent-name}--.

Hämta en åtkomsttoken

Kör följande kommando för att hämta en åtkomsttoken för SRE-agent-API:et:

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

Skapa en anpassad agent med en stoppkrok

Det här steget skapar en anpassad agent med namnet my_hooked_agent med en stoppkrok som kontrollerar om svaret slutar med === RESPONSE COMPLETE ===. Om markören saknas avvisar kroken svaret och uppmanar agenten att lägga till markören.

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

Du får HTTP 202 Godkänd med den fullständiga agentkonfigurationen i svarstexten.

I följande exempel visas samma konfiguration i YAML-format v2 som referens:

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

Så här fungerar stoppkroken

Stoppkroken utvärderar agentens svar innan det återgår till användaren:

• Ersätter $ARGUMENTS med hook-kontexten JSON, som inkluderar agentens slutliga svar.
• LLM utvärderar prompten och returnerar {"ok": true} eller {"ok": false, "reason": "..."}.
• Om den avvisas fortsätter agenten att fungera efter att orsaken har matats in som ett användarmeddelande.
• Efter tre avslag (standardvärdet) stoppas agenten.

Testa kroken i portalen

Följ dessa steg för att testa stoppkroken:

1. Gå till agenten i portalen och välj Builder>Agent Canvas.

2. Välj alternativknappen Testa lekplats .

3. Välj listrutan Underagent/Verktyg , leta upp my_hooked_agent och välj Använd.

   

4. Skriv What is 2+2? in chatten och välj Skicka.

Se vad som händer:

• Agenten svarar först med 4.
• Stoppkroken utvärderar och avvisar svaret (ingen kompletteringsmarkör).
• Ett steg i tankeprocessen visas där agenten fortsätter.
• Det slutliga svaret visas: 4 === RESPONSE COMPLETE ===.

Kroken fungerade. Det tvingade agenten att lägga till markören innan den stoppades.

Lägga till en PostToolAnvänd krok för granskning

Lägg till en PostToolUse hook som loggar vilket verktyg agenten använder. Uppdatera samma agent genom att skicka en ny PUT förfrågan inklusive båda hooks:

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: "*" betyder att denna hook körs för varje verktygsanrop. Skriptet loggar verktygsnamnet och matar in ett [AUDIT] meddelande i konversationen.

Om du vill testa kroken ställer du en fråga till agenten som utlöser ett verktyg (till exempel "Kör echo hello").

Blockera farliga kommandon

Lägg till en andra PostToolUse-hook som blockerar rm -rf, sudo, och 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"}))

Viktiga skillnader från revisionstillknytningen:

• matcher: "Bash|ExecuteShellCommand" körs endast för shell-verktyg (mönstret är förankrat som ^(Bash|ExecuteShellCommand)$).
• failMode: block blockerar verktygets resultat om själva skriptet kraschar (strikt läge).
• Returnerar "block" med en orsak när ett farligt mönster hittas.

Hook-svarformat

Promptkrokar och kommandokrokar använder olika svarsformat.

Utlösarhakar för prompt

Prompt hooks returnerar enkel JSON:

{"ok": true}

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

Kommandokrokar

Kommandokrokar returnerar expanderad JSON:

{"decision": "allow"}

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

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

Kommandokrokar kan också använda slutkoder i stället för JSON:

Kontrollera

När du har konfigurerat och testat krokarna bekräftar du följande villkor:

• Du konfigurerar anpassade krokar på agentnivå med hjälp av REST API v2. De gäller endast för den anpassade agenten.
• Du skapar krokar på agentnivå i Builder > Hooks. De gäller för hela agenten.
• Stoppkroken gör att agenten lägger till === RESPONSE COMPLETE ===-markören innan den stoppas.
• PostToolUse audit hook loggar meddelanden för [AUDIT] verktygsanrop.
• Principkroken blockerar farliga kommandon som rm -rf och sudo.

Felsökning

I följande tabell listas vanliga problem och lösningar för agent hooks.

Nästa steg

Relaterat innehåll

• Översikt över funktioner för agentkrokar
• Skapa och hantera hooks (portal)
• Körningslägen
• Körning av Python-kod