在這個教學中,你會建立一個參數化的 Kusto 工具,能執行精確的 KQL 查詢,並產生確定性且可重複的結果。 當使用者詢問「顯示過去七天的錯誤」時,代理會替換參數,並對你的 Azure Data Explorer 資料庫執行精確查詢。
在本教學課程中,您將瞭解如何:
- 在 Agent Canvas 上建立一個 Kusto 工具
- 定義一個參數化的 KQL 查詢
- 在平台上測試查詢
- 將工具附加到自訂代理並在測試平台中進行驗證
預計時間:15分鐘
先決條件
開始之前,請確定您有下列必要條件:
- 已將 AllDatabasesViewer 角色授與 Agent 受控識別的 Azure Data Explorer 叢集。 欲了解更多資訊,請參閱 Kusto 工具的前置條件。
- Kusto 連接器已設定好。 更多資訊請參見 設置Kusto連接器。
- 在 Azure SRE Agent 入口網站中存取 建置 + 設定。
瀏覽至 Agent Canvas
打開 Agent Canvas,在那裡你可以建立和管理工具。
- 開啟 SRE代理入口。
- 選擇您的專員。
- 選擇 「建置+設定」,然後在左側導覽中展開 「工作流程 」。
- 選取 代理畫布。
打開工具建立表單
從工具列開始工具建立流程。
- 在上方工具列選擇 「建立 」下拉選單。
- 選擇 工具>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。
加入參數
定義你的查詢所使用的參數。
- 往下滑到 參數 區塊。
- 選擇 新增參數。
- 輸入下列值:
-
名稱:
timeRange - 類型:字串
- 說明:「要追溯多久(例如,1小時、24小時、7天)」
-
名稱:
該參數會出現在您的查詢下方的 參數 表中。
測試查詢
在儲存前,先驗證查詢是否成功執行。
- 請在表單底部選擇 「測試 」。
- 輸入一個測試
timeRange值(例如,7d)。 - 確認查詢是否成功執行。
你會看到執行時間和一個綠色勾號確認查詢順利執行。 即使查詢回傳零列,勾選標記表示查詢語法有效。
建立工具
選擇 建立 以儲存你的 Kusto 工具。
將工具加入自訂代理
你創建了工具,但沒有把它附加到自訂代理程式上。 把工具裝上,讓代理人能使用。
- 在 Canvas 檢視中,找到你的客製代理人。
- 選擇客製化代理卡上的右側按鈕 +。
- 選擇 新增現有工具。
- 從清單上選擇你的 Kusto 工具。
- 選擇 新增工具。
新增後,你的客製化代理卡上的工具數量會增加。
在遊樂場中驗證工具
測試代理是否正確呼叫你的 Kusto 工具。
- 移至建置 + 設定>工作流程>Agent 畫布,然後在視圖切換開關中選取測試遊樂場。
- 從下拉選單中選擇您的客製化代理人。
- 請求:「展示過去七天的錯誤紀錄」
- Agent 會以
timeRange = 7d調用您的工具。
你應該會看到客服打電話給你的 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
- 在 Agent Canvas 上,選擇工具節點以開啟資訊面板。
- 在面板標題中選擇 編輯 (鉛筆)圖示。
- 編輯對話框會顯示你目前的設定。 修改查詢、參數或連接器。
- 選取 [儲存]。
Delete
- 選擇工具節點以開啟資訊面板。
- 在面板標題中選擇 ...... (更多動作)選單。
- 選擇 刪除工具。
- 在對話方塊中確認刪除。
備註
當你刪除一個工具時,你會立即從使用該工具的自訂代理程式中移除它。