Tutorial: Create a Kusto tool in Azure SRE Agent

In this tutorial, you create a parameterized Kusto tool that runs exact KQL queries with deterministic, repeatable results. When users ask questions like "show me errors from the last seven days," the agent substitutes the parameter and runs your exact query against your Azure Data Explorer database.

In this tutorial, you learn how to:

Estimated time: 15 minutes

Prerequisites

Before you begin, make sure you have the following prerequisites:

• An Azure Data Explorer cluster with the AllDatabasesViewer role granted to the agent's managed identity. For more information, see Kusto tools prerequisites.
• A Kusto connector configured. For more information, see Set up a Kusto connector.
• Access to Builder in the Azure SRE Agent portal.

Navigate to the Agent Canvas

Open the Agent Canvas where you create and manage tools.

1. Open the SRE Agent portal.
2. Select your agent.
3. Select Builder in the left navigation.
4. Select Agent Canvas.

Open the tool creation form

Start the tool creation process from the toolbar.

1. Select the Create dropdown in the top toolbar.
2. Select Tool > Kusto tool.

Fill in the tool details

Complete the form with your tool configuration.

Enter the following example query:

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

The ##timeRange## syntax creates a parameter. When someone asks "show errors from the last 24 hours," the agent fills in timeRange = 24h.

Add the parameter

Define the parameter that your query uses.

1. Scroll to the Parameters section.
2. Select Add parameter.
3. Enter the following values:
   • Name: timeRange
   • Type: String
   • Description: "How far back to look (for example, 1h, 24h, 7d)"

The parameter appears in the Parameters table below your query.

Test the query

Validate that the query runs successfully before saving.

1. Select Test at the bottom of the form.
2. Enter a test value for timeRange (for example, 7d).
3. Verify the query executes successfully.

You see execution time and a green checkmark confirming the query runs. Even if the query returns zero rows, the checkmark means the query syntax is valid.

Create the tool

Select Create to save your Kusto tool.

Add the tool to a custom agent

You created your tool but didn't attach it to a custom agent. Attach the tool so the agent can use it.

1. In Canvas view, find your custom agent.
2. Select the + button on the right side of the custom agent card.
3. Select Add existing tools.
4. Check your Kusto tool from the list.
5. Select Add tools.

The tool count on your custom agent card increases after adding.

Verify the tool in the playground

Test that the agent invokes your Kusto tool correctly.

1. Select Test Playground in the left navigation.
2. Select your custom agent from the dropdown list.
3. Ask: "Show me errors from the last seven days"
4. The agent invokes your tool with timeRange = 7d.

You should see the agent call your Kusto tool and return query results. The exact query you wrote runs against your cluster.

Parameter syntax

Use ##parameterName## or $parameterName to mark parameter placeholders in your queries:

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

Both syntaxes work identically. The agent substitutes values at runtime.

Execution modes

The following table describes the available execution modes for Kusto tools.

# Function mode example
spec:
  type: KustoTool
  mode: Function
  function: GetRecentErrors

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

Example: Deployment correlation tool

The following YAML definition creates a Kusto tool that correlates deployments with a specified service and time range.

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 or delete a tool

You can modify or remove tools after creation.

Edit

1. On the Agent Canvas, select the tool node to open the info panel.
2. Select the edit (pencil) icon in the panel header.
3. The edit dialog opens with your current settings. Modify the query, parameters, or connector.
4. Select Save.

Delete

1. Select the tool node to open the info panel.
2. Select the ⋯ (more actions) menu in the panel header.
3. Select Delete tool.
4. Confirm the deletion in the dialog.

Next step

Related content

• Kusto tools
• Create a Python tool
• Custom agents