API reference for Azure SRE Agent

Operações da API REST para gerir e interagir programaticamente com o Azure SRE Agent.

Overview

O Azure SRE Agent fornece APIs REST em duas camadas. Use o plano de controlo (ARM) para criar, configurar e eliminar agentes e os seus subrecursos. Use o plano de dados para operações em tempo de execução como chat, gestão de repositórios e carregamento de conhecimento.

Avião URL base Auth Uso para
Plano de controlo management.azure.com Azure padrão RBAC Criar, atualizar, eliminar agentes e configurar
Plano de dados Endpoint por agente azuresre.dev público Chat, repositórios, ganchos, conhecimento, gatilhos

Authentication

Plano de controlo (ARM)

Autenticação padrão do Azure - CLI do Azure, principal de serviço ou identidade gerida:

# 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 dados

O plano de dados requer um token separado com audiência 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

O endpoint do agente é único por agente. Segue o padrão https://{name}--{id}.{hash}.{region}.azuresre.ai e a operação ARM GET devolve este ponto final em properties.agentEndpoint.

Funções RBAC

Função Descrição Scope
Administrador de Agentes SRE Controlo total sobre a configuração e operações do agente Recursos do agente
Utilizador Agente SRE Conversar, aprovar ações, gerir tópicos Recursos do agente
Leitor de Agente SRE Acesso apenas de leitura à configuração do agente e threads Recursos do agente

Atribua funções usando o portal Azure, CLI ou API ARM:

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

Operações do plano de controlo (ARM)

Versão da API

2025-05-01-preview

Note

Tanto as APIs do plano de controlo como do plano de dados estão atualmente em pré-visualização. Os caminhos dos endpoints, esquemas de pedido e resposta, e comportamentos podem mudar antes da disponibilidade geral. Fixe as suas integrações nesta versão da API e teste após atualizações.

URL base

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

Adicione o sufixo path da tabela de operações e depois adicione ?api-version=2025-05-01-preview como parâmetro de consulta. Por exemplo: .../agents/{agentName}/start?api-version=2025-05-01-preview.

Operações de recursos de agentes

Operation Método Sufixo de caminho
Criar ou atualizar PUT (nenhum)
Get GET (nenhum)
Delete DELETE (nenhum)
Início POST /start
Parar POST /stop
Obter utilizações GET /usages
Obtenha usos diários GET /dailyusages

Propriedades do agente

Propriedade Tipo Descrição
provisioningState cadeia (de caracteres) Succeeded, Failed, InProgress, Canceled, Deleting (só leitura)
agentEndpoint cadeia (de caracteres) URL do plano de dados (apenas leitura)
powerState cadeia (de caracteres) Running ou Stopped (só leitura)
outboundIpAddresses string[] IPs de saída para lista de permissões (apenas leitura)
actionConfiguration.mode cadeia (de caracteres) Review, Automatic ou ReadOnly
actionConfiguration.accessLevel cadeia (de caracteres) Low ou High
defaultModel.provider cadeia (de caracteres) Anthropic ou MicrosoftFoundry (Open AI)
defaultModel.name cadeia (de caracteres) Nome do modelo (por exemplo, Automatic)
upgradeChannel cadeia (de caracteres) Stable ou Preview
monthlyAgentUnitLimit number Limite AAU de fluxo ativo mensal (não inclui fluxo sempre ligado)
knowledgeGraphConfiguration.identity cadeia (de caracteres) ID de recurso de identidade gerida
knowledgeGraphConfiguration.managedResources string[] IDs de grupos de recursos que o agente pode aceder
logConfiguration objecto Configuração do Application Insights
incidentManagementConfiguration.type cadeia (de caracteres) PagerDuty, AzMonitor, ServiceNowou None
mcpServers string[] URLs dos servidores MCP
vnetConfiguration.subnetResourceId cadeia (de caracteres) Sub-rede de injeção VNet
experimentalSettings objecto Substituições de flags de características

Recursos subordinados

Sub-recurso Tipo ARM Path
Conectores Microsoft.App/agents/DataConnectors /DataConnectors/{name}
Competências Microsoft.App/agents/skills /skills/{name}
Subagentes Microsoft.App/agents/subagents /subagents/{name}
Tools Microsoft.App/agents/tools /tools/{name}
Tarefas agendadas Microsoft.App/agents/scheduledTasks /scheduledTasks/{name}
Filtros de incidente Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Ganchos Microsoft.App/agents/hooks /hooks/{name}
Prompts comuns Microsoft.App/agents/commonPrompts /commonPrompts/{name}

Todos os subrecursos suportam PUT (criar/atualizar), GETe DELETE operações.

Formatos dos corpos de subrecursos

Os conectores utilizam propriedades diretas:

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"
    }
  }'

Outros sub-recursos (competências, subagentes, ferramentas, etc.) utilizam um envelope codificado 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 valor Caso de uso
Azure Data Explorer Kusto Consultar clusters ADX
Application Insights Kusto Consultar Insights da Aplicação
Análise de Registos Kusto Query Log Analytics
MCP Mcp conectores compatíveis com MCP (Datadog, Splunk, etc.)
PagerDuty Mcp Incidentes com PagerDuty
ServiceNow Mcp Incidentes do ServiceNow
Outlook Outlook Notificações por e-mail
Equipas Teams Notificações do canal Teams

Operações do plano de dados

Use a API do plano de dados para interagir com um agente em execução, incluindo enviar mensagens, gerir aprovações, carregar conhecimento e configurar repositórios, hooks e triggers.

URL base

Obtenha do ARM:

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

Todos os caminhos do plano de dados começam com $ENDPOINT/api/....

Tópicos e conversas

Método Path Descrição
GET /api/v1/threads Tópicos de conversa de listas
GET /api/v1/threads/{threadId} Arranja um tópico específico
POST /api/v1/threads/{threadId}/messages Envie uma mensagem (inicie uma conversa)
GET /api/v1/threads/{threadId}/messages Obter mensagens em um thread

Aprovações

Método Path Descrição
GET /api/v1/approvals/{threadId} Lista pendente de aprovações
POST /api/v1/approvals/{threadId}/{id}/decision Aprovar ou rejeitar uma ação

Repositórios de código

Método Path Descrição
PUT /api/v2/repos/{repoName} Adicionar um repositório de código
GET /api/v2/repos Listar repositórios
GET /api/v2/repos/{repoName} Obtenha detalhes do repositório
DELETE /api/v2/repos/{repoName} Remover um repositório
POST /api/v2/repos/{repoName}/test Conectividade dos repositórios de teste

Conhecimento (memória do agente)

Método Path Descrição
POST /api/v1/agentmemory/upload Carregar documentos (multipartes, máximo 100 MB no total, 16 MB por ficheiro)
GET /api/v1/agentmemory/status Verificar o estado da memória
DELETE /api/v1/agentmemory/document/{fileName} Eliminar um documento
DELETE /api/v1/agentmemory/documents Eliminar documentos em massa
GET /api/v1/agentmemory/indexer-status Verificar o progresso do indexador

Gatilhos HTTP

Método Path Descrição
POST /api/v1/httptriggers/create Criar um gatilho HTTP
GET /api/v1/httptriggers Gatilhos de lista
POST /api/v1/httptriggers/{triggerId}/execute Executar um gatilho
POST /api/v1/httptriggers/trigger/{triggerId} Endpoint público de webhook (sem necessidade de autenticação)

Ganchos

Método Path Descrição
PUT /api/v2/extendedAgent/hooks/{hookName} Criar ou atualizar um gancho
GET /api/v2/extendedAgent/hooks Ganchos de lista
DELETE /api/v2/extendedAgent/hooks/{hookName} Excluir um gancho

Configuração estendida do agente

Gerir subagentes, ferramentas, conectores, competências, prompts e plugins através do plano de dados:

Recurso Padrão de caminho
Subagentes /api/v2/extendedAgent/agents/{name}
Tools /api/v2/extendedAgent/tools/{name}
Conectores /api/v2/extendedAgent/connectors/{name}
Competências /api/v2/extendedAgent/skills/{name}
Prompts comuns /api/v2/extendedAgent/commonprompts/{name}
Tarefas agendadas /api/v2/extendedAgent/scheduledtasks/{name}
Plugins /api/v2/extendedAgent/plugins/{name}

Todos os recursos apoiam PUT, GET, PATCH, e DELETE métodos.

Streaming em tempo real

O agente utiliza o SignalR para transmissão de chat em tempo real:

Núcleo Path Purpose
AgentHub /agentHub Transmissão de mensagens em tempo real e atualizações de threads

Liga-te usando a biblioteca cliente SignalR com o mesmo token portador.

Exemplos

Obtenha propriedades para agentes

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

Listar todos os 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

Threads de lista via plano de dados

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"

Adicionar um repositório de código através do plano de dados

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"
    }
  }'

Conteúdo relacionado

  • Last updated on