Agent-hooks in Azure SRE Agent

Hooks zijn aangepaste controlepunten die het gedrag van de agent op belangrijke momenten onderscheppen en beheren. Gebruik hooks om kwaliteitspoorten af te dwingen voor agentreacties, controleer en beheer het gebruik van tools, blokkeer gevaarlijke bewerkingen door beleid te handhaven, en voorkom voortijdige voltooiing van taken door de agentuitvoer te valideren.

Het probleem

Uw agent voert taken autonoom uit: incidenten onderzoeken, hulpprogramma's uitvoeren en antwoorden genereren. Maar autonomie zonder toezicht brengt risico's met zich mee:

• Onvolledige antwoorden: de agent zegt 'klaar' voordat alles is behandeld waarom u hebt gevraagd.
• Gebruik van niet-gecontroleerde hulpprogramma's: u hebt geen inzicht in welke hulpprogramma's de agent aanroept of welke resultaten deze krijgt.
• Geen beleidshandhaving: gevaarlijke bewerkingen (destructieve opdrachten, niet-geautoriseerde wijzigingen) gaan ongecontroleerd door.
• Hiaten in de kwaliteit: reacties missen kritieke informatie omdat er geen validatiestap is.

U hebt een manier nodig om agentgedrag op belangrijke momenten te onderscheppen zonder het te vertragen of de autonomie volledig te verwijderen.

Hoe agenthook werkt

Hooks zijn aangepaste controlepunten die u aan specifieke agent-gebeurtenissen koppelt. Wanneer een gebeurtenis wordt geactiveerd, evalueert uw hook de situatie en bepaalt of de actie moet worden toegestaan of geblokkeerd.

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

Er worden momenteel twee hooks ondersteund:

Twee niveaus van haken

Haken werken op twee niveaus:

Beide niveaus kunnen naast elkaar bestaan. Als een haak op agentniveau en een haak op custom-agentniveau beide overeenkomen met dezelfde gebeurtenis, worden beide uitgevoerd. De haken op agentniveau worden eerst geactiveerd.

Uitvoeringstypen

U kunt hooks implementeren met behulp van een LLM- of shellscript:

Prompt hooks zijn krachtig voor subjectieve evaluatie, zoals controleren of een antwoord betrekking heeft op alle gebruikersproblemen of controleren of een onderzoek grondig genoeg was. Ze gebruiken de $ARGUMENTS tijdelijke aanduiding om de volledige context van de hook te ontvangen. Als $ARGUMENTS niet in de prompt staat, wordt de context automatisch toegevoegd. Wanneer een gesprekstranscript beschikbaar is, ontvangen prompt hooks ook ReadFile en GrepSearch tools, waardoor de LLM kan redeneren over de volledige gespreksgeschiedenis.

Command hooks zijn beter voor deterministische controles, zoals het valideren dat een antwoord vereiste markeringen bevat, het blokkeren van gevaarlijke opdrachten, of het loggen van gereedschapsgebruik naar een extern systeem.

Wat maakt deze benadering anders

In de volgende tabel wordt het gedrag van agents vergeleken met en zonder haakjes.

Haken vervangen veiligheidscontroles in de gebruiksmodus niet, maar vormen hierop een aanvulling. Met uitvoeringsmodi kunt u bepalen wat de agent kan doen. Hooks bepalen hoe goed het werkt en wat er gebeurt met de resultaten.

Voor en na

Hooks configureren

De eenvoudigste manier om hooks te maken, is via de gebruikersinterface van de portal:

1. Haken op agentniveau: Ga naar Builder → Hooks → selecteer Hook maken.
2. Hooks op aangepast agentniveau: Ga naar Agent Canvas → selecteer een aangepaste agent → Hooks beheren.

In het volgende voorbeeld wordt een complete hook-configuratie getoond.

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

Hooks moeten JSON uitvoeren. Er worden twee indelingen ondersteund.

Eenvoudige indeling (aanbevolen voor prompthook):

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

Uitgebreide indeling (aanbevolen voor opdrachthook):

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

Opdrachthaken kunnen ook afsluitcodes gebruiken in plaats van JSON-uitvoer:

Configuratiegids

In de volgende tabel worden alle beschikbare hookconfiguratieopties beschreven.

Hookcontextschema

Hooks ontvangen gestructureerde JSON-context over de huidige gebeurtenis. Prompthook ontvangt context via de $ARGUMENTS tijdelijke aanduiding in de prompttekst. Opdrachthook ontvangt context als JSON op stdin.

Voor beide hooktypen bevat het execution_summary veld een bestandspad naar de gesprekstranscriptie (geen inline-inhoud). Voor prompthooks ontvangt de LLM ReadFile en GrepSearch hulpprogramma's om toegang te krijgen tot dit bestand. Voor de commandohaken is het bestand beschikbaar op het opgegeven pad in de sandbox.

Gemeenschappelijke velden

Alle koppelingen (hooks) ontvangen de volgende velden:

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

Haakvelden stoppen

Stop hooks ontvangen extra velden over de uiteindelijke uitvoer van de agent.

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

Velden na gereedschapsgebruik hook

PostToolUse hooks ontvangen extra velden over de uitvoering van het hulpprogramma.

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

Limieten

De volgende limieten gelden voor agenthooks.

Voorbeeld: Het gebruik van alle hulpprogramma's controleren

De volgende PostToolUse hook registreert elke aanroep van het hulpprogramma en voegt een auditcontextbericht toe:

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

Het additionalContext veld wordt toegevoegd als een gebruikersbericht in het gesprek, waardoor de agent inzicht heeft in het audittrail.

Voorbeeld: Een voltooiingsmarkering vereisen

Met de volgende stophook worden antwoorden geweigerd die niet eindigen op 'Taak voltooid':

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

Beste praktijken

Volg deze richtlijnen wanneer u agenthook configureert:

1. Geef altijd een reden op bij het afwijzen. Behandelt afwijzingen zonder redenen als goedkeuringen.
2. Gebruik de juiste time-outs: Langlopende hooks vertragen de uitvoering van agenten.
3. Fouten probleemloos afhandelen: gebruik failMode: allow tenzij strikte afdwinging is vereist.
4. Wees specifiek met matchers: Te brede PostToolUse matchers kunnen prestatieproblemen veroorzaken.
5. Testhaken grondig: Haken die altijd weigeren kunnen lussen veroorzaken (verzacht door maxRejections).
6. Log naar stderr: Gebruik stderr voor debug-uitvoer. Het systeem leest stdout als het terugkoppelresultaat.

Probeer het zelf

Op de volgende schermopname ziet u een Stop hook in actie. De agent reageert in eerste instantie met slechts '4', maar de haak weigert het antwoord omdat de voltooiingsmarkering ontbreekt. De agent gaat vervolgens verder en voegt de markering toe.

Aan de slag

Verwante inhoud