Esercitazione: Configurare gli hook dell'agente (API) nell'ambiente Azure SRE.

Suggerimento

Preferisce l'interfaccia utente del portale? È ora possibile creare e gestire hook direttamente nel portale senza usare l'API REST. Il portale fornisce un modulo visivo e un editor di codice. Non curl sono necessari comandi.

In questa esercitazione si crea un agente personalizzato con un hook Stop che forza l'agente ad aggiungere un marcatore di completamento a ogni risposta. Configurare l'hook tramite l'API REST e quindi testarlo nel playground del portale.

Tempo stimato: 15 minuti

Annotazioni

Hook a livello di agente e hook a livello di agente personalizzato: questa esercitazione crea hook in un agente personalizzato (hook a livello di agente personalizzato). Questi hook vengono attivati solo quando viene eseguito l'agente personalizzato specifico.

Per creare hook a livello di agente che si applicano all'intero agente (tutti i thread, tutti gli agenti personalizzati), usare Builder>Hooks nel portale.

livello Modalità di creazione Ambito
Livello agente Portale: Hook del generatore > Si applica a tutti i thread e agli agenti personalizzati
Livello agente personalizzato API REST (questa esercitazione) o portale: Agent Canvas > Agente personalizzato > Gestisci ganci Si applica solo a un agente personalizzato

In questa esercitazione apprenderai a:

  • Creare un agente personalizzato con un hook Stop usando l'API REST
  • Testare il comportamento dell'hook nell'area di test del portale
  • Aggiungere un hook PostToolUse per l'utilizzo degli strumenti di controllo
  • Bloccare comandi pericolosi con un gancio di politica

Prerequisiti

  • Un agente SRE di Azure in stato in esecuzione
  • curl per chiamare l'API REST
  • Interfaccia della riga di comando di Azure ha eseguito l'accesso (az login) per ottenere un token di accesso

Informazioni sul formato dell'API hook

Questa esercitazione usa l'API REST v2 per creare hook in un agente personalizzato. La scheda dell'editor YAML del portale mostra il formato v1 e non visualizza gli hook configurati tramite l'API, ma gli hook sono ancora attivi. È possibile verificarli nella pagina Generatore>Hook o Testa playground.

Suggerimento

Quando usare l'API rispetto al portale:

  • Portale (hook > del Generatore): ideale per gli hook a livello di agente in forma visiva. Non è necessario alcun codice.
  • API (questa esercitazione): ideale per hook a livello di agente personalizzato, pipeline CI/CD o gestione a livello di codice.

Trovare l'URL DELL'API dell'agente

L'URL di base dell'API dell'agente segue questo modello:

https://{agent-name}--{hash}.{hash}.{region}.azuresre.ai

Per trovarlo:

  1. Aprire sre.azure.com e selezionare l'agente.
  2. Nella barra laterale sinistra, selezionare Builder>Agent Canvas.
  3. Aprire gli strumenti di sviluppo del browser (F12 o fare clic con il pulsante destro del mouse su > Controlla).
  4. Passare alla scheda Rete , filtrare in base a "api" e cercare le richieste a un URL che termina con .azuresre.ai.
  5. L'URL di base è tutto prima di /api/....

In alternativa, controllare l'attributo src nella scheda Elementi . Cercare un oggetto <iframe> il cui src inizio con https://{agent-name}--.

Ottenere un token di accesso

Eseguire il comando seguente per ottenere un token di accesso per l'API dell'agente SRE:

TOKEN=$(az account get-access-token \
  --resource <RESOURCE_ID> \
  --query accessToken -o tsv)

Creare un agente personalizzato con un hook Stop

Questo passaggio crea un agente personalizzato denominato my_hooked_agent con un hook Stop che controlla se la risposta termina con === RESPONSE COMPLETE ===. Se manca il marcatore, l'hook rifiuta la risposta e indica all'agente di aggiungere il marcatore.

AGENT_URL="https://your-agent--xxxxxxxx.yyyyyyyy.region.azuresre.ai"

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ]
    }
  }
}
EOF

Si riceve HTTP 202 Accettato con la configurazione completa dell'agente nel corpo della risposta.

L'esempio seguente illustra la stessa configurazione nel formato YAML v2 per riferimento:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant. Be concise.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check the agent response below.

          $ARGUMENTS

          Does it end with === RESPONSE COMPLETE ===?
          If yes: {"ok": true}
          If no: {"ok": false, "reason": "Add === RESPONSE COMPLETE === at the end."}
        timeout: 30

Funzionamento dell'hook Stop

L'hook Stop valuta la risposta dell'agente prima di tornare all'utente:

  • Sostituisce $ARGUMENTS con il contesto hook JSON, che include la risposta finale dell'agente.
  • LLM valuta il prompt e restituisce {"ok": true} o {"ok": false, "reason": "..."}.
  • Se rifiutato, l'agente continua a operare una volta che il motivo è stato inviato come messaggio utente.
  • Dopo tre rifiuti (impostazione predefinita), l'agente si arresta.

Testare l'hook nel portale

Per testare l'hook Stop, seguire questa procedura:

  1. Andare all'agente nel portale e selezionare Generatore>Canvas dell'agente.

  2. Selezionare il pulsante di opzione Testa playground.

  3. Selezionare l'elenco a discesa Subagent/Tool , trovare my_hooked_agent e selezionare Applica.

    Testare il playground con l'agente associato selezionato.

  4. Digitare What is 2+2? nella chat e selezionare Invia.

Guarda cosa succede:

  • L'agente risponde prima con 4.
  • L'hook Stop valuta e rifiuta la risposta (nessun marcatore di completamento).
  • Viene visualizzato un passaggio del Processo di pensiero in cui l'agente continua.
  • Viene visualizzata la risposta finale: 4 === RESPONSE COMPLETE ===.

Risultato del hook di terminazione che mostra che l'agente aggiunge il marcatore RESPONSE COMPLETE dopo il rifiuto iniziale.

Il gancio ha funzionato. Ha obbligato l'agente ad aggiungere il marcatore prima dell'arresto.

Aggiungere un hook PostToolUse per il controllo

Aggiungere un hook PostToolUse che registra ogni strumento usato dall'agente. Aggiornare lo stesso agente inviando una nuova PUT richiesta con entrambi gli hook:

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ],
      "PostToolUse": [
        {
          "type": "command",
          "matcher": "*",
          "timeout": 30,
          "failMode": "allow",
          "script": "#!/usr/bin/env python3\nimport sys, json\ncontext = json.load(sys.stdin)\ntool = context.get('tool_name', 'unknown')\nprint(json.dumps({'decision': 'allow', 'hookSpecificOutput': {'additionalContext': f'[AUDIT] {tool} executed.'}}))"
        }
      ]
    }
  }
}
EOF

matcher: "*" significa che questo hook viene eseguito per ogni chiamata di strumento. Lo script registra il nome dello strumento e inserisce un [AUDIT] messaggio nella conversazione.

Per testare l'hook, porre all'agente una domanda che attiva uno strumento (ad esempio, "Esegui echo hello").

Blocca comandi pericolosi

Aggiungere un secondo hook PostToolUse che blocca rm -rf, sudoe chmod 777:

PostToolUse:
  # Audit hook (runs for all tools)
  - type: command
    matcher: "*"
    timeout: 30
    failMode: allow
    script: |
      #!/usr/bin/env python3
      import sys, json
      context = json.load(sys.stdin)
      tool = context.get('tool_name', 'unknown')
      print(json.dumps({"decision": "allow",
        "hookSpecificOutput": {"additionalContext": f"[AUDIT] {tool} executed."}}))

  # Policy hook (only for shell tools)
  - 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', '')
      for pattern in [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']:
          if re.search(pattern, command):
              print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
              sys.exit(0)
      print(json.dumps({"decision": "allow"}))

Differenze principali rispetto all'hook di controllo:

  • matcher: "Bash|ExecuteShellCommand" viene eseguito solo per gli strumenti della shell (lo schema è ancorato come ^(Bash|ExecuteShellCommand)$).
  • failMode: block blocca il risultato dello strumento se lo script stesso si arresta in modo anomalo (modalità strict).
  • Restituisce "block" con un motivo quando viene trovato uno schema pericoloso.

Formati di risposta hook

I collegamenti del prompt e i collegamenti dei comandi utilizzano formati di risposta differenti.

Hook di prompt

Gli hook prompt restituiscono codice JSON semplice:

{"ok": true}

{"ok": false, "reason": "Please fix X."}

Hook di comando

Gli hook dei comandi restituiscono JSON espanso:

{"decision": "allow"}

{"decision": "block", "reason": "Dangerous command."}

{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Audit note."}}

Gli hook dei comandi possono anche usare codici di uscita anziché JSON:

Codice di uscita Comportamento
0 senza output Permetti
0 con JSON Analizzare il codice JSON
2 Blocco (stderr diventa la causa)
Altro Torna a failMode

Attenzione

Un rifiuto senza motivo viene considerato come approvazione. Si deve sempre includere reason quando si rifiuta.

Verificare

Dopo aver configurato e testato gli hook, verificare le condizioni seguenti:

  • È possibile configurare hook a livello di agente personalizzato usando l'API REST v2. Si applicano solo all'agente personalizzato.
  • È possibile creare hook di livello agente in Generator > Hooks. Si applicano all'intero agente.
  • Il gancio di arresto fa sì che l'agente aggiunga il marcatore === RESPONSE COMPLETE === prima di fermarsi.
  • L'hook di auditing PostToolUse registra i messaggi dei log [AUDIT] per le chiamate agli strumenti.
  • Il hook delle regole blocca comandi pericolosi come rm -rf e sudo.

Risoluzione dei problemi

Nella tabella seguente sono elencati i problemi e le soluzioni comuni per gli hook dell'agente.

Problema Soluzione
Hook non visibili nella scheda YAML del portale Previsto: la scheda YAML mostra solo v1. Gli hook a livello di agente personalizzati creati tramite l'API sono attivi e visibili in Builder>Hook o nel playground.
Unsupported kind: ExtendedAgent Utilizzare l'endpoint v2: PUT /api/v2/extendedAgent/agents/{name}.
Handoffs cannot be null Aggiungere "handoffs": [] al payload JSON.
Hook non ha alcun effetto Includere un campo reason quando si rifiuta. Senza di esso, il rifiuto viene considerato come approvazione.
L'agente è in loop infinito Inferiore maxRejections (impostazione predefinita: 3, intervallo: 1-25).

Passo successivo

Informazioni sugli hook dell'agente.

Contenuti correlati

  • Last updated on