Tutorial: Creación de una herramienta kusto en el agente de SRE de Azure

En este tutorial, creará una herramienta kusto parametrizada que ejecuta consultas KQL exactas con resultados repetibles y deterministas. Cuando los usuarios hacen preguntas como "mostrarme errores de los últimos siete días", el agente sustituye el parámetro y ejecuta la consulta exacta en la base de datos de Azure Data Explorer.

En este tutorial aprenderá a:

Tiempo estimado: 15 minutos

Prerrequisitos

Asegúrese de que cumple los siguientes requisitos previos antes de empezar:

• Un clúster de Azure Data Explorer con el rol AllDatabasesViewer concedido a la identidad administrada del agente. Para obtener más información, consulte Requisitos previos de las herramientas de Kusto.
• Un conector Kusto configurado. Para obtener más información, consulte Configuración de un conector de Kusto.
• Acceso a Builder en el portal del agente de SRE de Azure.

Navegar al Lienzo del agente

Abre el Lienzo del Agente donde puedes crear y administrar herramientas.

1. Abra el portal del agente de SRE.
2. Seleccionar tu agente.
3. Seleccione Generador en el panel de navegación izquierdo.
4. Seleccione Agent Canvas.

Abrir el formulario de creación de herramientas

Inicie el proceso de creación de herramientas desde la barra de herramientas.

1. Seleccione la lista desplegable Crear en la barra de herramientas superior.
2. Seleccione Herramienta>herramienta Kusto.

Rellene los detalles de la herramienta.

Complete el formulario con la configuración de la herramienta.

Escriba la consulta de ejemplo siguiente:

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

La ##timeRange## sintaxis crea un parámetro. Cuando alguien pregunta "mostrar errores de las últimas 24 horas", el agente rellena timeRange = 24h.

Adición del parámetro

Defina el parámetro que usa la consulta.

1. Desplácese hasta la sección Parámetros .
2. Seleccione Agregar parámetro.
3. Escriba los valores siguientes:
   • Nombre: timeRange
   • Tipo: Cadena
   • Descripción: "hasta cuándo se debe retroceder (por ejemplo, 1 hora, 24 horas, 7 días)".

El parámetro aparece en la tabla Parameters debajo de la consulta.

Prueba la consulta

Compruebe que la consulta se ejecuta correctamente antes de guardarla.

1. Seleccione Probar en la parte inferior del formulario.
2. Escriba un valor de prueba para timeRange (por ejemplo, 7d).
3. Compruebe que la consulta se ejecuta correctamente.

Verá el tiempo de ejecución y una marca de verificación verde que confirma la ejecución de la consulta. Incluso si la consulta devuelve cero filas, la marca de verificación significa que la sintaxis de la consulta es válida.

Creación de la herramienta

Seleccione Crear para guardar la herramienta Kusto.

Adición de la herramienta a un agente personalizado

Creaste tu herramienta, pero no la adjuntaste a un agente personalizado. Adjunte la herramienta para que el agente pueda usarla.

1. En la Vista de Lienzo, busque el agente personalizado.
2. Seleccione el botón + situado en el lado derecho de la tarjeta del agente personalizado.
3. Seleccione Agregar herramientas existentes.
4. Compruebe la herramienta Kusto en la lista.
5. Seleccione Agregar herramientas.

El recuento de herramientas en la tarjeta del agente personalizado aumenta tras la adición.

Comprobación de la herramienta en el área de juegos

Pruebe que el agente invoca correctamente la herramienta Kusto.

1. Seleccione Área de pruebas en la navegación izquierda.
2. Seleccione el agente personalizado en la lista desplegable.
3. Muéstrame errores de los últimos siete días
4. El agente invoca la herramienta con timeRange = 7d.

Debería ver cómo el agente llama a la herramienta Kusto y devuelve los resultados de la consulta. La consulta exacta que ha escrito se ejecuta en el clúster.

Sintaxis de parámetros

Use ##parameterName## o $parameterName para marcar los marcadores de posición de parámetros en las consultas:

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

Ambas sintaxis funcionan de forma idéntica. El agente reemplaza los valores durante el tiempo de ejecución.

Modos de ejecución

En la tabla siguiente se describen los modos de ejecución disponibles para las herramientas de Kusto.

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

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

Ejemplo: Herramienta de correlación de implementación

La siguiente definición de YAML crea una herramienta kusto que correlaciona las implementaciones con un servicio y un intervalo de tiempo especificados.

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

Editar o eliminar una herramienta

Puede modificar o quitar herramientas después de la creación.

Editar

1. En el Agent Canvas, seleccione el nodo de herramienta para abrir el panel de información.
2. Seleccione el icono de edición (lápiz) en el encabezado del panel.
3. El cuadro de diálogo de edición se abre con la configuración actual. Modifique la consulta, los parámetros o el conector.
4. Haga clic en Guardar.

Eliminar

1. Seleccione el nodo de herramientas para abrir el panel de información.
2. Seleccione el menú ⋯ (más acciones) en el encabezado del panel.
3. Seleccione Eliminar herramienta.
4. Confirme la eliminación en el cuadro de diálogo.

Paso siguiente

Contenido relacionado

• Herramientas de Kusto
• Creación de una herramienta de Python
• Agentes personalizados