Agentkrokar i Azure SRE-agent

Krokar är anpassade kontrollpunkter som fångar upp och styr agentbeteende vid viktiga tidpunkter. Använd krokar för att införa kvalitetsgrindar på agentsvar, kontrollera användningen av gransknings- och kontrollverktyg, blockera farliga åtgärder genom att tillämpa principer och förhindra att uppgifter slutförs för tidigt genom att validera agentutdata.

Problemet

Din agent utför uppgifter autonomt – undersöka incidenter, köra verktyg och generera svar. Men autonomi utan tillsyn skapar risk:

• Ofullständiga svar: Agenten säger "klar" innan du tar itu med allt du bad om.
• Oheviderad verktygsanvändning: Du har ingen insyn i vilka verktyg agenten anropar eller vilka resultat den får.
• Ingen principframtvingande: Farliga åtgärder (destruktiva kommandon, obehöriga ändringar) fortsätter omarkerade.
• Kvalitetsluckor: Svar missar viktig information eftersom det inte finns något valideringssteg.

Du behöver ett sätt att fånga upp agentbeteendet vid viktiga tidpunkter utan att sakta ned det eller ta bort dess autonomi helt.

Så här fungerar agentkopplingar

Hooks är anpassade kontrollpunkter som du kopplar till specifika agenthändelser. När en händelse utlöses utvärderar din hook situationen och avgör om åtgärden ska tillåtas eller blockeras.

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

Två hook-händelser stöds för närvarande:

Två nivåer av krokar

Krokar fungerar på två nivåer:

Båda nivåerna kan samexistera. Om en krok på agentnivå och en krok på anpassad agentnivå båda matchar samma händelse , körs båda. Krokarna på agentnivå avfyras först.

Körningstyper

Du kan implementera krokar med antingen ett LLM- eller ett gränssnittsskript:

Prompt hooks är kraftfulla för subjektiv utvärdering, till exempel att kontrollera om ett svar åtgärdar alla användarproblem eller verifierar att en undersökning var tillräckligt grundlig. De använder $ARGUMENTS platshållaren för att ta emot den fullständiga hook-kontexten. Om $ARGUMENTS inte finns i prompten, läggs kontexten till automatiskt. När en konversationsavskrift är tillgänglig tar prompt hooks också emot ReadFile och GrepSearch verktyg som möjliggör att LLM kan resonera om hela konversationshistoriken.

Kommandokrokar är bättre för deterministiska kontroller, till exempel validering av att ett svar innehåller nödvändiga markörer, blockerar farliga kommandon eller loggningsverktygsanvändning till ett externt system.

Vad gör den här metoden annorlunda

I följande tabell jämförs agenters beteende med och utan krokar.

Krokar ersätter inte säkerhetskontroller för körningsläge – de kompletterar dem. Körningslägen styr vad agenten kan göra. Hooks styr hur bra det gör och vad som händer med resultaten.

Före och efter

Konfigurera krokar

Det enklaste sättet att skapa krokar är via portalgränssnittet:

1. Krokar på agentnivå: Gå till Builder → Hooks → välj Skapa krok.
2. Anpassade krokar på agentnivå: Gå till Agentöversikt → välj en anpassad agent → Hantera Hooks.

I följande exempel visas en fullständig krokkonfiguration:

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

Krokar måste mata ut JSON. Två format stöds.

Enkelt format (rekommenderas för promptkrokar):

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

Utökat format (rekommenderas för kommandokrokar):

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

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

Konfigurationsreferens

I följande tabell beskrivs alla tillgängliga konfigurationsalternativ för krokar.

Schema för hookkontext

Hooks tar emot strukturerad JSON-kontext om den aktuella händelsen. Prompt hooks tar emot kontext via platshållaren $ARGUMENTS i promptens text. Kommandokrokar får kontext som JSON på stdin.

För båda kroktyperna innehåller fältet execution_summary en filsökväg till konversationsavskriften (inte infogat innehåll). För prompt hooks tar LLM emot ReadFile och GrepSearch verktyg för att komma åt den här filen. För kommandokrokar är filen tillgänglig på den angivna sökvägen i sandbox-miljön.

Vanliga fält

Alla krokar får följande fält:

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

Stoppa krokfält

Stoppkrokar tar emot extra fält om agentens slutliga utdata.

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

PostToolAnvänd krokfält

PostToolAnvändning-krokar tar emot extra fält om verktygets körning.

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

Begränsningar

Följande begränsningar gäller för agenthookar.

Exempel: Granska all verktygsanvändning

Följande PostToolUse hook loggar varje verktygsanrop och lägger till ett granskningskontextmeddelande:

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

Fältet additionalContext läggs till som ett användarmeddelande i konversationen, vilket ger agenten insyn i spårningsloggen.

Exempel: Kräv en kompletteringsmarkör

Följande Stoppkrok avvisar svar som inte slutar med "Uppgiften har slutförts":

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

Bästa praxis

Följ dessa riktlinjer när du konfigurerar agentkrokar:

1. Ange alltid en orsak när du avvisar. Behandla avslag utan skäl som godkännanden.
2. Använd lämpliga tidsgränser: Långa hooks saktar ner agentkörningen.
3. Hantera fel på ett korrekt sätt: Använd failMode: allow såvida inte strikt verkställighet krävs.
4. Var specifik med matchare: Alltför breda PostToolUse-matchare kan orsaka problem med prestandan.
5. Testa hookar noggrant: Hookar som alltid vägrar kan orsaka loopar (minimeras av maxRejections).
6. Logga till stderr: Använd stderr för felsökning av utdata. Systemet parsar stdout som krokresultatet.

Prova själv

Följande skärmbild visar hur en Stoppkrok fungerar. Agenten besvarar först med bara "4", men mekanismen avvisar svaret eftersom slutförandemarkören saknas. Agenten fortsätter sedan och lägger till markören.

Get started

Relaterat innehåll