Freigeben über

Lernprogramm: Erstellen eines Kusto-Tools in Azure SRE-Agent

In diesem Lernprogramm erstellen Sie ein parametrisiertes Kusto-Tool, das genaue KQL-Abfragen mit deterministischen, wiederholbaren Ergebnissen ausführt. Wenn Benutzer Fragen wie "Fehler aus den letzten sieben Tagen anzeigen" stellen, ersetzt der Agent den Parameter und führt Ihre genaue Abfrage für Ihre Azure Data Explorer-Datenbank aus.

In diesem Tutorial erfahren Sie, wie:

  • Kusto-Tool im Agent Canvas erstellen
  • Definieren einer parametrisierten KQL-Abfrage
  • Testen der Abfrage im Portal
  • Fügen Sie das Tool an einen benutzerdefinierten Agenten an und überprüfen Sie es im Testumfeld.

Geschätzte Zeit: 15 Minuten

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über die folgenden Voraussetzungen verfügen:

  • Ein Azure Data Explorer-Cluster mit der AllDatabasesViewer-Rolle , die der verwalteten Identität des Agents gewährt wird. Weitere Informationen finden Sie unter kusto tools prerequisites.
  • Ein Kusto-Connector wurde konfiguriert. Weitere Informationen finden Sie unter Einrichten eines Kusto-Connectors.
  • Zugriff auf Generator im Azure SRE-Agent-Portal.

Öffnen Sie den Agent-Canvas, in dem Sie Tools erstellen und verwalten.

  1. Öffnen Sie das SRE-Agent-Portal.
  2. Wähle einen Agenten.
  3. Wählen Sie im linken Navigationsbereich den Generator aus.
  4. Wählen Sie "Agent Canvas" aus.

Screenshot der Agent-Canvas mit canvas-Ansicht mit benutzerdefinierten Agent-Karten.

Öffnen des Toolerstellungsformulars

Starten Sie den Toolerstellungsprozess über die Symbolleiste.

  1. Wählen Sie die Dropdownliste "Erstellen" in der oberen Symbolleiste aus.
  2. Wählen Sie das Tool Kusto>aus.

Screenshot des Menüs

Füllen Sie die Tooldetails aus.

Füllen Sie das Formular mit Ihrer Toolkonfiguration aus.

Feld Wert Beschreibung
Name des Tools QueryAppLogs Wie der Agent auf dieses Tool verweist.
Beschreibung Abfragen der AppLogs-Tabelle nach Fehlern im angegebenen Zeitraum Wenn der Agent dieses Tool verwenden soll.
Connector (Wählen Sie Ihren Kusto-Connector aus) Die zu verwendende Azure Data Explorer-Verbindung.
Datenbank (aus der Connector-URL automatisch ausgefüllt) Ihr Datenbankname.
Abfrage Siehe folgendes Beispiel. Ihre KQL-Abfrage mit Parametern.

Geben Sie die folgende Beispielabfrage ein:

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

Die ##timeRange## Syntax erstellt einen Parameter. Wenn jemand fragt, "Fehler aus den letzten 24 Stunden anzeigen", füllt der Agent timeRange = 24h aus.

Screenshot des Kusto-Toolformulars mit ausgefüllter Abfrage und Parameter.

Hinzufügen des Parameters

Definieren Sie den Parameter, den Ihre Abfrage verwendet.

  1. Scrollen Sie zum Abschnitt "Parameter ".
  2. Wählen Sie "Parameter hinzufügen" aus.
  3. Geben Sie die folgenden Werte ein:
    • Name: timeRange
    • Typ: Zeichenfolge
    • Beschreibung: "Wie weit in die Vergangenheit schauen (z. B. 1h, 24h, 7d)"

Der Parameter wird in der Parametertabelle unterhalb der Abfrage angezeigt.

Testen der Abfrage

Überprüfen Sie, ob die Abfrage vor dem Speichern erfolgreich ausgeführt wird.

  1. Wählen Sie unten im Formular "Testen" aus.
  2. Geben Sie einen Testwert für timeRange (z. B 7d. ) ein.
  3. Überprüfen Sie, ob die Abfrage erfolgreich ausgeführt wird.

Screenshot des Tooltests mit Ausführungszeit und Erfolgsstatus.

Sie sehen die Ausführungszeit und ein grünes Häkchen, das bestätigt, dass die Abfrage ausgeführt wird. Auch wenn die Abfrage null Zeilen zurückgibt, bedeutet das Häkchen, dass die Abfragesyntax gültig ist.

Tool erstellen

Wählen Sie "Erstellen" aus, um Ihr Kusto-Tool zu speichern.

Screenshot des Tools, das die Bestätigung erfolgreich erstellt hat.

Hinzufügen des Tools zu einem benutzerdefinierten Agent

Sie haben Ihr Tool erstellt, aber nicht an einen benutzerdefinierten Agent angefügt. Fügen Sie das Tool an, damit der Agent es verwenden kann.

  1. Suchen Sie in der Canvasansicht ihren benutzerdefinierten Agent.
  2. Wählen Sie die + Schaltfläche auf der rechten Seite der benutzerdefinierten Agent-Karte aus.
  3. Wählen Sie "Vorhandene Tools hinzufügen" aus.
  4. Überprüfen Sie Ihr Kusto-Tool in der Liste.
  5. Wählen Sie "Tools hinzufügen" aus.

Screenshot der Canvasansicht mit benutzerdefinierter Agent-Karte mit der Schaltfläche

Die Anzahl der Tools auf der benutzerdefinierten Agentenkarte erhöht sich, nachdem Sie etwas hinzugefügt haben.

Überprüfen des Tools in der Testumgebung

Testen Sie, dass der Agent Ihr Kusto-Tool richtig aufruft.

  1. Wählen Sie im linken Navigationsbereich " Test-Playground " aus.
  2. Wählen Sie Ihren benutzerdefinierten Agent aus der Dropdownliste aus.
  3. Frage: "Fehler aus den letzten sieben Tagen anzeigen"
  4. Der Agent ruft Ihr Tool mit timeRange = 7d.

Screenshot des Test-Playgrounds mit Kusto-Abfrageergebnissen mit Fehlereinträgen aus der AppLogs-Tabelle.

Der Agent sollte Ihr Kusto-Tool aufrufen und Abfrageergebnisse zurückgeben. Die von Ihnen erstellte exakte Abfrage wird gegen Ihren Cluster ausgeführt.

Parametersyntax

Verwenden Sie ##parameterName## oder $parameterName, um Parameterplatzhalter in Ihren Abfragen zu markieren:

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

Beide Syntaxen funktionieren identisch. Der Agent ersetzt Werte zur Laufzeit.

Ausführungsmodi

In der folgenden Tabelle werden die verfügbaren Ausführungsmodi für Kusto-Tools beschrieben.

Modus Verwenden Sie, wenn
Query Definieren Sie die Inlineabfrage in YAML (am häufigsten).
Function Speichern Sie die Abfragelogik als Funktion im Azure Data Explorer-Cluster.
Script Platzieren Sie die Abfrage in einer externen .kql Datei. 
# Function mode example
spec:
  type: KustoTool
  mode: Function
  function: GetRecentErrors

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

Beispiel: Bereitstellungskorrelationstool

Die folgende YAML-Definition erstellt ein Kusto-Tool, das Bereitstellungen mit einem angegebenen Dienst und einem bestimmten Zeitraum korreliert.

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)"

Bearbeiten oder Löschen eines Tools

Sie können Tools nach der Erstellung ändern oder entfernen.

Bearbeiten

  1. Wählen Sie auf der Agent-Canvas den Toolknoten aus, um den Infobereich zu öffnen.
  2. Wählen Sie das Bearbeitungssymbol (Bleistift) in der Bereichsüberschrift aus.
  3. Das Dialogfeld "Bearbeiten" wird mit ihren aktuellen Einstellungen geöffnet. Ändern Sie die Abfrage, Parameter oder den Connector.
  4. Wählen Sie Speichern aus.

Löschen

  1. Wählen Sie den Toolknoten aus, um den Infobereich zu öffnen.
  2. Wählen Sie im Bereichskopf das Menü ⋯ (weitere Aktionen) aus.
  3. Wählen Sie das Tool "Löschen" aus.
  4. Bestätigen Sie den Löschvorgang im Dialogfeld.

Hinweis

Wenn Sie ein Tool löschen, entfernen Sie es sofort aus allen benutzerdefinierten Agents, die das Tool verwenden.

Nächster Schritt

Testen des Tools in der Testumgebung

Verwandte Inhalte

  • Last updated on