教學:在 Azure SRE Agent 中建立 Kusto 工具

在這個教學中,你會建立一個參數化的 Kusto 工具,能執行精確的 KQL 查詢,並產生確定性且可重複的結果。 當使用者詢問「顯示過去七天的錯誤」時,代理會替換參數,並對你的 Azure Data Explorer 資料庫執行精確查詢。

在本教學課程中,您將瞭解如何:

  • 在 Agent Canvas 上建立一個 Kusto 工具
  • 定義一個參數化的 KQL 查詢
  • 在平台上測試查詢
  • 將工具附加到自訂代理並在測試平台中進行驗證

預計時間:15分鐘

先決條件

開始之前,請確定您有下列必要條件:

  • 已將 AllDatabasesViewer 角色授與 Agent 受控識別的 Azure Data Explorer 叢集。 欲了解更多資訊,請參閱 Kusto 工具的前置條件。
  • Kusto 連接器已設定好。 更多資訊請參見 設置Kusto連接器。
  • 在 Azure SRE Agent 入口網站中存取 建置 + 設定。

打開 Agent Canvas,在那裡你可以建立和管理工具。

  1. 開啟 SRE代理入口。
  2. 選擇您的專員。
  3. 選擇 「建置+設定」,然後在左側導覽中展開 「工作流程 」。
  4. 選取 代理畫布。

顯示 Agent Canvas 畫布檢視與自訂 Agent 卡片的螢幕擷取畫面。

打開工具建立表單

從工具列開始工具建立流程。

  1. 在上方工具列選擇 「建立 」下拉選單。
  2. 選擇 工具>Kusto 工具。

Create 選單的截圖,顯示工具子選單與 Kusto 工具選項。

填寫工具細節

請填寫你的工具配置。

領域 價值 說明
工具名稱 QueryAppLogs 代理人如何引用這個工具。
說明 「查詢 AppLogs 表格中指定時間範圍內的錯誤」 代理人應該何時使用這個工具。
連接器 (選擇你的 Kusto 連接器) 要使用的 Azure Data Explorer 連線。
資料庫 (由連接器網址自動填充) 你的資料庫名稱。
查詢 請參閱下列範例。 你的 KQL 查詢含有參數。

請輸入以下範例查詢:

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

##timeRange## 語法會建立一個參數。 當有人問「顯示過去24小時的錯誤」時,客服人員會填寫 timeRange = 24h。

Kusto 工具表單的截圖,已填寫查詢和參數。

加入參數

定義你的查詢所使用的參數。

  1. 往下滑到 參數 區塊。
  2. 選擇 新增參數。
  3. 輸入下列值:
    • 名稱:timeRange
    • 類型:字串
    • 說明:「要追溯多久(例如,1小時、24小時、7天)」

該參數會出現在您的查詢下方的 參數 表中。

測試查詢

在儲存前,先驗證查詢是否成功執行。

  1. 請在表單底部選擇 「測試 」。
  2. 輸入一個測試 timeRange 值(例如, 7d)。
  3. 確認查詢是否成功執行。

工具測試截圖,顯示執行時間和成功狀態。

你會看到執行時間和一個綠色勾號確認查詢順利執行。 即使查詢回傳零列,勾選標記表示查詢語法有效。

建立工具

選擇 建立 以儲存你的 Kusto 工具。

顯示工具成功建立確認的螢幕擷取畫面。

將工具加入自訂代理

你創建了工具,但沒有把它附加到自訂代理程式上。 把工具裝上,讓代理人能使用。

  1. 在 Canvas 檢視中,找到你的客製代理人。
  2. 選擇客製化代理卡上的右側按鈕 +。
  3. 選擇 新增現有工具。
  4. 從清單上選擇你的 Kusto 工具。
  5. 選擇 新增工具。

Canvas 視圖截圖,顯示自訂代理卡,右側有新增按鈕。

新增後,你的客製化代理卡上的工具數量會增加。

在遊樂場中驗證工具

測試代理是否正確呼叫你的 Kusto 工具。

  1. 移至建置 + 設定>工作流程>Agent 畫布,然後在視圖切換開關中選取測試遊樂場。
  2. 從下拉選單中選擇您的客製化代理人。
  3. 請求:「展示過去七天的錯誤紀錄」
  4. Agent 會以 timeRange = 7d 調用您的工具。

測試平台的截圖顯示 Kusto 查詢結果,其中包含來自 AppLogs 表格的錯誤條目。

你應該會看到客服打電話給你的 Kusto 工具並回傳查詢結果。 你寫的查詢就是針對你的叢集執行的。

參數語法

在查詢中使用 ##parameterName## 或 $parameterName 標記參數佔位符:

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

兩種語法的運作方式完全相同。 代理在執行時替換數值。

執行模式

下表說明了 Kusto 工具可用的執行模式。

模式 何時使用
Query 最常見的是在 YAML 中內嵌定義查詢。
Function 將查詢邏輯以函式形式儲存在 Azure Data Explorer 叢集中。
Script 將查詢放入外部 .kql 檔案。
# Function mode example
spec:
  type: KustoTool
  mode: Function
  function: GetRecentErrors

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

範例:部署關聯工具

以下 YAML 定義建立了一個 Kusto 工具,將部署與指定的服務及時間範圍關聯起來。

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

編輯或刪除工具

你可以在創建後修改或移除工具。

Edit

  1. 在 Agent Canvas 上,選擇工具節點以開啟資訊面板。
  2. 在面板標題中選擇 編輯 (鉛筆)圖示。
  3. 編輯對話框會顯示你目前的設定。 修改查詢、參數或連接器。
  4. 選取 [儲存]。

Delete

  1. 選擇工具節點以開啟資訊面板。
  2. 在面板標題中選擇 ...... (更多動作)選單。
  3. 選擇 刪除工具。
  4. 在對話方塊中確認刪除。

備註

當你刪除一個工具時,你會立即從使用該工具的自訂代理程式中移除它。

下一個步驟