Referencia de API para agente de SRE de Azure

Operaciones de API REST para administrar e interactuar con Azure agente de SRE mediante programación.

Overview

Azure agente de SRE proporciona API REST en dos capas. Use el plano de control (ARM) para crear, configurar y eliminar agentes y sus subrecursos. Use el plano de datos para operaciones en tiempo de ejecución, como chat, administración de repositorios y cargas de conocimiento.

Autenticación

Plano de control (ARM)

Autenticación Azure estándar: CLI de Azure, entidad de servicio o identidad administrada:

# Interactive login
az login

# Service principal
az login --service-principal -u $APP_ID -p $SECRET --tenant $TENANT_ID

# Managed identity (from Azure VM or Container App)
az login --identity

Plano de datos

El plano de datos requiere un token independiente con la audiencia https://azuresre.dev:

# Step 1: Get the agent's data plane endpoint
ENDPOINT=$(az rest -m GET \
  --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.App/agents/{agentName}?api-version=2025-05-01-preview" \
  --query properties.agentEndpoint -o tsv)

# Step 2: Get a data plane token
TOKEN=$(az account get-access-token \
  --resource https://azuresre.dev \
  --query accessToken -o tsv)

# Step 3: Call the data plane
curl -H "Authorization: Bearer $TOKEN" "$ENDPOINT/api/v1/threads"

Funciones RBAC

Asigne roles mediante el portal de Azure, la CLI o la API de ARM:

az role assignment create \
  --assignee {userOrServicePrincipalId} \
  --role "SRE Agent Administrator" \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{name}"

Operaciones del plano de control (ARM)

Versión de API

2025-05-01-preview

Dirección URL base

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.App/agents/{agentName}

Anexe el sufijo de ruta de acceso de la tabla de operaciones y agregue ?api-version=2025-05-01-preview como parámetro de consulta. Por ejemplo: .../agents/{agentName}/start?api-version=2025-05-01-preview.

Operaciones de recursos del agente

Propiedades del agente

Subrecursos

Todos los subrecursos admiten PUT (crear o actualizar), GETy DELETE operaciones.

Formatos de cuerpo de subrecursos

Los conectores usan propiedades directas :

az rest -m PUT \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{agent}/DataConnectors/my-kusto?api-version=2025-05-01-preview" \
  --body '{
    "properties": {
      "name": "my-kusto",
      "dataConnectorType": "Kusto",
      "dataSource": "https://mycluster.eastus2.kusto.windows.net",
      "identity": "system"
    }
  }'

Otros subrecursos (aptitudes, subagentes, herramientas, etc.) usan un sobre codificado en base64:

# The spec is base64-encoded inside properties.value
SPEC='{"name":"my-tool","description":"Query Azure Resource Graph"}'
ENCODED=$(echo -n "$SPEC" | base64)

az rest -m PUT \
  --url "...Microsoft.App/agents/{agent}/tools/my-tool?api-version=2025-05-01-preview" \
  --body "{\"properties\":{\"value\":\"$ENCODED\"}}"

Tipos de conectores

Operaciones de plano de datos

Use la API del plano de datos para interactuar con un agente en ejecución, incluido el envío de mensajes, la administración de aprobaciones, la carga de conocimientos y la configuración de repositorios, enlaces y desencadenadores.

Dirección URL base

Obtener de ARM:

ENDPOINT=$(az rest -m GET \
  --url "...Microsoft.App/agents/{name}?api-version=2025-05-01-preview" \
  --query properties.agentEndpoint -o tsv)

Todas las rutas de acceso del plano de datos comienzan por $ENDPOINT/api/....

Subprocesos y chat

Aprobaciones

Repositorios de código

Conocimiento (memoria del agente)

Desencadenadores HTTP

Hooks

Configuración extendida del agente

Administre subagentes, herramientas, conectores, aptitudes, avisos y complementos a través del plano de datos:

Todos los recursos admiten PUTlos métodos , GET, PATCHy DELETE .

Streaming en directo

El agente usa SignalR para streaming de chat en tiempo real:

Conéctese mediante la biblioteca cliente de SignalR con el mismo token de portador.

Ejemplos

Obtención de propiedades del agente

az rest -m GET \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{name}?api-version=2025-05-01-preview" \
  -o json

Enumeración de todos los conectores

az rest -m GET \
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.App/agents/{name}/DataConnectors?api-version=2025-05-01-preview" \
  -o json

Enumeración de subprocesos a través del plano de datos

TOKEN=$(az account get-access-token --resource https://azuresre.dev --query accessToken -o tsv)
ENDPOINT="https://{agentEndpoint}"

curl -s -H "Authorization: Bearer $TOKEN" "$ENDPOINT/api/v1/threads"

Adición de un repositorio de código a través del plano de datos

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$ENDPOINT/api/v2/repos/my-repo" \
  -d '{
    "properties": {
      "url": "https://github.com/myorg/myrepo",
      "type": "GitHub"
    }
  }'

Contenido relacionado

• Referencia de plantilla de ARM: esquema de propiedades completo en Microsoft Learn
• Deploy with Infrastructure as Code: Automate agent deployment using Bicep, Terraform o PowerShell
• Requisitos de red: lista de permitidos de firewall para puntos de conexión de API
• Precios y facturación: costos para las operaciones controladas por API