Dokumentacja interfejsu API dla agenta Azure SRE

Operacje interfejsu API REST na potrzeby programowego zarządzania agentem SRE Azure i interakcji z nim.

Overview

Azure agent SRE udostępnia interfejsy API REST w dwóch warstwach. Użyj płaszczyzny sterowania (ARM), aby utworzyć, skonfigurować i usunąć agentów oraz ich zasobów podrzędnych. Użyj płaszczyzny danych na potrzeby operacji środowiska uruchomieniowego, takich jak czat, zarządzanie repozytorium i przekazywanie wiedzy.

Samolot Podstawowy adres URL Auth Użyj dla
Płaszczyzna sterowania management.azure.com Kontrola dostępu oparta na rolach w warstwie Standardowa Azure Tworzenie, aktualizowanie, usuwanie agentów i konfiguracja
Płaszczyzna danych Punkt końcowy dla agenta azuresre.dev Publiczności Czat, repozytoria, haki, wiedza, wyzwalacze

Authentication

Płaszczyzna sterowania (ARM)

Uwierzytelnianie Azure w warstwie Standardowa — Azure CLI, jednostka usługi lub tożsamość zarządzana:

# 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

Płaszczyzna danych

Płaszczyzna danych wymaga oddzielnego tokenu z odbiorcami 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

Punkt końcowy agenta jest unikatowy dla każdego agenta. Jest zgodny ze wzorcem https://{name}--{id}.{hash}.{region}.azuresre.ai , a operacja ARM GET zwraca ten punkt końcowy w pliku properties.agentEndpoint.

Role RBAC

Role Opis Scope
Administrator agenta SRE Pełna kontrola nad konfiguracją i operacjami agenta Zasoby dla agenta
Użytkownik agenta SRE Czat, zatwierdzanie akcji, zarządzanie wątkami Zasoby dla agenta
Czytelnik agenta SRE Dostęp tylko do odczytu do konfiguracji agenta i wątków Zasoby dla agenta

Przypisz role przy użyciu portalu Azure, interfejsu wiersza polecenia lub interfejsu API usługi ARM:

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

Operacje płaszczyzny sterowania (ARM)

wersja API

2025-05-01-preview

Note

Interfejsy API płaszczyzny sterowania i płaszczyzny danych są obecnie dostępne w wersji zapoznawczej. Ścieżki punktu końcowego, schematy żądań i odpowiedzi oraz zachowanie mogą ulec zmianie przed ogólną dostępnością. Przypnij integracje do tej wersji interfejsu API i przetestuj je po uaktualnieniu.

Podstawowy adres URL

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

Dołącz sufiks ścieżki z tabeli operations, a następnie dodaj ?api-version=2025-05-01-preview jako parametr zapytania. Na przykład: .../agents/{agentName}/start?api-version=2025-05-01-preview.

Operacje zasobów agenta

Operacja Metoda Sufiks ścieżki
Tworzenie lub aktualizowanie PUT (brak)
Get GET (brak)
Delete DELETE (brak)
Rozpocznij POST /start
Zatrzymaj POST /stop
Pobieranie użycia GET /usages
Pobieranie dziennego użycia GET /dailyusages

Właściwości agenta

Majątek Typ Opis
provisioningState ciąg Succeeded, , Failed, InProgress, CanceledDeleting(tylko do odczytu)
agentEndpoint ciąg Adres URL płaszczyzny danych (tylko do odczytu)
powerState ciąg Running lub Stopped (tylko do odczytu)
outboundIpAddresses string[] Wychodzące adresy IP dla listy dozwolonych (tylko do odczytu)
actionConfiguration.mode ciąg Review, Automatic lub ReadOnly
actionConfiguration.accessLevel ciąg Low lub High
defaultModel.provider ciąg Anthropic lub MicrosoftFoundry (Otwórz sztuczną inteligencję)
defaultModel.name ciąg Nazwa modelu (na przykład Automatic)
upgradeChannel ciąg Stable lub Preview
monthlyAgentUnitLimit number Miesięczny limit AAU przepływu aktywnego (nie obejmuje przepływu zawsze włączonego)
knowledgeGraphConfiguration.identity ciąg Identyfikator zasobu tożsamości zarządzanej
knowledgeGraphConfiguration.managedResources string[] Identyfikatory grup zasobów, do których agent może uzyskać dostęp
logConfiguration obiekt Konfiguracja usługi Application Insights
incidentManagementConfiguration.type ciąg PagerDuty, AzMonitor, ServiceNowlub None
mcpServers string[] Adresy URL serwera MCP
vnetConfiguration.subnetResourceId ciąg Podsieć iniekcji sieci wirtualnej
experimentalSettings obiekt Przesłonięcia flagi funkcji

Zasoby podrzędne

Zasób podrzędny Typ usługi ARM Path
Łączniki Microsoft.App/agents/DataConnectors /DataConnectors/{name}
Umiejętności Microsoft.App/agents/skills /skills/{name}
Subagenci Microsoft.App/agents/subagents /subagents/{name}
Tools Microsoft.App/agents/tools /tools/{name}
Zaplanowane zadania Microsoft.App/agents/scheduledTasks /scheduledTasks/{name}
Filtry zdarzeń Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Punkty zaczepienia Microsoft.App/agents/hooks /hooks/{name}
Typowe monity Microsoft.App/agents/commonPrompts /commonPrompts/{name}

Wszystkie zasoby podrzędne obsługują PUT (tworzenie/aktualizowanie), GETi DELETE operacje.

Formaty treści zasobów podrzędnych

Łączniki używają właściwości bezpośrednich:

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

Inne zasoby podrzędne (umiejętności, podagenty, narzędzia itd.) używają koperty zakodowanej w formacie 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\"}}"

Typy łączników

Typ Value Przypadek użycia
Azure Data Explorer Kusto Wykonywanie zapytań względem klastrów ADX
Application Insights Kusto Wykonywanie zapytań w usłudze App Insights
Analiza dzienników Kusto Log Analytics zapytań
MCP Mcp Łączniki zgodne z programem MCP (Datadog, Splunk itp.)
PagerDuty Mcp Zdarzenia PagerDuty
ServiceNow Mcp Zdarzenia usługi ServiceNow
Outlook Outlook Powiadomienia e-mail
Zespoły Teams Powiadomienia dotyczące kanału usługi Teams

Operacje płaszczyzny danych

Interfejs API płaszczyzny danych umożliwia interakcję z uruchomionym agentem, w tym wysyłanie komunikatów, zarządzanie zatwierdzeniami, przekazywanie wiedzy oraz konfigurowanie repozytoriów, punktów zaczepienia i wyzwalaczy.

Podstawowy adres URL

Pobierz z usługi ARM:

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

Wszystkie ścieżki płaszczyzny danych zaczynają się od $ENDPOINT/api/....

Wątki i czat

Metoda Path Opis
GET /api/v1/threads Wyświetlanie listy wątków konwersacji
GET /api/v1/threads/{threadId} Pobieranie określonego wątku
POST /api/v1/threads/{threadId}/messages Wyślij wiadomość (rozpocznij konwersację)
GET /api/v1/threads/{threadId}/messages Pobieranie komunikatów w wątku

Approvals

Metoda Path Opis
GET /api/v1/approvals/{threadId} Wyświetlanie listy oczekujących zatwierdzeń
POST /api/v1/approvals/{threadId}/{id}/decision Zatwierdzanie lub odrzucanie akcji

Repozytoria kodu

Metoda Path Opis
PUT /api/v2/repos/{repoName} Dodawanie repozytorium kodu
GET /api/v2/repos Wylistuj repozytoria
GET /api/v2/repos/{repoName} Pobieranie szczegółów repozytorium
DELETE /api/v2/repos/{repoName} Usuwanie repozytorium
POST /api/v2/repos/{repoName}/test Testowanie łączności repozytorium

Wiedza (pamięć agenta)

Metoda Path Opis
POST /api/v1/agentmemory/upload Przekazywanie dokumentów (łącznie z wieloma częściami, maksymalnie 100 MB, 16 MB na plik)
GET /api/v1/agentmemory/status Sprawdzanie stanu pamięci
DELETE /api/v1/agentmemory/document/{fileName} Usuwanie dokumentu
DELETE /api/v1/agentmemory/documents Zbiorcze usuwanie dokumentów
GET /api/v1/agentmemory/indexer-status Sprawdzanie postępu indeksatora

Wyzwalacze HTTP

Metoda Path Opis
POST /api/v1/httptriggers/create Tworzenie wyzwalacza HTTP
GET /api/v1/httptriggers Wyzwalacze listy
POST /api/v1/httptriggers/{triggerId}/execute Wykonywanie wyzwalacza
POST /api/v1/httptriggers/trigger/{triggerId} Publiczny punkt końcowy elementu webhook (brak wymaganego uwierzytelniania)

Punkty zaczepienia

Metoda Path Opis
PUT /api/v2/extendedAgent/hooks/{hookName} Tworzenie lub aktualizowanie punktu zaczepienia
GET /api/v2/extendedAgent/hooks Lista punktów zaczepienia
DELETE /api/v2/extendedAgent/hooks/{hookName} Usuwanie haka

Konfiguracja rozszerzonego agenta

Zarządzaj podagentami, narzędziami, łącznikami, umiejętnościami, monitami i wtyczkami za pośrednictwem płaszczyzny danych:

Resource Wzorzec ścieżki
Subagenci /api/v2/extendedAgent/agents/{name}
Tools /api/v2/extendedAgent/tools/{name}
Łączniki /api/v2/extendedAgent/connectors/{name}
Umiejętności /api/v2/extendedAgent/skills/{name}
Typowe monity /api/v2/extendedAgent/commonprompts/{name}
Zaplanowane zadania /api/v2/extendedAgent/scheduledtasks/{name}
Plugins /api/v2/extendedAgent/plugins/{name}

Wszystkie zasoby obsługują PUTmetody , GET, PATCHi DELETE .

Przesyłanie strumieniowe w czasie rzeczywistym

Agent używa usługi SignalR do przesyłania strumieniowego czatu w czasie rzeczywistym:

Koncentrator Path Purpose
AgentHub /agentHub Aktualizacje przesyłania strumieniowego komunikatów i wątków w czasie rzeczywistym

Połącz się przy użyciu biblioteki klienta usługi SignalR z tym samym tokenem elementu nośnego.

Examples

Pobieranie właściwości agenta

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

Wyświetlanie listy wszystkich łączników

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

Wyświetlanie listy wątków za pośrednictwem płaszczyzny danych

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"

Dodawanie repozytorium kodu za pośrednictwem płaszczyzny danych

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

Treści powiązane

  • Last updated on