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.

Avión Dirección URL base Auth Usado para
Plano de control management.azure.com RBAC de Azure estándar Creación, actualización, eliminación de agentes y configuración
Plano de datos Punto de conexión por agente azuresre.dev audiencia Chat, repositorios, enlaces, conocimientos, desencadenadores

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"

Note

El punto de conexión del agente es único por agente. Sigue el patrón https://{name}--{id}.{hash}.{region}.azuresre.ai y la operación GET de ARM devuelve este punto de conexión en properties.agentEndpoint.

Funciones RBAC

Función Descripción Ámbito
Administrador del agente de SRE Control total sobre la configuración y las operaciones del agente Recurso del agente
Usuario del agente de SRE Chatear, aprobar acciones, administrar subprocesos Recurso del agente
Lector del Agente de SRE Acceso de solo lectura a la configuración y los subprocesos del agente Recurso del agente

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

Note

Las API del plano de control y del plano de datos se encuentran actualmente en versión preliminar. Las rutas de acceso de punto de conexión, los esquemas de solicitud y respuesta y el comportamiento pueden cambiar antes de la disponibilidad general. Ancle las integraciones a esta versión de API y pruebe después de las actualizaciones.

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

Operación Método Sufijo path
Creación o actualización PUT (ninguno)
Get GET (ninguno)
Eliminar DELETE (ninguno)
Inicio POST /start
Parar POST /stop
Obtener usos GET /usages
Obtener usos diarios GET /dailyusages

Propiedades del agente

Propiedad Tipo Descripción
provisioningState string Succeeded, Failed, InProgress, , CanceledDeleting(solo lectura)
agentEndpoint string Dirección URL del plano de datos (solo lectura)
powerState string Running o Stopped (solo lectura)
outboundIpAddresses string[] Direcciones IP salientes para la lista de permitidos (solo lectura)
actionConfiguration.mode string Review, Automatic o ReadOnly
actionConfiguration.accessLevel string Low o High
defaultModel.provider string Anthropic o MicrosoftFoundry (Open AI)
defaultModel.name string Nombre del modelo (por ejemplo, Automatic)
upgradeChannel string Stable o Preview
monthlyAgentUnitLimit number Límite de AAU de flujo activo mensual (no incluye el flujo siempre activo)
knowledgeGraphConfiguration.identity string Identificador de recurso de identidad administrada
knowledgeGraphConfiguration.managedResources string[] Identificadores de grupo de recursos a los que el agente puede acceder
logConfiguration object Configuración de Application Insights
incidentManagementConfiguration.type string PagerDuty, AzMonitor, ServiceNow o None
mcpServers string[] Direcciones URL del servidor MCP
vnetConfiguration.subnetResourceId string Subred de inyección de red virtual
experimentalSettings object Invalidaciones de marca de características

Subrecursos

Subrecurso Tipo de ARM Ruta
Conectores Microsoft.App/agents/DataConnectors /DataConnectors/{name}
Habilidades Microsoft.App/agents/skills /skills/{name}
Subagentes Microsoft.App/agents/subagents /subagents/{name}
Herramientas Microsoft.App/agents/tools /tools/{name}
Tareas programadas Microsoft.App/agents/scheduledTasks /scheduledTasks/{name}
Filtros de incidentes Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Hooks Microsoft.App/agents/hooks /hooks/{name}
Avisos comunes Microsoft.App/agents/commonPrompts /commonPrompts/{name}

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

Tipo Value Caso de uso
Explorador de Datos de Azure Kusto Consulta de clústeres de ADX
Application Insights Kusto Consulta de App Insights
Log Analytics Kusto Consulta Log Analytics
MCP Mcp Conectores compatibles con MCP (Datadog, Splunk, etc.)
PagerDuty Mcp Incidentes de PagerDuty
ServiceNow Mcp Incidentes de ServiceNow
Outlook Outlook Notificaciones por correo electrónico
Equipos Teams Notificaciones del canal de Teams

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

Método Ruta Descripción
GET /api/v1/threads Enumerar subprocesos de conversación
GET /api/v1/threads/{threadId} Obtener un subproceso específico
POST /api/v1/threads/{threadId}/messages Enviar un mensaje (iniciar una conversación)
GET /api/v1/threads/{threadId}/messages Obtener mensajes en un subproceso

Aprobaciones

Método Ruta Descripción
GET /api/v1/approvals/{threadId} Enumerar aprobaciones pendientes
POST /api/v1/approvals/{threadId}/{id}/decision Aprobar o rechazar una acción

Repositorios de código

Método Ruta Descripción
PUT /api/v2/repos/{repoName} Adición de un repositorio de código
GET /api/v2/repos Lista de repositorios
GET /api/v2/repos/{repoName} Obtención de detalles del repositorio
DELETE /api/v2/repos/{repoName} Eliminación de un repositorio
POST /api/v2/repos/{repoName}/test Probar la conectividad del repositorio

Conocimiento (memoria del agente)

Método Ruta Descripción
POST /api/v1/agentmemory/upload Cargar documentos (multipart, máximo 100 MB en total, 16 MB por archivo)
GET /api/v1/agentmemory/status Comprobación del estado de la memoria
DELETE /api/v1/agentmemory/document/{fileName} Eliminar un documento
DELETE /api/v1/agentmemory/documents Eliminación masiva de documentos
GET /api/v1/agentmemory/indexer-status Comprobación del progreso del indexador

Desencadenadores HTTP

Método Ruta Descripción
POST /api/v1/httptriggers/create Creación de un desencadenador HTTP
GET /api/v1/httptriggers Enumeración de desencadenadores
POST /api/v1/httptriggers/{triggerId}/execute Ejecución de un desencadenador
POST /api/v1/httptriggers/trigger/{triggerId} Punto de conexión de webhook público (no se requiere autenticación)

Hooks

Método Ruta Descripción
PUT /api/v2/extendedAgent/hooks/{hookName} Crea o actualiza un enlace.
GET /api/v2/extendedAgent/hooks Enlaces de lista
DELETE /api/v2/extendedAgent/hooks/{hookName} Elimina un enlace.

Configuración extendida del agente

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

Recurso Patrón de ruta
Subagentes /api/v2/extendedAgent/agents/{name}
Herramientas /api/v2/extendedAgent/tools/{name}
Conectores /api/v2/extendedAgent/connectors/{name}
Habilidades /api/v2/extendedAgent/skills/{name}
Avisos comunes /api/v2/extendedAgent/commonprompts/{name}
Tareas programadas /api/v2/extendedAgent/scheduledtasks/{name}
Plugins /api/v2/extendedAgent/plugins/{name}

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

Streaming en directo

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

Hub Ruta propósito
AgentHub /agentHub Actualizaciones de streaming y subprocesos de mensajes 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

  • Last updated on