チュートリアル: Azure SRE エージェントで Kusto ツールを作成する

このチュートリアルでは、確定的で反復可能な結果を持つ正確な KQL クエリを実行する、パラメーター化された Kusto ツールを作成します。 ユーザーが "過去 7 日間のエラーを表示する" などの質問をすると、エージェントはパラメーターを置き換え、Azure Data Explorer データベースに対して正確なクエリを実行します。

このチュートリアルでは、以下の内容を学習します。

推定時間: 15 分

前提条件

開始する前に、以下の前提条件を確認してください。

• エージェントのマネージド ID に付与された AllDatabasesViewer ロールを持つ Azure Data Explorer クラスター。 詳細については、「 Kusto ツールの前提条件」を参照してください。
• Kusto コネクタが構成されました。 詳細については、「 Kusto コネクタのセットアップ」を参照してください。
• Azure SRE エージェント ポータルで Builder にアクセスします。

エージェント キャンバスに移動する

ツールを作成および管理するエージェント キャンバスを開きます。

1. SRE エージェント ポータルを開きます。
2. エージェントを選択してください。
3. 左側のナビゲーションで [ビルダー ] を選択します。
4. [エージェント キャンバス] を選択します。

ツール作成フォームを開く

ツール バーからツールの作成プロセスを開始します。

1. 上部のツール バーの [ 作成 ] ドロップダウンを選択します。
2. ツール>Kusto ツールを選択します。

ツールの詳細を入力する

ツール構成に基づいてフォームに記入してください。

次のクエリ例を入力します。

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

##timeRange##構文では、パラメーターが作成されます。 誰かが「過去 24 時間のエラーを表示する」と尋ねると、エージェントは timeRange = 24hを入力します。

パラメーターを追加する

クエリで使用するパラメーターを定義します。

1. [パラメーター] セクションまでスクロールします。
2. [ パラメーターの追加] を選択します。
3. 次の値を入力します。
   • 名前: timeRange
   • 種類: 文字列
   • 説明: "見る距離 (例: 1h、24h、7d)"

このパラメーターは、クエリの下の [パラメーター] テーブルに表示されます。

クエリをテストする

保存する前に、クエリが正常に実行されることを検証します。

1. フォームの下部にある [テスト ] を選択します。
2. timeRangeのテスト値 (たとえば、7d) を入力します。
3. クエリが正常に実行されたことを確認します。

実行時間と、クエリの実行を確認する緑色のチェックマークが表示されます。 クエリから 0 行が返された場合でも、チェックマークはクエリ構文が有効であることを意味します。

ツールを作成する

[ 作成 ] を選択して Kusto ツールを保存します。

カスタム エージェントにツールを追加する

ツールを作成しましたが、カスタム エージェントにアタッチしませんでした。 エージェントがツールを使用できるようにツールをアタッチします。

1. キャンバス ビューで、カスタム エージェントを見つけます。
2. カスタム エージェント カードの右側にある [ + ] ボタンを選択します。
3. [ 既存のツールの追加] を選択します。
4. 一覧から Kusto ツールを確認します。
5. [ ツールの追加] を選択します。

カスタム エージェント カードのツール数は、追加後に増加します。

プレイグラウンドでツールを確認する

エージェントが Kusto ツールを正しく呼び出したことをテストします。

1. 左側のナビゲーションで [ Test Playground ] を選択します。
2. ドロップダウン リストからカスタム エージェントを選択します。
3. 質問: "過去 7 日間のエラーを表示する"
4. エージェントは、 timeRange = 7dを使用してツールを呼び出します。

エージェントが Kusto ツールを呼び出し、クエリ結果を返すことがわかります。 作成した正確なクエリは、クラスターに対して実行されます。

パラメーター構文

クエリでパラメーター プレースホルダーをマークするには、 ##parameterName## または $parameterName を使用します。

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

どちらの構文も同じように機能します。 エージェントは実行時に値を置き換えます。

実行モード

次の表では、Kusto ツールで使用できる実行モードについて説明します。

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

ツールを編集または削除する

作成後にツールを変更または削除できます。

[編集]

1. エージェント キャンバスで、ツール ノードを選択して情報パネルを開きます。
2. パネル ヘッダーの 編集 (鉛筆) アイコンを選択します。
3. 編集ダイアログが開き、現在の設定が表示されます。 クエリ、パラメーター、またはコネクタを変更します。
4. 保存を選びます。

削除

1. ツール ノードを選択して情報パネルを開きます。
2. パネル ヘッダーで ⋯ (その他のアクション) メニューを選択します。
3. [削除] ツールを選択します。
4. ダイアログで削除を確認します。

次のステップ

関連するコンテンツ

• Kusto ツール
• Python ツールを作成する
• カスタム エージェント