Esercitazione: Creare e gestire hook nel portale

In questa esercitazione vengono creati due hook di governance usando il portale: un hook Stop che applica la formattazione dei dati (tabelle markdown con intestazioni grassetto) e un hook PostToolUse che blocca i comandi pericolosi della shell. Gli hook vengono configurati sia a livello di agente (si applica a tutti i thread e ai subagenti) che al livello di subagente (si applica a un subagente specifico).

Tempo stimato: 10 minuti

In questa esercitazione apprenderai a:

Prerequisiti

• Un agente SRE di Azure in stato in esecuzione
• Ruolo collaboratore o superiore nella risorsa agente SRE

Comprendere dove si trovano gli hook nel portale

I ganci operano su due livelli. Comprendere questa distinzione è un concetto chiave dell'architettura.

Creare hook a livello di agente

Gli hook a livello di agente si applicano all'intero agente, inclusi tutti i thread e tutti i subagenti. Hanno modalità di attivazione che controllano quando sono attive.

Apri la pagina Hooks

Seguire questa procedura per passare alla pagina Hooks.

1. Passare a sre.azure.com e selezionare l'agente.
2. Nella barra laterale espandere Generatore.
3. Selezionare Hooks.

Viene visualizzata l'intestazione Hook con una descrizione, un pulsante Crea hook e una griglia di dati vuota (o un elenco di hook esistenti).

Creare un hook Stop

Un hook Stop viene attivato quando l'agente sta per restituire una risposta finale. Usarlo per convalidare la qualità della risposta e applicare regole di formattazione.

1. Selezionare Crea hook.

2. Compila i campi del modulo

   Campo	Valore
   Nome	require-table-format
   Tipo di evento	Stop
   Modalità di attivazione	Sempre
   Descrizione	Assicura che le risposte presentino dati strutturati come tabelle markdown con intestazioni in grassetto

3. In Definizione Hook, mantenere Tipo di Hook impostato su Prompt.

4. Mantenere Model impostato su Reasoning Fast (impostazione predefinita).

5. Nell'editor prompt immettere il testo seguente:

   Check the agent response below.
   
   $ARGUMENTS
   
   Does the response present any structured data (lists of items, comparisons, metrics) as a markdown table with **bold** column headers?
   If no structured data is present, approve.
   If structured data IS present as a table with bold headers: {"ok": true}
   If structured data is present but NOT formatted as a table: {"ok": false, "reason": "Reformat the structured data as a markdown table with **bold** column headers."}
   

6. Lasciare Timeout (sec) in 30, modalità errore in Allow e Numero max rifiuti in 3.

7. Seleziona Salva.

La finestra di dialogo viene chiusa con una notifica di esito positivo. L'hook viene visualizzato nella griglia dati con Tipo di evento Arresta e Attivazione sempre.

Testare l'hook Stop

Seguire questa procedura per verificare che l'hook stop funzioni correttamente.

1. Nella barra laterale selezionare Chat.
2. Digitare Confrontare i vantaggi e i svantaggi di Python e Go per la compilazione di microservizi e selezionare Invia.
3. Guardare la risposta dell'agente:
   • L'agente risponde inizialmente con un confronto di testo normale.
   • L'hook Stop valuta e rifiuta la risposta perché i dati non si trovano in una tabella.
   • L'agente riscrive la sua risposta in una tabella markdown con intestazioni in grassetto.

La risposta finale presenta il confronto come tabella formattata simile all'esempio seguente:

Creare un hook PostToolUse

Un hook PostToolUse viene attivato al termine dell'esecuzione di uno strumento. Usarlo per controllare l'utilizzo degli strumenti, bloccare comandi pericolosi o aggiungere contesto aggiuntivo.

1. Tornare a Builder>Hook.

2. Selezionare Crea hook.

3. Compilare il modulo:

   Campo	Valore
   Nome	block-dangerous-commands
   Tipo di evento	Uso dello strumento Post
   Modalità di attivazione	Sempre
   Descrizione	Blocca rm -rf, sudo e chmod 777 nei comandi della shell
   Tipo di hook	Comando
   Tool matcher	Bash\|ExecuteShellCommand

4. Selezionare Python come linguaggio di script.

5. Nell'editor di script immettere lo script seguente:

   #!/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"}))
   

6. Imposta Modalità di errore su Blocca (se lo script si arresta in modo anomalo, il risultato dello strumento viene bloccato).

7. Seleziona Salva.

Entrambi gli hook ora vengono visualizzati nella griglia dei dati Hook.

Testare il gancio PostToolUse

Seguire questa procedura per verificare che l'hook PostToolUse funzioni correttamente.

1. Nella barra laterale selezionare Chat.
2. Chiedere all'agente di eseguire un comando sicuro: "Esegui echo hello". L'hook consente questo comando.
3. Chiedere all'agente di eseguire un comando pericoloso: "Eseguire rm -rf /tmp/test". L'hook blocca questo comando.

Il comando safe viene eseguito normalmente. Il comando pericoloso viene bloccato e l'agente riceve un messaggio che spiega perché.

Modificare ed eliminare hook a livello di agente

È possibile modificare o rimuovere hook esistenti dalla griglia dei dati Hook.

• Modifica: selezionare l'icona di modifica in qualsiasi riga hook nella griglia dei dati, modificare i campi e selezionare Salva.
• Elimina: selezionare la casella di controllo accanto agli hook da rimuovere, selezionare Elimina sulla barra degli strumenti e confermare.

La griglia dei dati riflette immediatamente le modifiche apportate.

Creare hook a livello di subagente

Gli hook a livello di subagent vengono configurati direttamente nella definizione di un subagente. Si applicano solo quando viene eseguito un subagente specifico, non all'agente principale né ad altri subagenti.

Aprire il pannello dei hook del sottoagente

Seguire questa procedura per accedere alla configurazione hook per un subagent specifico.

1. Nella barra laterale espandere Generatore e selezionare Generatore subagente.
2. Selezionare un subagente esistente per modificarlo oppure selezionare Crea per avviarne uno nuovo.
3. Nel modulo subagent, vai giù fino alla sezione Hooks.
4. Seleziona Gestisci Hooks.

Si apre un pannello laterale con le sezioni Stop e Uso dello strumento Post. Se non sono configurati hook, vengono visualizzati stati vuoti con testo di guida.

Aggiungere un hook a un subagent

La procedura seguente aggiunge un hook Stop che garantisce che questo subagente risponda sempre con una sezione di riepilogo.

1. Nel pannello Gestisci hook selezionare Aggiungi hook nella parte bassa del pannello.

2. Nella finestra di dialogo compilare il modulo hook:

   Campo	Valore
   Tipo di evento	Stop
   Tipo di hook	Rapido
   Richiesta	Check the response below. $ARGUMENTS Does it include a clear summary section at the end? If yes: {"ok": true} If no: {"ok": false, "reason": "Add a Summary section at the end of your response."}
   Timeout (sec)	30
   Modalità errore	Permetti
   Numero massimo di rifiuti	3

3. Selezionare Salva sull'hook.

4. Selezionare Crea (o Salva) nel subagente per salvare la configurazione completa.

Il gancio viene visualizzato nel pannello Gestisci ganci nella sezione Arresta. Il modulo subagent mostra Manage Hooks (1) sul pulsante.

Gestire hook per thread

Gli hook a livello di agente con l'attivazione sempre sono attivi in ogni conversazione per impostazione predefinita. È necessario attivare manualmente gli hook con l'attivazione on demand per ogni thread.

Attivare/disattivare hook in una conversazione

Seguire questa procedura per attivare o disattivare hook in un thread specifico.

1. Aprire un thread di chat .
2. Selezionare il + pulsante nel piè di pagina della chat.
3. Selezionare Gestisci Hook.
4. Attivare o disattivare gli hook per il thread corrente.

È possibile disattivare temporaneamente gli hook Always . È possibile attivare hook on demand quando necessario. Non è possibile attivare o disattivare gli hook di sistema necessari.

Le modifiche agli hook diventano effettive immediatamente nel thread corrente.

Risoluzione dei problemi

Nella tabella seguente sono elencati i problemi e le soluzioni comuni durante la creazione e la gestione degli hook nel portale.

Passo successivo

Contenuti correlati

• Panoramica delle funzionalità hook dell'agente
• Esercitazione: Configurare gli hook dell'agente tramite l'API REST
• Modalità di esecuzione