Informazioni di riferimento sulle API per Azure agente SRE

Operazioni api REST per la gestione e l'interazione con Azure agente SRE a livello di codice.

Panoramica

Azure agente SRE fornisce API REST a due livelli. Usare il piano di controllo (ARM) per creare, configurare ed eliminare agenti e le relative risorse secondarie. Usare il piano dati per operazioni di runtime come chat, gestione dei repository e caricamenti delle informazioni.

Aereo URL di base Auth Usare per
Piano di controllo management.azure.com Controllo degli accessi in base al ruolo standard Azure Creare, aggiornare, eliminare agenti e configurazione
Piano di dati Endpoint per agente azuresre.dev Pubblico Chat, repository, hook, conoscenza, trigger

Authentication

Piano di controllo (ARM)

Autenticazione Azure standard: interfaccia della riga di comando di Azure, entità servizio o identità gestita:

# 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

Piano di dati

Il piano dati richiede un token separato con destinatari 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"

Annotazioni

L'endpoint dell'agente è univoco per agente. Segue il modello https://{name}--{id}.{hash}.{region}.azuresre.ai e l'operazione ARM GET restituisce questo endpoint in properties.agentEndpoint.

Ruoli RBAC

Ruolo Descrizione Ambito
Amministratore agente SRE Controllo completo sulla configurazione e sulle operazioni dell'agente Risorsa dell'agente
Utente agente SRE Chat, approvare azioni, gestire thread Risorsa dell'agente
SRE Agente Lettore Accesso in sola lettura alla configurazione e ai thread dell'agente Risorsa dell'agente

Assegnare ruoli usando il portale di Azure, l'interfaccia della riga di comando o l'API ARM:

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

Operazioni del piano di controllo (ARM)

Versione dell'API

2025-05-01-preview

Annotazioni

Sia il piano di controllo che le API del piano dati sono attualmente in anteprima. I percorsi degli endpoint, gli schemi di richiesta e risposta e il comportamento possono cambiare prima della disponibilità generale. Aggiungere le integrazioni a questa versione dell'API e testare dopo gli aggiornamenti.

URL di base

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

Aggiungere il suffisso path dalla tabella delle operazioni, quindi aggiungere ?api-version=2025-05-01-preview come parametro di query. Ad esempio: .../agents/{agentName}/start?api-version=2025-05-01-preview.

Operazioni delle risorse dell'agente

Operazione metodo Suffisso path
Creazione o aggiornamento PUT (nessuno)
Get GET (nessuno)
Elimina DELETE (nessuno)
Inizio POST /start
Fermati POST /stop
Ottenere gli utilizzi GET /usages
Ottenere utilizzi giornalieri GET /dailyusages

Proprietà dell'agente

Proprietà Tipo Descrizione
provisioningState string Succeeded Failed, InProgress, , Canceled, ( Deleting sola lettura)
agentEndpoint string URL del piano dati (sola lettura)
powerState string Running o Stopped (sola lettura)
outboundIpAddresses string[] Indirizzi IP in uscita per l'elenco elementi consentiti (sola lettura)
actionConfiguration.mode string Review, Automatic o ReadOnly
actionConfiguration.accessLevel string Low oppure High
defaultModel.provider string Anthropic o MicrosoftFoundry (Open AI)
defaultModel.name string Nome modello (ad esempio, Automatic)
upgradeChannel string Stable oppure Preview
monthlyAgentUnitLimit number Limite AAU del flusso attivo mensile (non include il flusso sempre attivo)
knowledgeGraphConfiguration.identity string ID risorsa identità gestita
knowledgeGraphConfiguration.managedResources string[] ID gruppo di risorse a cui l'agente può accedere
logConfiguration object Configurazione di Application Insights
incidentManagementConfiguration.type string PagerDuty, AzMonitor, ServiceNowo None
mcpServers string[] URL del server MCP
vnetConfiguration.subnetResourceId string Subnet di inserimento della rete virtuale
experimentalSettings object Sostituzioni dei flag di funzionalità

Risorse secondarie

Sotto-risorsa Tipo arm Percorso
Connettori Microsoft.App/agents/DataConnectors /DataConnectors/{name}
Competenze Microsoft.App/agents/skills /skills/{name}
Subagenti Microsoft.App/agents/subagents /subagents/{name}
Tools Microsoft.App/agents/tools /tools/{name}
Attività pianificate Microsoft.App/agents/scheduledTasks /scheduledTasks/{name}
Filtri degli eventi imprevisti Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Hook Microsoft.App/agents/hooks /hooks/{name}
Richieste comuni Microsoft.App/agents/commonPrompts /commonPrompts/{name}

Tutte le risorse secondarie supportano PUT (creazione/aggiornamento), GETe DELETE operazioni.

Formati del corpo delle risorse secondarie

I connettori usano proprietà dirette:

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

Altre sotto-risorse (competenze, subagenti, strumenti e così via) usano una busta con codifica 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\"}}"

Tipi di connettore

Tipo Value Caso di utilizzo
Esplora dati di Azure Kusto Eseguire query sui cluster ADX
Application Insights Kusto Query App Insights
Log Analytics Kusto Query Log Analytics
MCP Mcp Connettori compatibili con MCP (Datadog, Splunk e così via)
PagerDuty Mcp Eventi imprevisti di PagerDuty
ServiceNow Mcp Eventi imprevisti di ServiceNow
Outlook Outlook Notifiche tramite posta elettronica
Teams Teams Notifiche dei canali di Teams

Operazioni del piano dati

Usare l'API del piano dati per interagire con un agente in esecuzione, tra cui l'invio di messaggi, la gestione delle approvazioni, il caricamento delle informazioni e la configurazione di repository, hook e trigger.

URL di base

Ottenere da ARM:

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

Tutti i percorsi del piano dati iniziano con $ENDPOINT/api/....

Thread e chat

metodo Percorso Descrizione
GET /api/v1/threads Elencare i thread di conversazione
GET /api/v1/threads/{threadId} Ottenere un thread specifico
POST /api/v1/threads/{threadId}/messages Inviare un messaggio (avviare una conversazione)
GET /api/v1/threads/{threadId}/messages Ottenere messaggi in un thread

Approvazioni

metodo Percorso Descrizione
GET /api/v1/approvals/{threadId} Elencare le approvazioni in sospeso
POST /api/v1/approvals/{threadId}/{id}/decision Approvare o rifiutare un'azione

Repository di codice

metodo Percorso Descrizione
PUT /api/v2/repos/{repoName} Aggiungere un repository di codice
GET /api/v2/repos Elenco repository
GET /api/v2/repos/{repoName} Ottenere i dettagli del repository
DELETE /api/v2/repos/{repoName} Rimuovere un repository
POST /api/v2/repos/{repoName}/test Testare la connettività del repository

Knowledge (memoria agente)

metodo Percorso Descrizione
POST /api/v1/agentmemory/upload Caricare documenti (multipart, max 100 MB totali, 16 MB per file)
GET /api/v1/agentmemory/status Controllare lo stato della memoria
DELETE /api/v1/agentmemory/document/{fileName} Eliminazione di un documento
DELETE /api/v1/agentmemory/documents Eliminare documenti in blocco
GET /api/v1/agentmemory/indexer-status Controllare lo stato dell'indicizzatore

Trigger HTTP

metodo Percorso Descrizione
POST /api/v1/httptriggers/create Creare un trigger HTTP
GET /api/v1/httptriggers Elencare i trigger
POST /api/v1/httptriggers/{triggerId}/execute Eseguire un trigger
POST /api/v1/httptriggers/trigger/{triggerId} Endpoint webhook pubblico (nessuna autenticazione necessaria)

Hook

metodo Percorso Descrizione
PUT /api/v2/extendedAgent/hooks/{hookName} Crea o aggiornare un hook
GET /api/v2/extendedAgent/hooks Elencare gli hook
DELETE /api/v2/extendedAgent/hooks/{hookName} Eliminare un hook

Configurazione dell'agente esteso

Gestire subagenti, strumenti, connettori, competenze, richieste e plug-in tramite il piano dati:

risorsa Modello di percorso
Subagenti /api/v2/extendedAgent/agents/{name}
Tools /api/v2/extendedAgent/tools/{name}
Connettori /api/v2/extendedAgent/connectors/{name}
Competenze /api/v2/extendedAgent/skills/{name}
Richieste comuni /api/v2/extendedAgent/commonprompts/{name}
Attività pianificate /api/v2/extendedAgent/scheduledtasks/{name}
Plugins /api/v2/extendedAgent/plugins/{name}

Tutte le risorse supportano i PUTmetodi , GETPATCH, e DELETE .

Streaming in tempo reale

L'agente usa SignalR per lo streaming di chat in tempo reale:

Hub Percorso Scopo
AgentHub /agentHub Streaming di messaggi in tempo reale e aggiornamenti dei thread

Connettersi usando la libreria client SignalR con lo stesso token di connessione.

Esempi

Ottenere le proprietà dell'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

Elencare tutti i connettori

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

Elencare i thread tramite piano dati

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"

Aggiungere un repository di codice tramite il piano dati

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

Contenuti correlati

  • Last updated on