Condividi tramite

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 chiedono domande come "mostra gli errori degli ultimi 7 giorni", l'agente sostituisce il parametro ed esegue la query esatta sul database di Esplora dati di Azure.

In questa esercitazione apprenderai a:

  • Creare uno strumento Kusto nel generatore di subagent
  • Definire una query KQL con parametri
  • Testare la query nel portale
  • Collega lo strumento a un subagente e verificalo nel campo di prova

Tempo stimato: 15 minuti

Prerequisiti

Prima di iniziare, verificare di disporre di quanto segue:

  • 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.

Aprire il generatore di subagent in cui si creano e si gestiscono 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 Generatore subagente.

Screenshot del generatore di subagent che mostra la visualizzazione canvas con schede subagent.

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.

Screenshot del menu Crea che mostra il sottomenu Strumento con l'opzione dello strumento Kusto.

Compilare i dettagli dello strumento

Completare il modulo con la configurazione dello strumento.

Campo Valore Descrizione
Nome strumento QueryAppLogs Informazioni su come l'agente fa riferimento a questo strumento.
Descrizione "Eseguire query sulla tabella AppLogs per individuare gli errori nell'intervallo di tempo specificato" Quando l'agente deve usare questo strumento.
Connettore (selezionare il connettore Kusto) Connessione da usare di Azure Data Explorer.
Banca dati (popolato automaticamente dall'URL del connettore) Il nome del tuo database.
Quesito Vedi l'esempio seguente. Query KQL con parametri.

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.

Screenshot del modulo dello strumento Kusto con la query e il parametro riempiti.

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.

Screenshot del test dello strumento che mostra il tempo di esecuzione e lo stato di esito positivo.

Il test mostra il tempo di esecuzione e conferma che la query viene eseguita. Anche se la query restituisce zero righe, un segno di spunta verde indica che la sintassi della query è valida.

Creare lo strumento

Selezionare Crea per salvare lo strumento Kusto.

Screenshot della conferma della creazione riuscita dello strumento.

Aggiungere lo strumento a un subagent

Lo strumento viene creato ma non ancora collegato a un subagente. Collegarlo in modo che l'agente possa usarlo.

  1. Nella visualizzazione Canvas trova il sottoagente.
  2. Selezionare il + pulsante sul lato destro della scheda subagent.
  3. Selezionare Aggiungi strumenti esistenti.
  4. Controlla lo strumento Kusto dall'elenco.
  5. Selezionare Aggiungi strumenti.

Screenshot della visualizzazione canvas che mostra la scheda del subagente con il pulsante Aggiungi sul lato destro.

Il conteggio degli strumenti nella scheda del subagente 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 il sottoagente dall'elenco a discesa.
  3. Chiedi: "Mostra errori degli ultimi 7 giorni"
  4. L'agente richiama lo strumento con timeRange = 7d.

Screenshot del playground di test che mostra i risultati della query Kusto con voci di errore dalla tabella AppLogs.

Dovresti vedere l'agente chiamare lo strumento Kusto e restituire i risultati dell'interrogazione. La query esatta che hai scritto viene eseguita sul tuo 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.

Modalità Usare quando
Query La query è definita direttamente in YAML (più comune).
Function La logica di query viene archiviata come funzione nel cluster di Esplora dati di Azure.
Script La query si trova in un file esterno .kql . 
# 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)"

Passo successivo

Testare lo strumento nell'area di test

Contenuti correlati

  • Last updated on