مرجع واجهة برمجة التطبيقات لعامل Azure SRE

عمليات واجهة برمجة تطبيقات REST لإدارة Azure SRE Agent والتفاعل معها برمجيا.

نظرة عامة

يوفر Azure SRE Agent واجهات برمجة تطبيقات REST على طبقتين. استخدم مستوى التحكم (ARM) لإنشاء العوامل ومواردها الفرعية وتكوينها وحذفها. استخدم مستوى البيانات لعمليات وقت التشغيل مثل الدردشة وإدارة المستودع وتحميلات المعرفة.

الطائرة عنوان URL الأساسي Auth يستخدم لـ
وحدة التحكم management.azure.com التحكم في الوصول استنادا إلى الدور Azure القياسي إنشاء وتحديث وحذف العوامل والتهيئة
مستوى البيانات نقطة نهاية لكل عامل azuresre.dev الجمهور الدردشة، المستودعات، الخطافات، المعرفة، المشغلات

Authentication

وحدة التحكم (ARM)

مصادقة Azure القياسية - Azure CLI أو كيان الخدمة أو الهوية المدارة:

# 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

مستوى البيانات

يتطلب مستوى البيانات رمزا مميزا منفصلا مع الجمهور 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"

‏‫ملاحظة‬

نقطة نهاية العامل فريدة لكل عامل. يتبع النمط https://{name}--{id}.{hash}.{region}.azuresre.ai وترجع عملية ARM GET نقطة النهاية هذه في properties.agentEndpoint.

أدوار RBAC

دور وصف النطاق
مسؤول وكيل SRE التحكم الكامل في تكوين العامل وعملياته مورد العامل
مستخدم عامل SRE الدردشة والموافقة على الإجراءات وإدارة مؤشرات الترابط مورد العامل
قارئ وكيل SRE الوصول للقراءة فقط إلى تكوين العامل ومؤشرات الترابط مورد العامل

تعيين الأدوار باستخدام مدخل Azure أو CLI أو API ARM:

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

عمليات وحدة التحكم (ARM)

إصدار API

2025-05-01-preview

‏‫ملاحظة‬

كل من وحدة التحكم وواجهات برمجة تطبيقات مستوى البيانات قيد المعاينة حاليا. قد تتغير مسارات نقطة النهاية ومخططات الطلب والاستجابة والسلوك قبل التوفر العام. ثبت عمليات التكامل الخاصة بك بإصدار واجهة برمجة التطبيقات هذا واختبرها بعد الترقيات.

عنوان URL الأساسي

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

ألحق لاحقة المسار من جدول العمليات، ثم أضف ?api-version=2025-05-01-preview كمعلمة استعلام. على سبيل المثال: .../agents/{agentName}/start?api-version=2025-05-01-preview.

عمليات موارد العامل

التشغيل الطريقة لاحقة المسار
إنشاء أو تحديث PUT (لا شيء)
Get GET (لا شيء)
حذف DELETE (لا شيء)
بدء POST /start
إيقاف POST /stop
الحصول على الاستخدامات GET /usages
الحصول على استخدامات يومية GET /dailyusages

خصائص العامل

الملكية النوع وصف
provisioningState string Succeeded، Failed، InProgress، Canceled، Deleting (للقراءة فقط)
agentEndpoint string عنوان URL لمستوى البيانات (للقراءة فقط)
powerState string Running أو Stopped (للقراءة فقط)
outboundIpAddresses سلسلة‬‬ [] عناوين IP الصادرة لقائمة السماح (للقراءة فقط)
actionConfiguration.mode string Review, Automatic, أو ReadOnly
actionConfiguration.accessLevel string Low او High
defaultModel.provider string Anthropic أو MicrosoftFoundry (فتح الذكاء الاصطناعي)
defaultModel.name string اسم النموذج (على سبيل المثال، Automatic)
upgradeChannel string Stable او Preview
monthlyAgentUnitLimit number الحد الأقصى للتدفق النشط الشهري AAU (لا يتضمن التدفق الدائم)
knowledgeGraphConfiguration.identity string معرف مورد الهوية المدارة
knowledgeGraphConfiguration.managedResources سلسلة‬‬ [] معرفات مجموعة الموارد التي يمكن للعامل الوصول إليها
logConfiguration الهدف تكوين Application Insights
incidentManagementConfiguration.type string PagerDutyأو AzMonitorأو ServiceNowأو None
mcpServers سلسلة‬‬ [] عناوين URL لخادم MCP
vnetConfiguration.subnetResourceId string الشبكة الفرعية لحقن الشبكة الظاهرية
experimentalSettings الهدف تجاوزات علامة الميزة

الموارد الفرعية

مورد فرعي نوع ARM المسار
الموصلات Microsoft.App/agents/DataConnectors /DataConnectors/{name}
المهارات Microsoft.App/agents/skills /skills/{name}
العوامل الفرعية Microsoft.App/agents/subagents /subagents/{name}
الأدوات Microsoft.App/agents/tools /tools/{name}
المهام المجدولة Microsoft.App/agents/scheduledTasks /scheduledTasks/{name}
عوامل تصفية الحوادث Microsoft.App/agents/incidentFilters /incidentFilters/{name}
Hooks Microsoft.App/agents/hooks /hooks/{name}
المطالبات الشائعة Microsoft.App/agents/commonPrompts /commonPrompts/{name}

تدعم PUT جميع الموارد الفرعية (إنشاء/تحديث) GETوالعمليات.DELETE

تنسيقات النص الأساسي للموارد الفرعية

تستخدم الموصلات خصائص مباشرة:

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

تستخدم الموارد الفرعية الأخرى (المهارات والأقسام الفرعية والأدوات وما إلى ذلك) مغلفا مشفرا ب 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\"}}"

أنواع الموصلات

النوع القيمة حالة الاستخدام
Azure Data Explorer ‏(Kusto) Kusto الاستعلام عن مجموعات ADX
Application Insights Kusto Query App Insights
تحليلات السجل Kusto Log Analytics الاستعلام
MCP Mcp الموصلات المتوافقة مع MCP (Datadog وSplunk وما إلى ذلك)
PagerDuty Mcp حوادث PagerDuty
ServiceNow Mcp حوادث ServiceNow
Outlook Outlook إعلامات البريد الإلكتروني
Teams Teams إعلامات قناة Teams

عمليات مستوى البيانات

استخدم واجهة برمجة تطبيقات مستوى البيانات للتفاعل مع عامل قيد التشغيل، بما في ذلك إرسال الرسائل وإدارة الموافقات وتحميل المعرفة وتكوين المستودعات والربطات والمشغلات.

عنوان URL الأساسي

الحصول على من ARM:

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

تبدأ جميع مسارات مستوى البيانات ب $ENDPOINT/api/....

مؤشرات الترابط والدردشة

الطريقة المسار وصف
GET /api/v1/threads سرد مؤشرات ترابط المحادثة
GET /api/v1/threads/{threadId} الحصول على مؤشر ترابط معين
POST /api/v1/threads/{threadId}/messages إرسال رسالة (بدء محادثة)
GET /api/v1/threads/{threadId}/messages الحصول على رسائل في مؤشر ترابط

الموافقات

الطريقة المسار وصف
GET /api/v1/approvals/{threadId} قائمة الموافقات المعلقة
POST /api/v1/approvals/{threadId}/{id}/decision الموافقة على إجراء أو رفضه

مستودعات التعليمات البرمجية

الطريقة المسار وصف
PUT /api/v2/repos/{repoName} إضافة مستودع التعليمات البرمجية
GET /api/v2/repos سرد المستودعات
GET /api/v2/repos/{repoName} الحصول على تفاصيل المستودع
DELETE /api/v2/repos/{repoName} إزالة مستودع
POST /api/v2/repos/{repoName}/test اختبار اتصال المستودع

المعرفة (ذاكرة العامل)

الطريقة المسار وصف
POST /api/v1/agentmemory/upload تحميل المستندات (متعدد الأحزاب، إجمالي 100 ميغابايت كحد أقصى، 16 ميغابايت لكل ملف)
GET /api/v1/agentmemory/status التحقق من حالة الذاكرة
DELETE /api/v1/agentmemory/document/{fileName} حذف مستند
DELETE /api/v1/agentmemory/documents حذف المستندات بشكل مجمع
GET /api/v1/agentmemory/indexer-status التحقق من تقدم المفهرس

مشغلات HTTP

الطريقة المسار وصف
POST /api/v1/httptriggers/create إنشاء محفز HTTP
GET /api/v1/httptriggers مشغلات القائمة
POST /api/v1/httptriggers/{triggerId}/execute تنفيذ مشغل
POST /api/v1/httptriggers/trigger/{triggerId} نقطة نهاية إخطار على الويب العامة (لا يلزم المصادقة)

Hooks

الطريقة المسار وصف
PUT /api/v2/extendedAgent/hooks/{hookName} إنشاء خطاف أو تحديثه
GET /api/v2/extendedAgent/hooks قائمة الخطافات
DELETE /api/v2/extendedAgent/hooks/{hookName} حذف خطاف

تكوين العامل الموسع

إدارة الأقسام الفرعية والأدوات والموصلات والمهارات والمطالبات والمكونات الإضافية من خلال مستوى البيانات:

المصدر نمط المسار
العوامل الفرعية /api/v2/extendedAgent/agents/{name}
الأدوات /api/v2/extendedAgent/tools/{name}
الموصلات /api/v2/extendedAgent/connectors/{name}
المهارات /api/v2/extendedAgent/skills/{name}
المطالبات الشائعة /api/v2/extendedAgent/commonprompts/{name}
المهام المجدولة /api/v2/extendedAgent/scheduledtasks/{name}
Plugins /api/v2/extendedAgent/plugins/{name}

تدعم PUTجميع الموارد الأساليب GETPATCHوDELETE.

البث في الوقت الحقيقي

يستخدم العامل SignalR لتدفق الدردشة في الوقت الحقيقي:

محور المسار الغرض
AgentHub /agentHub تدفق الرسائل في الوقت الحقيقي وتحديثات مؤشر الترابط

الاتصال باستخدام مكتبة عميل SignalR بنفس الرمز المميز للحامل.

أمثلة

الحصول على خصائص العامل

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

سرد كافة الموصلات

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

سرد مؤشرات الترابط عبر مستوى البيانات

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"

إضافة مستودع التعليمات البرمجية عبر مستوى البيانات

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

المحتوى ذو الصلة

  • Last updated on