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:

Event	Activeert wanneer	Wat kunt u doen
Stop	Agent staat op het punt om een definitief antwoord te retourneren	Volledigheid valideren, weigeren en afdwingen dat de agent doorgaat
PostToolUse	Het uitvoeren van een hulpprogramma is voltooid	Gebruik controleren, resultaten blokkeren, extra context injecteren

Twee niveaus van haken

Haken werken op twee niveaus:

Niveau	Waar te configureren	Scope
Agentniveau	Builder → Hooks in het portaal	Van toepassing op de hele agent, inclusief alle threads en alle aangepaste agents
Aangepast agentniveau	Agent Canvas → Op maat gemaakte agent → Beheer Hooks of via de REST API v2	Alleen van toepassing wanneer die specifieke aangepaste agent wordt uitgevoerd

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:

Typ	Hoe werkt het?	Het beste voor
Prompt	Een LLM evalueert uw prompt en retourneert een JSON-beslissing	Genuanceerde validatie (Is dit antwoord voltooid?)
Opdracht	Een bash- of Python-script wordt uitgevoerd in een sandbox-omgeving	Deterministische controles, beleidsnaleving, audit

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.

Zonder haken	Met haken
Agent bepaalt wanneer het klaar is	U definieert wat 'gedaan' betekent
Het gebruik van hulpprogramma's is onzichtbaar	Elke tooloproep kan worden gecontroleerd
Gevaarlijke opdrachten gaan op de achtergrond door	De beleidsuitvoering blokkeert hen automatisch.
Kwaliteit hangt alleen af van prompt engineering	Geautomatiseerde kwaliteitspoorten vangen hiaten

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

Scenario	Voordat	Na
Antwoordkwaliteit	Agent stopt wanneer hij denkt dat hij klaar is	Uw stophook valideert volledigheid voordat het antwoord gebruikers bereikt
Zichtbaarheid van hulpprogramma's	Geen audittrail van uitvoering van hulpprogramma's	PostToolUse hooks log en controleer elke aanroep van het hulpprogramma
Beleidsafdwinging	Gevaarlijke opdrachten worden ongecontroleerd uitgevoerd	Scripts blokkeren `rm -rf`, `sudo`en andere riskante patronen automatisch
Kwaliteitsborging	Prompt engineering is uw enige troefkaart	Op LLM-gebaseerde hooks evalueren nuance; scripts dwingen regels af die deterministisch zijn

Hooks configureren

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

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

Aanbeveling

U kunt ook hooks configureren via REST API v2 met behulp van PUT /api/v2/extendedAgent/agents/{agentName}. De YAML-indeling in de volgende sectie toont het volledige configuratieschema. Zie de API-zelfstudie voor meer informatie.

Op het tabblad Agent Canvas YAML wordt het v1-formaat weergegeven en worden geen hooks weergegeven. Gebruik de pagina Hooks onder Opbouwfunctie om hooks weer te geven en te 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:

Afsluitcode	Gedrag
`0` zonder uitvoer	Toestaan (geen bezwaar)
`0` met JSON	JSON parseren voor beslissing
`2`	Altijd blokkeren. stderr wordt de reden
Overige	Maakt gebruik van `failMode` instelling (`allow` of `block`)

Waarschuwing

Bij Stop hooks wordt een afwijzing zonder reden behandeld als goedkeuring en stopt de agent op normale wijze. Geef altijd een reason veld op bij het weigeren.

Opmerking

U kunt meerdere hooks definiëren voor dezelfde gebeurtenis. Voor PostToolUse wordt elke haak met een overeenkomend matcher patroon onafhankelijk uitgevoerd. Wanneer meerdere hooks additionalContext bieden, wordt de context van de laatste hook aan het gesprek toegevoegd.

Configuratiegids

In de volgende tabel worden alle beschikbare hookconfiguratieopties beschreven.

Option	Typ	Verstek	Beschrijving
`type`	touw	`prompt`	`prompt` of `command`
`prompt`	touw	—	LLM-prompttekst (vereist voor prompthook). Gebruiken `$ARGUMENTS` voor contextinjectie.
`command`	touw	—	Inline shell-opdracht (voor commando hooks, kunnen niet samen worden gebruikt met `script`).
`script`	touw	—	Script met meerdere regels (voor opdrachthook, wederzijds exclusief met `command`).
`matcher`	touw	—	Regex-patroon voor toolnamen (vereist voor PostToolUse hooks). `*` komt overeen met alle tools. Patronen worden verankerd als `^(pattern)$` en overeenkomend hoofdlettergevoelig. Leeg of null komt niet overeen met niets.
`timeout`	int	`30`	Time-out voor uitvoering in seconden (moet positief zijn; waarden boven 300 worden gemarkeerd tijdens CLI-validatie).
`failMode`	touw	`allow`	Hook-fouten afhandelen: `allow` of `block`.
`model`	touw	`ReasoningFast`	Model voor prompthook (scenarionaam of implementatienaam).
`maxRejections`	int	`3` (standaardagent)	Maximum aantal afwijzingen voordat stoppen wordt afgedwongen. Bereik: 1-25. Alleen van toepassing op prompt-type Stop-haken. Command-type Stop hooks hebben geen impliciete limiet. Wanneer meerdere prompthaken verschillende waarden opgeven, wordt het maximum gebruikt.

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.

Limiet	Waarde
Scriptgrootte	Maximaal 64 kB
Onderbreking	1-300 seconden
Maximum aantal afwijzingen (prompt haakjes stoppen)	1-25 (standaard: 3)
Ondersteunde script shebangs	`#!/bin/bash`, `#!/usr/bin/env python3`
Scriptuitvoeringsomgeving	Code-interpreter met sandbox

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:

Geef altijd een reden op bij het afwijzen. Behandelt afwijzingen zonder redenen als goedkeuringen.
Gebruik de juiste time-outs: Langlopende hooks vertragen de uitvoering van agenten.
Fouten probleemloos afhandelen: gebruik failMode: allow tenzij strikte afdwinging is vereist.
Wees specifiek met matchers: Te brede PostToolUse matchers kunnen prestatieproblemen veroorzaken.
Testhaken grondig: Haken die altijd weigeren kunnen lussen veroorzaken (verzacht door maxRejections).
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

Hulpbron	Wat u leert
Agenthook configureren (API)	Hooks instellen met behulp van REST API v2 en YAML

Vermogen	Hoe het verband houdt
Uitvoeringsmodi	Hooks vormen een aanvulling op de veiligheidsmaatregelen voor de uitvoeringsmodus. Modi bepalen wat er wordt uitgevoerd, hooks bepalen hoe goed deze wordt uitgevoerd.
Python-hulpprogramma's	Maak aangepaste hulpprogramma's waarmee hooks kunnen controleren en valideren.

Feedback

Is deze pagina nuttig?

Last updated on 2026-03-28