Referência de API para Azure Agente SRE

Operações de API REST para gerenciar e interagir com Azure agente SRE programaticamente.

Overview

Azure agente SRE fornece APIs REST em duas camadas. Use o ARM (plano de controle) para criar, configurar e excluir agentes e seus sub-recursos. Use o plano de dados para operações de runtime, como chat, gerenciamento de repositório e uploads de conhecimento.

Avião URL base Auth Usar para
Painel de controle management.azure.com RBAC de Azure Padrão Criar, atualizar, excluir agentes e configuração
Plano de dados Ponto de extremidade por agente azuresre.dev Público Chat, repositórios, ganchos, conhecimento, gatilhos

Autenticação

Plano de controle (ARM)

Autenticação de Azure padrão – CLI do Azure, entidade de serviço ou identidade gerenciada:

# 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 ponto de extremidade do agente é exclusivo por agente. Ele segue o padrão https://{name}--{id}.{hash}.{region}.azuresre.ai e a operação ARM GET retorna esse ponto de extremidade em properties.agentEndpoint.

Funções RBAC

Função Description Scope
Administrador do Agente SRE Controle total sobre a configuração e as operações do agente Recurso de agente
Usuário do Agente SRE Chat, aprovar ações, gerenciar threads Recurso de agente
Leitor do Agente SRE Acesso somente leitura à configuração e threads do agente Recurso de agente

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

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

Operações do ARM (plano de controle)

Versão da API

2025-05-01-preview

Note

As APIs do plano de controle e do plano de dados estão atualmente em versão prévia. Caminhos de ponto de extremidade, esquemas de solicitação e resposta e comportamento podem mudar antes da disponibilidade geral. Fixe suas integrações nessa versão da API e teste após as atualizações.

URL base

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

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

Operações de recurso do agente

Operação Método Sufixo de caminho
Criar ou atualizar PUT (nenhuma)
Get GET (nenhuma)
excluir DELETE (nenhuma)
Start POST /start
Parar POST /stop
Obter usos GET /usages
Obter usos diários GET /dailyusages

Propriedades do agente

Property Tipo Description
provisioningState cadeia Succeeded, Failed, InProgress, Canceled( Deleting somente leitura)
agentEndpoint cadeia URL do plano de dados (somente leitura)
powerState cadeia Running ou Stopped (somente leitura)
outboundIpAddresses string[] IPs de saída para a lista de permissões (somente leitura)
actionConfiguration.mode cadeia Review, Automatic ou ReadOnly
actionConfiguration.accessLevel cadeia Low ou High
defaultModel.provider cadeia Anthropic ou MicrosoftFoundry (IA aberta)
defaultModel.name cadeia Nome do modelo (por exemplo, Automatic)
upgradeChannel cadeia Stable ou Preview
monthlyAgentUnitLimit number Limite AAU de fluxo ativo mensal (não inclui fluxo always-on)
knowledgeGraphConfiguration.identity cadeia ID do recurso de identidade gerenciada
knowledgeGraphConfiguration.managedResources string[] IDs do grupo de recursos que o agente pode acessar
logConfiguration objeto Configuração do Application Insights
incidentManagementConfiguration.type cadeia PagerDuty, AzMonitor, ServiceNowou None
mcpServers string[] URLs do servidor MCP
vnetConfiguration.subnetResourceId cadeia Sub-rede de injeção de VNet
experimentalSettings objeto Substituições de sinalizador de recurso

Sub-recursos

Sub-recurso Tipo arm Caminho
Conectores Microsoft.App/agents/DataConnectors /DataConnectors/{name}
Capacidades 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 incidentes Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Ganchos Microsoft.App/agents/hooks /hooks/{name}
Prompts comuns Microsoft.App/agents/commonPrompts /commonPrompts/{name}

Todos os sub-recursos dão suporte PUT (criar/atualizar) GETe DELETE operações.

Formatos de corpo de sub-recurso

Os conectores usam 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 (habilidades, subagentes, ferramentas e assim por diante) usam um envelope codificado em 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 conector

Tipo Valor Caso de uso
Azure Data Explorer Kusto Consultar clusters do ADX
Application Insights Kusto Consultar o App Insights
Análise de Logs Kusto Log Analytics de consulta
MCP Mcp Conectores compatíveis com MCP (Datadog, Splunk etc.)
PagerDuty Mcp Incidentes de PagerDuty
ServiceNow Mcp Incidentes do ServiceNow
Outlook Outlook Notificações por email
Equipes Teams Notificações do canal do 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, gerenciar aprovações, carregar conhecimento e configurar repositórios, ganchos e gatilhos.

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/....

Threads e chat

Método Caminho Description
GET /api/v1/threads Listar threads de conversa
GET /api/v1/threads/{threadId} Obter um thread específico
POST /api/v1/threads/{threadId}/messages Enviar uma mensagem (iniciar uma conversa)
GET /api/v1/threads/{threadId}/messages Obter mensagens em um thread

Aprovações

Método Caminho Description
GET /api/v1/approvals/{threadId} Listar aprovações pendentes
POST /api/v1/approvals/{threadId}/{id}/decision Aprovar ou rejeitar uma ação

Repositórios de código

Método Caminho Description
PUT /api/v2/repos/{repoName} Adicionar um repositório de código
GET /api/v2/repos Listar repositórios
GET /api/v2/repos/{repoName} Obter detalhes do repositório
DELETE /api/v2/repos/{repoName} Remover um repositório
POST /api/v2/repos/{repoName}/test Testar conectividade de repositório

Conhecimento (memória do agente)

Método Caminho Description
POST /api/v1/agentmemory/upload Carregar documentos (várias partes, máximo de 100 MB no total, 16 MB por arquivo)
GET /api/v1/agentmemory/status Verificar o status da memória
DELETE /api/v1/agentmemory/document/{fileName} Excluir um documento
DELETE /api/v1/agentmemory/documents Excluir documentos em massa
GET /api/v1/agentmemory/indexer-status Verificar o progresso do indexador

Gatilhos HTTP

Método Caminho Description
POST /api/v1/httptriggers/create Criar um gatilho HTTP
GET /api/v1/httptriggers Listar acionadores
POST /api/v1/httptriggers/{triggerId}/execute Executar um gatilho
POST /api/v1/httptriggers/trigger/{triggerId} Ponto de extremidade de webhook público (sem necessidade de autenticação)

Ganchos

Método Caminho Description
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 do agente estendido

Gerenciar subagentes, ferramentas, conectores, habilidades, prompts e plug-ins por meio 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}
Capacidades /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 dão suportePUT, GETe PATCHDELETE métodos.

Streaming em tempo real

O agente usa o SignalR para streaming de chat em tempo real:

Hub Caminho Purpose
AgentHub /agentHub Atualizações de thread e streaming de mensagens em tempo real

Conecte-se usando a biblioteca de clientes do SignalR com o mesmo token de portador.

Exemplos

Obter propriedades do 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

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

Listar threads por meio do 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 por meio 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