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:

Event Si attiva quando Cosa puoi fare
Stop Agent sta per restituire una risposta finale Convalidare la completezza, rifiutare e forzare l'agente a continuare
PostToolUse Uno strumento termina correttamente l'esecuzione Controllare l'utilizzo, bloccare i risultati, inserire un contesto aggiuntivo

Due livelli di ganci

Gli hook funzionano a due livelli:

livello Dove configurare Ambito
Livello agente Builder → Hook nel portale Si applica all'intero agente, inclusi tutti i thread e tutti gli agenti personalizzati
Livello agente personalizzato Agent Canvas → Agente Personalizzato → Gestire Hook o tramite l'API REST v2 Si applica solo quando viene eseguito l'agente personalizzato specifico

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.

Tipo Come funziona Ideale per
Richiesta Un LLM valuta il prompt e restituisce una decisione JSON Convalida dettagliata ("Questa risposta è completa?")
Comando Uno script bash o Python viene eseguito in un ambiente in modalità sandbox Controlli deterministici, imposizione dei criteri, verifica

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.

Senza ganci Con ganci
L'agente decide quando è "completato" Definisci cosa significa "fatto"
L'utilizzo degli strumenti è invisibile È possibile controllare ogni chiamata di strumento
I comandi pericolosi procedono silenziosamente. L'applicazione delle politiche li blocca automaticamente
La qualità dipende solo dall'ingegneria dei prompt I controlli di qualità automatizzati intercettano le lacune

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

Scenario Prima Dopo
Qualità della risposta L'agente si arresta quando ritiene che il suo compito sia completato. L'hook Stop convalida l'completezza prima che la risposta raggiunga gli utenti
Visibilità degli strumenti Nessun tracciamento di controllo dell'esecuzione dello strumento Gli hook di PostToolUse registrano e verificano ogni chiamata di strumento
Applicazione dei criteri I comandi pericolosi vengono eseguiti senza controllo Gli script bloccano rm -rf, sudoe altri modelli a rischio automaticamente
Controllo di qualità L'ingegneria dei prompt è l'unica leva Gli hook basati su LLM valutano le sfumature; Gli script applicano regole deterministiche

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.

Suggerimento

È anche possibile configurare hook tramite l'API REST v2 usando PUT /api/v2/extendedAgent/agents/{agentName}. Il formato YAML nella sezione seguente illustra lo schema di configurazione completo. Per altre informazioni, vedere l'esercitazione sull'API.

La scheda YAML canvas agente visualizza il formato v1 e non mostra hook. Usa la pagina Hook sotto Generatore per visualizzare e gestire gli 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:

Codice di uscita Comportamento
0 senza output Consenti (nessuna obiezione)
0 con JSON Analizzare JSON per la decisione
2 Blocca sempre. stderr diventa la causa
Altro Usa l'impostazione failMode (allow o block)

Attenzione

Per gli hook stop, un rifiuto senza motivo viene considerato come approvazione e l'agente si arresta normalmente. Specificare sempre un reason campo quando si rifiuta.

Annotazioni

È possibile definire più hook per lo stesso evento. Per PostToolUse, ogni hook con un modello corrispondente matcher viene eseguito in modo indipendente. Se più hook forniscono additionalContext, il contesto dell'ultimo hook viene inserito nella conversazione.

Informazioni di riferimento sulla configurazione

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

Opzione Tipo Impostazione predefinita Descrizione
type string prompt prompt oppure command
prompt string - Testo del prompt LLM (obbligatorio per gli hook di richiesta). Usare $ARGUMENTS per l'inserimento del contesto.
command string - Comando shell inline (per gli hook dei comandi, che si escludono a vicenda con script).
script string - Script su più righe (per hook di comando, che si escludono a vicenda con command).
matcher string - Modello regex per i nomi degli strumenti (obbligatorio per gli hook PostToolUse). * corrisponde a tutti gli strumenti. I pattern sono ancorati come ^(pattern)$ con distinzione tra maiuscole e minuscole. Vuoto o Null non corrisponde a nulla.
timeout int 30 Timeout di esecuzione in secondi (deve essere positivo; valori superiori a 300 vengono contrassegnati durante la convalida CLI).
failMode string allow Come gestire gli errori di hook: allow o block.
model string ReasoningFast Modello per gli hook di richiesta (nome dello scenario o nome della distribuzione).
maxRejections int 3 (impostazione predefinita agente) Numero massimo di rifiutazioni prima di forzare l'arresto. Intervallo: 1-25. Si applica solo agli hook stop di tipo prompt. Gli hook stop di tipo comando non hanno limiti impliciti. Quando più hook prompt specificano valori diversi, viene usato il valore massimo.

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.

Limit Valore
Dimensioni script 64 KB massimo
Interruzione temporanea 1-300 secondi
Numero massimo di rifiuti (hook di interruzione prompt) 1-25 (impostazione predefinita: 3)
Script shebang supportati #!/bin/bash, #!/usr/bin/env python3
Ambiente di esecuzione script Interprete di codice in modalità sandbox

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.

Screenshot che mostra un hook di interruzione in azione in cui la risposta dell'agente è decorata con un marcatore di completamento dopo il rifiuto dell'hook.

Inizia subito

risorsa Cosa imparerai
Configurare gli hook dell'agente (API) Configurare gli hook usando l'API REST v2 e YAML

Contenuti correlati

Capability Come è collegato
Modalità di esecuzione Gli hook completano i controlli di sicurezza in modalità esecuzione. Le modalità controllano cosa viene eseguito, gli hook controllano quanto bene viene eseguito.
Strumenti Python Creare strumenti personalizzati che gli hook possono controllare e convalidare.
  • Last updated on