Esercitazione: Creare uno strumento Kusto nell'agente SRE di Azure

In questa esercitazione viene creato uno strumento Kusto con parametri che esegue query KQL esatte con risultati deterministici e ripetibili. Quando gli utenti pongono domande come "mostra errori degli ultimi sette giorni", l'agente sostituisce il parametro ed esegue la query esatta sul database di Esplora dati di Azure.

In questa esercitazione apprenderai a:

Tempo stimato: 15 minuti

Prerequisiti

Prima di iniziare, verificare di aver soddisfatto i prerequisiti seguenti:

• Un cluster di Esplora dati di Azure con il ruolo AllDatabasesViewer concesso all'identità gestita dell'agente. Per altre informazioni, vedere Prerequisiti degli strumenti Kusto.
• Un connettore Kusto configurato. Per altre informazioni, vedere Configurare un connettore Kusto.
• Accesso a Builder nel portale dell'agente SRE di Azure.

Andare al canvas dell'agente

Aprire l'area di disegno agente in cui creare e gestire gli strumenti.

1. Aprire il portale dell'agente SRE.
2. Seleziona il tuo agente.
3. Selezionare Builder nel riquadro di spostamento a sinistra.
4. Selezionare Agent Canvas.

Aprire il modulo di creazione dello strumento

Avviare il processo di creazione dello strumento dalla barra degli strumenti.

1. Selezionare l'elenco a discesa Crea nella barra degli strumenti superiore.
2. Selezionare Strumento>Kusto.

Compilare i dettagli dello strumento

Completare il modulo con la configurazione dello strumento.

Immettere la query di esempio seguente:

AppLogs
| where Timestamp > ago(##timeRange##)
| where Level == "Error"
| order by Timestamp desc
| take 10

La ##timeRange## sintassi crea un parametro. Quando un utente chiede "mostra gli errori delle ultime 24 ore", l'agente compila timeRange = 24h.

Aggiungere il parametro

Definire il parametro usato dalla query.

1. Scorrere fino alla sezione Parametri .
2. Selezionare Aggiungi parametro.
3. Immettere i valori seguenti:
   • Nome: timeRange
   • Tipo: Stringa
   • Descrizione: "L'intervallo di tempo da considerare (ad esempio, 1h, 24h, 7d)"

Il parametro viene visualizzato nella tabella Parameters sotto la query.

Testare la query

Verificare che la query funzioni correttamente prima del salvataggio.

1. Selezionare Test nella parte inferiore del modulo.
2. Immettere un valore di test per timeRange (ad esempio, 7d).
3. Verificare che la query venga eseguita correttamente.

Viene visualizzato il tempo di esecuzione e una spunta verde che conferma l'esecuzione della query. Anche se la query restituisce zero righe, il segno di spunta indica che la sintassi della query è valida.

Creare lo strumento

Selezionare Crea per salvare lo strumento Kusto.

Aggiungere lo strumento a un agente personalizzato

Hai creato il tuo strumento ma non lo hai collegato a un agente personalizzato. Collegare lo strumento in modo che l'agente possa usarlo.

1. Nella visualizzazione Canvas trova l'agente personalizzato.
2. Selezionare il pulsante + sul lato destro della scheda dell'agente personalizzato.
3. Selezionare Aggiungi strumenti esistenti.
4. Controllare lo strumento Kusto dall'elenco.
5. Selezionare Aggiungi strumenti.

Il numero di strumenti nella scheda dell'agente personalizzato aumenta dopo l'aggiunta.

Verificare lo strumento nell'area di prova

Verificare che l'agente richiami correttamente lo strumento Kusto.

1. Selezionare Test Playground nella barra di navigazione a sinistra.
2. Selezionare l'agente personalizzato dall'elenco a discesa.
3. Chiedi: "Mostra errori degli ultimi sette giorni"
4. L'agente richiama lo strumento con timeRange = 7d.

Dovresti vedere l'agente chiamare lo strumento Kusto e restituire i risultati dell'interrogazione. La query esatta che è stata scritta viene eseguita sul cluster.

Sintassi dei parametri

Usare ##parameterName## o $parameterName per contrassegnare i segnaposto dei parametri nelle query:

query: |-
  AppExceptions
  | where TimeGenerated > ago(##timeRange##)
  | where ServiceName == "$serviceName"

Entrambe le sintassi funzionano in modo identico. L'agente sostituisce i valori in fase di esecuzione.

Modalità di esecuzione

Nella tabella seguente vengono descritte le modalità di esecuzione disponibili per gli strumenti Kusto.

# Function mode example
spec:
  type: KustoTool
  mode: Function
  function: GetRecentErrors

# Script mode example
spec:
  type: KustoTool
  mode: Script
  file: queries/complex-analysis.kql

Esempio: Strumento di correlazione per l'implementazione

La definizione YAML seguente crea uno strumento Kusto che correla le distribuzioni con un servizio e un intervallo di tempo specificato.

api_version: azuresre.ai/v2
kind: ExtendedAgentTool
metadata:
  name: get-recent-deployments
spec:
  type: KustoTool
  connector: devops-logs
  mode: Query
  database: deployments
  description: "Get deployments in a time range for a service"
  toolMode: Auto
  query: |-
    Deployments
    | where TimeGenerated > ago(##timeRange##)
    | where ServiceName == "##serviceName##"
    | project TimeGenerated, Version, DeployedBy, Environment
    | order by TimeGenerated desc
  parameters:
    - name: serviceName
      type: string
      description: "Name of the service"
    - name: timeRange
      type: string
      description: "How far back to look (e.g., 1h, 24h)"

Modificare o eliminare uno strumento

È possibile modificare o rimuovere strumenti dopo la creazione.

Edit

1. Nel canvas dell'agente selezionare il nodo strumento per aprire il pannello informazioni.
2. Selezionare l'icona di modifica (matita) nell'intestazione del pannello.
3. Viene visualizzata la finestra di dialogo di modifica con le impostazioni correnti. Modificare la query, i parametri o il connettore.
4. Seleziona Salva.

Elimina

1. Selezionare il nodo dello strumento per aprire il pannello delle informazioni.
2. Selezionare il menu ⋯ (altre azioni) nell'intestazione del pannello.
3. Selezionare Elimina strumento.
4. Confermare l'eliminazione nella finestra di dialogo.

Passo successivo

Contenuti correlati

• Strumenti Kusto
• Creare uno strumento Python
• Agenti personalizzati