Informations de référence sur l’API pour l’agent SRE Azure

Opérations d’API REST pour la gestion et l’interaction avec Azure Agent SRE par programmation.

Overview

Azure Agent SRE fournit des API REST à deux couches. Utilisez le plan de contrôle (ARM) pour créer, configurer et supprimer des agents et leurs sous-ressources. Utilisez le plan de données pour les opérations d’exécution telles que la conversation, la gestion des référentiels et les chargements de connaissances.

Avion URL de base Auth Utiliser pour
Plan de contrôle management.azure.com RBAC Azure standard Créer, mettre à jour, supprimer des agents et une configuration
Plan de données Point de terminaison par agent azuresre.dev Public Conversation, dépôts, hooks, connaissances, déclencheurs

Authentication

Plan de contrôle (ARM)

Authentification Azure standard : Azure CLI, principal de service ou identité managée :

# 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

Plan de données

Le plan de données nécessite un jeton distinct avec audience 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

Le point de terminaison de l’agent est unique par agent. Il suit le modèle https://{name}--{id}.{hash}.{region}.azuresre.ai et l’opération ARM GET retourne ce point de terminaison dans properties.agentEndpoint.

Rôles RBAC

Rôle Description Étendue
Administrateur de l’agent SRE Contrôle total sur la configuration et les opérations de l’agent Ressource de l’agent
Utilisateur de l’agent SRE Discuter, approuver des actions, gérer des threads Ressource de l’agent
Lecteur de l’agent SRE Accès en lecture seule à la configuration et aux threads de l’agent Ressource de l’agent

Attribuez des rôles à l’aide du portail Azure, de l’interface CLI ou de l’API ARM :

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

Opérations de plan de contrôle (ARM)

Version de l’API

2025-05-01-preview

Note

Les API du plan de contrôle et du plan de données sont actuellement en préversion. Les chemins d’accès au point de terminaison, les schémas de requête et de réponse et le comportement peuvent changer avant la disponibilité générale. Épinglez vos intégrations à cette version de l’API et testez après les mises à niveau.

URL de base

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

Ajoutez le suffixe de chemin d’accès à partir de la table des opérations, puis ajoutez-le ?api-version=2025-05-01-preview en tant que paramètre de requête. Par exemple : .../agents/{agentName}/start?api-version=2025-05-01-preview.

Opérations de ressources de l’agent

Opération Méthode Suffixe de chemin d’accès
Créer ou mettre à jour PUT (aucun)
Get GET (aucun)
Supprimer DELETE (aucun)
Démarrer POST /start
Arrêtez POST /stop
Obtenir des utilisations GET /usages
Obtenir des utilisations quotidiennes GET /dailyusages

Propriétés de l’agent

Propriété Type Description
provisioningState string Succeeded, , FailedInProgress, Canceled, , Deleting (en lecture seule)
agentEndpoint string URL du plan de données (lecture seule)
powerState string Running ou Stopped (en lecture seule)
outboundIpAddresses chaîne de caractères[] Adresses IP sortantes pour la liste verte (en lecture seule)
actionConfiguration.mode string Review, Automatic ou ReadOnly
actionConfiguration.accessLevel string Low ou High
defaultModel.provider string Anthropic ou MicrosoftFoundry (Open AI)
defaultModel.name string Nom du modèle (par exemple, Automatic)
upgradeChannel string Stable ou Preview
monthlyAgentUnitLimit number Limite AAU de flux actif mensuel (n’inclut pas de flux always-on)
knowledgeGraphConfiguration.identity string ID de ressource d’identité managée
knowledgeGraphConfiguration.managedResources chaîne de caractères[] ID de groupe de ressources auquel l’agent peut accéder
logConfiguration Objet Configuration d’Application Insights
incidentManagementConfiguration.type string PagerDuty, AzMonitor, ServiceNow, ou None
mcpServers chaîne de caractères[] URL du serveur MCP
vnetConfiguration.subnetResourceId string Sous-réseau d’injection de réseau virtuel
experimentalSettings Objet Remplacements d’indicateurs de fonctionnalité

Sous-ressources

Sous-ressource Type ARM Chemin
Connectors Microsoft.App/agents/DataConnectors /DataConnectors/{name}
Compétences Microsoft.App/agents/skills /skills/{name}
Sous-agents Microsoft.App/agents/subagents /subagents/{name}
Outils Microsoft.App/agents/tools /tools/{name}
Tâches planifiées Microsoft.App/agents/scheduledTasks /scheduledTasks/{name}
Filtres d’incident Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Hooks Microsoft.App/agents/hooks /hooks/{name}
Invites courantes Microsoft.App/agents/commonPrompts /commonPrompts/{name}

Toutes les sous-ressources prennent en charge PUT (créer/mettre à jour) GETet DELETE les opérations.

Formats de corps de sous-ressource

Les connecteurs utilisent des propriétés directes :

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

D’autres sous-ressources (compétences, sous-éléments , outils, et ainsi de suite) utilisent une enveloppe encodée 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\"}}"

Types de connecteurs

Type Valeur Cas d’utilisation
Explorateur de données Azure Kusto Interroger des clusters ADX
Application Insights Kusto Interroger App Insights
Log Analytics Kusto Log Analytics de requête
MCP Mcp Connecteurs compatibles MCP (Datadog, Splunk, etc.)
PagerDuty Mcp Incidents PagerDuty
ServiceNow Mcp Incidents ServiceNow
Outlook Outlook Notifications par courrier électronique
Équipes Teams Notifications de canal Teams

Opérations de plan de données

Utilisez l’API de plan de données pour interagir avec un agent en cours d’exécution, notamment l’envoi de messages, la gestion des approbations, le chargement des connaissances et la configuration des dépôts, des hooks et des déclencheurs.

URL de base

Obtenir à partir d’ARM :

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

Tous les chemins d’accès au plan de données commencent par $ENDPOINT/api/....

Threads et conversation

Méthode Chemin Description
GET /api/v1/threads Répertorier les threads de conversation
GET /api/v1/threads/{threadId} Obtenir un thread spécifique
POST /api/v1/threads/{threadId}/messages Envoyer un message (démarrer une conversation)
GET /api/v1/threads/{threadId}/messages Obtenir des messages dans un thread

Approbations

Méthode Chemin Description
GET /api/v1/approvals/{threadId} Répertorier les approbations en attente
POST /api/v1/approvals/{threadId}/{id}/decision Approuver ou rejeter une action

Dépôts de code

Méthode Chemin Description
PUT /api/v2/repos/{repoName} Ajouter un référentiel de code
GET /api/v2/repos Répertorier les référentiels
GET /api/v2/repos/{repoName} Obtenir les détails du dépôt
DELETE /api/v2/repos/{repoName} Supprimer un référentiel
POST /api/v2/repos/{repoName}/test Tester la connectivité des référentiels

Connaissances (mémoire de l’agent)

Méthode Chemin Description
POST /api/v1/agentmemory/upload Charger des documents (multipart, 100 Mo au total, 16 Mo par fichier)
GET /api/v1/agentmemory/status Vérifier l’état de la mémoire
DELETE /api/v1/agentmemory/document/{fileName} Supprimer un document
DELETE /api/v1/agentmemory/documents Supprimer en bloc des documents
GET /api/v1/agentmemory/indexer-status Vérifier la progression de l’indexeur

Déclencheurs HTTP

Méthode Chemin Description
POST /api/v1/httptriggers/create Créer un déclencheur HTTP
GET /api/v1/httptriggers Lister les déclencheurs
POST /api/v1/httptriggers/{triggerId}/execute Exécuter un déclencheur
POST /api/v1/httptriggers/trigger/{triggerId} Point de terminaison webhook public (aucune authentification requise)

Hooks

Méthode Chemin Description
PUT /api/v2/extendedAgent/hooks/{hookName} Créer ou mettre à jour un hook
GET /api/v2/extendedAgent/hooks Répertorier les crochets
DELETE /api/v2/extendedAgent/hooks/{hookName} Supprimer un hook

Configuration de l’agent étendu

Gérez les sous-titres, les outils, les connecteurs, les compétences, les invites et les plug-ins via le plan de données :

Ressource Modèle de chemin
Sous-agents /api/v2/extendedAgent/agents/{name}
Outils /api/v2/extendedAgent/tools/{name}
Connectors /api/v2/extendedAgent/connectors/{name}
Compétences /api/v2/extendedAgent/skills/{name}
Invites courantes /api/v2/extendedAgent/commonprompts/{name}
Tâches planifiées /api/v2/extendedAgent/scheduledtasks/{name}
Plugins /api/v2/extendedAgent/plugins/{name}

Toutes les ressources prennent en chargePUT, , GETPATCHet DELETE les méthodes.

Streaming en temps réel

L’agent utilise SignalR pour le streaming de conversation en temps réel :

Concentrateur Chemin Purpose
AgentHub /agentHub Mises à jour du streaming et des threads en temps réel

Connectez-vous à l’aide de la bibliothèque cliente SignalR avec le même jeton du porteur.

Exemples

Obtenir les propriétés de l’agent

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

Répertorier tous les connecteurs

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

Répertorier les threads via le plan de données

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"

Ajouter un référentiel de code via le plan de données

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

Contenu connexe

  • Last updated on