Hook dell'agente nell'Agente SRE di Azure

Gli hook sono checkpoint personalizzati che intercettano e controllano il comportamento dell'agente in momenti chiave. Usare hook per applicare controlli di qualità sulle risposte dell'agente, verificare e controllare l'utilizzo degli strumenti, bloccare le operazioni pericolose applicando criteri e impedire il completamento anticipato delle attività convalidando l'output dell'agente.

Problema

L'agente esegue attività in modo autonomo: analisi degli eventi imprevisti, esecuzione di strumenti e generazione di risposte. Ma l'autonomia senza supervisione crea rischi:

• Risposte incomplete: l'agente dice "fatto" prima di affrontare tutto ciò che hai richiesto.
• Utilizzo degli strumenti non controllato: non c'è visibilità su quali strumenti l'agente utilizza o sui risultati ottenuti.
• Nessuna imposizione dei criteri: le operazioni pericolose (comandi distruttivi, modifiche non autorizzate) procedono senza controllo.
• Gap di qualità: le risposte non contengono informazioni critiche perché non esiste alcun passaggio di convalida.

È necessario un modo per intercettare il comportamento dell'agente in momenti chiave senza rallentarlo o rimuoverne completamente l'autonomia.

Funzionamento dei ganci dell'agente

Gli hook sono checkpoint personalizzati associati a eventi specifici dell'agente. Quando viene generato un evento, l'hook valuta la situazione e decide se consentire o bloccare l'azione.

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

Sono attualmente supportati due eventi hook:

Due livelli di ganci

Gli hook funzionano a due livelli:

Entrambi i livelli possono coesistere. Se un hook a livello di agente e un hook a livello di agente personalizzato corrispondono entrambi allo stesso evento, entrambi vengono eseguiti. Gli hook a livello di agente vengono attivati per primi.

Tipi di esecuzione

È possibile implementare hook utilizzando un Large Language Model (LLM) o uno script shell.

Gli hook di prompt sono potenti per la valutazione soggettiva, ad esempio il controllo se una risposta risolve tutte le preoccupazioni dell'utente o verifica che un'indagine sia stata abbastanza approfondita. Usano il segnaposto $ARGUMENTS per ricevere il contesto completo dell'hook. Se $ARGUMENTS non è presente nel prompt, il contesto viene aggiunto automaticamente. Quando è disponibile la trascrizione di una conversazione, gli hook del prompt ricevono anche gli strumenti ReadFile e GrepSearch, permettendo al modello linguistico di grandi dimensioni di ragionare sulla storia completa della conversazione.

Gli hook dei comandi sono migliori per i controlli deterministici, ad esempio la convalida che una risposta contiene marcatori obbligatori, il blocco di comandi pericolosi o la registrazione dell'utilizzo degli strumenti in un sistema esterno.

Cosa rende questo approccio diverso

La tabella seguente confronta il comportamento dell'agente con e senza hook.

Gli hook non sostituiscono i controlli di sicurezza nella modalità di esecuzione: li completano. Le modalità di esecuzione controllano le operazioni che l'agente può eseguire. Gli hook controllano quanto bene funziona e cosa accade con i risultati.

Prima e dopo

Configurare gli hook

Il modo più semplice per creare hook consiste nell'interfaccia utente del portale:

1. Hook a livello di agente: Passare a Generatore → hook → selezionare Crea hook.
2. Hook a livello di agente personalizzato: andare a Canvas dell'agente → selezionare un agente personalizzato → Gestisci hook.

L'esempio seguente mostra una configurazione hook completa:

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

Formato della risposta Hook

Gli hook devono restituire JSON. Sono supportati due formati.

Formato semplice (consigliato per i prompt hook):

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

Formato espanso (consigliato per gli hook dei comandi):

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

Gli hook dei comandi possono anche usare i codici di uscita anziché l'output JSON:

Informazioni di riferimento sulla configurazione

Nella tabella seguente vengono descritte tutte le opzioni di configurazione hook disponibili.

Schema del contesto hook

Gli hook ricevono un contesto JSON strutturato sull'evento corrente. I ganci del prompt ricevono il contesto tramite il $ARGUMENTS segnaposto nel testo del prompt. Gli hook dei comandi ricevono il contesto come JSON in stdin.

Per entrambi i tipi di hook, il campo execution_summary contiene un percorso di file alla trascrizione della conversazione (non contenuto inline). Per gli hook di prompt, l'LLM riceve gli strumenti ReadFile e GrepSearch per accedere a questo file. Per i comandi hook, il file è disponibile nel percorso specificato nella sandbox.

Campi comuni

Tutti gli hook ricevono i campi seguenti:

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

Campi hook di interruzione

Gli hook di interruzione ricevono campi aggiuntivi sull'output finale dell'agente.

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

Campi hook di PostToolUse

Gli hook PostToolUse ricevono campi aggiuntivi sull'esecuzione dello strumento.

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

Limits

I limiti seguenti si applicano agli hook dell'agente.

Esempio: Controllare l'utilizzo di tutti gli strumenti

L'hook PostToolUse seguente registra ogni chiamata allo strumento e aggiunge un messaggio di contesto di controllo:

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

Il additionalContext campo viene aggiunto come messaggio utente nella conversazione, offrendo all'agente visibilità sull'audit trail.

Esempio: Richiedi un marcatore di completamento

L'hook di interruzione seguente rifiuta le risposte che non terminano con "Attività completata".:

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

Procedure consigliate

Seguire queste linee guida quando si configurano gli hook dell'agente:

1. Fornire sempre un motivo quando si rifiuta. Trattare i rifiuti senza motivazioni come approvazioni.
2. Usare timeout appropriati: gli hook a esecuzione prolungata rallentano l'esecuzione dell'agente.
3. Gestire gli errori in modo elegante: usare failMode: allow a meno che non sia necessaria un'applicazione rigorosa.
4. Essere specifici con i matcher: i matcher PostToolUse eccessivamente estesi possono causare problemi di prestazioni.
5. Testare gli hook accuratamente: gli hook che rifiutano sempre possono causare cicli (mitigati da maxRejections).
6. Accedere a stderr: usare stderr per il debug dell'output. Il sistema analizza stdout come risultato dell'hook.

Prova pratica

Lo screenshot seguente mostra in azione un gancio Stop. L'agente risponde inizialmente con solo "4", ma l'hook rifiuta la risposta perché manca il marcatore di completamento. L'agente continua quindi e aggiunge il marcatore.

Inizia subito

Contenuti correlati