نشر وكيل مستضاف

توضح لك هذه المقالة كيفية نشر وكيل محوى في خدمة Foundry Agent باستخدام Python SDK أو REST API. استخدم هذه الأساليب عندما ترغب في إدارة نشر الوكلاء مباشرة من تطبيقاتك أو خدماتك.

إذا كنت تنشر لأول مرة أو ترغب في أسرع مسار، استخدم خيار البدء السريع: إنشاء ونشر وكيل مستضاف بدلا من ذلك. تستخدم البداية السريعة Azure Developer CLI (azd) أو VS Code، والتي تتولى بناء ودفع وإصدار وتكوين RBAC تلقائيا.

دورة حياة النشر

كل نشر للوكيل المستضاف يتبع هذا التسلسل:

  1. Build and push — قم بتغليف كود الوكيل في صورة حاوية وادفعها إلى Azure Container Registry.
  2. إنشاء نسخة وكيل — سجل الصورة في خدمة وكلاء Foundry. توفر المنصة بنية تحتية وتنشئ هوية وكيل مخصصة ل Entra.
  3. استطلاع للحالة — انتظر حتى تصل activeحالة الإصدار إلى .
  4. الاستدعاء — إرسال الطلبات إلى نقطة النهاية المخصصة للوكيل.

المتطلبات الأساسية

الصلاحيات المطلوبة

تحتاج إلى Azure مدير Project الذكاء الاصطناعي في نطاق project لإنشاء ونشر وكلاء مستضافة. يشمل هذا الدور كل من صلاحيات مستوى البيانات لإنشاء الوكلاء والقدرة على تعيين دور المستخدم الذكي Azure لهوية الوكيل التي تنشئه المنصة. تحتاج هوية الوكيل إلى Azure AI User في المشروع للوصول إلى النماذج والقطع الأثرية أثناء وقت التشغيل.

إذا كنت تستخدم azd إضافة VS Code، فإن الأدوات تتعامل مع معظم تعيينات RBAC تلقائيا، بما في ذلك:

  • قارئ مستودع سجل الحاويات لهوية المشروع المدارة (سحب الصور)
  • Azure مستخدم الذكاء الاصطناعي لهوية الوكيل التي أنشأها المنصة (نموذج وقت التشغيل والوصول إلى الأداة)

ملاحظة

تنشئ المنصة هوية وكيل إنترا مخصصة لكل وكيل مستضاف في وقت النشر. هذه الهوية هي مبدأ خدمة تستخدمه الحاوية التشغيلية لاستدعاء النماذج والأدوات. لا تحتاج إلى تكوين الهويات المدارة يدويا. ومع ذلك، يجب أن يكون لدى المستخدم الذي ينشئ الوكيل إذن بتعيين Azure AI User لتلك الهوية — ولهذا السبب يوصى ب Azure AI Project Manager على Azure AI User فقط.

ملاحظة

بينما تتعامل امتدادات azd وVS Code مع تعيينات RBAC الأساسية تلقائيا، قد تتطلب السيناريوهات المعقدة إعدادا يدويا إضافيا. للحصول على تفاصيل شاملة حول جميع الأذونات وتوزيع الأدوار المعنية، راجع مرجع أذونات الوكيل المستضاف.

لمزيد من المعلومات، راجع المصادقة والتفويض.

مهم

يجب أن يكون Azure Container Registry الذي يحتفظ بصورة الحاوية الخاصة بوكيلك المستضاف متاحا حاليا عبر نقطة النهاية العامة. وضع السجل خلف شبكة خاصة (نقطة نهاية خاصة مع تعطيل الوصول إلى الشبكة العامة) غير مدعوم حاليا للوكلاء المستضافين — فالمنصة لا تستطيع سحب الصورة. للحصول على القائمة الكاملة لقيود الشبكة، راجع القيود.

متطلبات الحاويات

يجب أن تستوفي صورة الحاوية الخاصة بك المتطلبات التالية لتعمل على منصة الوكيل المستضاف.

مهم

تتطلب منصة الاستضافة x86_64 صور الحاويات (linux/amd64). إذا بنيت على Apple Silicon أو أجهزة أخرى تعتمد على ARM، استخدمها docker build --platform linux/amd64 . لتجنب إنتاج صورة ARM غير متوافقة.

مكتبات البروتوكول

يتواصل الوكلاء المستضيفون مع بوابة Foundry عبر مكتبات البروتوكولات. اختر البروتوكول الذي يتوافق مع نمط تفاعل وكيلك:

البروتوكول مكتبة Python مكتبة .NET نقطة النهاية الأفضل ل
الردود azure-ai-agentserver-responses Azure.AI.AgentServer.Responses /responses روبوتات دردشة حوارية، بث، تعدد الأدوار مع تاريخ مدار من المنصة
الدعاءات azure-ai-agentserver-invocations Azure.AI.AgentServer.Invocations /invocations مستقبلات Webhook، معالجة غير حوارية، سير عمل غير متزامن مخصص

يمكن لحاوية واحدة أن تكشف البروتوكولين في نفس الوقت عن طريق إعلان كلاهما عند إنشاء الوكيل — في agent.yaml ملف أو استدعاء SDK أو طلب واجهة برمجة تطبيقات REST — واستيراد كلا المكتبتين. استخدم مكتبات البروتوكول داخل إطار العمل الحالي، سواء كان ذلك Microsoft Agent Framework، أو LangChain، أو كود مخصص.

نقاط النهاية الصحية

تكشف مكتبات البروتوكول تلقائيا نقطة /readiness نهاية لفحوصات صحة المنصة. لا تحتاج إلى تنفيذ ذلك بنفسك.

الميناء

تخدم الحاويات حركة المرور على الميناء 8088 محليا. في الإنتاج، تتولى بوابة Foundry التوجيه — لا تحتاج الحاوية إلى كشف منفذ عام.

متغيرات البيئة المحقونة بالمنصة

تقوم منصة الوكيل المستضاف تلقائيا بحقن متغيرات البيئة في الحاوية أثناء وقت التشغيل. يمكن لكودك قراءة هذه دون إعلانها في agent.yaml أو environment_variables. FOUNDRY_* البادئة مخصصة للاستخدام على المنصة.

المتغير الغرض
FOUNDRY_PROJECT_ENDPOINT رابط نقطة نهاية مشروع Foundry
FOUNDRY_PROJECT_ARM_ID معرف مورد مشروع Foundry ARM
FOUNDRY_AGENT_NAME اسم الوكيل الجاري
FOUNDRY_AGENT_VERSION نسخة من وكيل الجار
FOUNDRY_AGENT_SESSION_ID معرف الجلسة للطلب الحالي (الحاويات المستضافة فقط)
APPLICATIONINSIGHTS_CONNECTION_STRING Application Insights سلسلة الاتصال للقياس عن بعد

لا تعيد إعلان المتغيرات agent.yaml المحقونة في المنصة — فهي تضبط تلقائيا.

المتغيرات التي تعلن عنها بنفسك، مثل MODEL_DEPLOYMENT_NAME نقاط نهاية MCP في صندوق الأدوات، تدخل في environment_variables قسم agent.yaml أو استدعاء SDK create_version .

قم بتغليفك واختباره محليا

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

اختبار بروتوكول الاستجابات

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

اختبار بروتوكول الاستدعاءات

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

النشر باستخدام Azure Developer CLI أو VS Code

تقوم Azure Developer CLI (azd) وإضافة VS Code بأتمتة دورة حياة النشر الكاملة. للحصول على دليل خطوة بخطوة، راجع البدء السريع: إنشاء ونشر وكيل مستضاف.

النشر باستخدام حزمة تطوير Python SDK

استخدم SDK عندما تريد إدارة نشر الوكلاء مباشرة من كود Python.

متطلبات إضافية

  • Python 3.10 أو أحدث

  • صورة حاوية بنظام Azure Container Registry

  • كاتب مستودع سجل الحاويات أو دور AcrPush على سجل الحاويات (لدفع الصور)

  • Azure AI Projects SDK الإصدار 2.1.0 أو أحدث

    pip install "azure-ai-projects>=2.1.0"

ابن ودفع صورة الحاوية الخاصة بك

  1. ابن صورة Docker الخاصة بك:

    docker build --platform linux/amd64 -t myagent:v1 .

    انظر ملفات Dockerfiles النموذجية ل Python و C#‎.

  2. Push to Azure Container Registry:

    az acr login --name myregistry
docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
docker push myregistry.azurecr.io/myagent:v1

نصيحة

استخدم علامات الصور الفريدة بدلا من :latest النشر القابل للتكرار.

تكوين صلاحيات سجل الحاويات

امنح هوية مشروعك المدارة حق الوصول لسحب الصور:

  1. في بوابة Azure، انتقل إلى مورد مشروع Foundry الخاص بك.

  2. اختر Identity وانسخ معرف الكائن (الرئيسي) تحت النظام المخصص.

  3. قم بتعيين دور قارئ مستودع سجل الحاويات لهذا الهوية في سجل الحاويات الخاص بك. انظر Azure Container Registry الأدوار والأذونات.

إنشاء نسخة وكيل مستضاف

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

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

لعرض كلا البروتوكولين، مرر كلاهما في container_protocol_versions:

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0")
],

المعايير الرئيسية:

المعلمة الوصف
agent_name اسم فريد (أبجدي رقمي مع شرطات، الحد الأقصى 63 حرفا)
image Full Azure Container Registry image URL with tag
cpu تخصيص وحدة المعالجة المركزية (على سبيل المثال، "1")
memory تخصيص الذاكرة (على سبيل المثال، "2Gi")
container_protocol_versions البروتوكولات التي تعرضها الحاوية (responses, invocations, أو كلاهما)

استطلاع لحالة الإصدار

بعد إنشاء نسخة، قم بالاستطلاع حتى تصل active الحالة قبل استدعاء الوكيل. عادة ما يستغرق الإعداد أقل من دقيقة حسب حجم الصورة.

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

قيم حالة الإصدارات:

الحالة الوصف
creating توفير البنية التحتية جار
active الوكيل جاهز لتلبية الطلبات
failed فشل التوفير — تحقق error من الحقل للتفاصيل
deleting النسخة قيد التنظيف
deleted تمت إزالة النسخة بالكامل

استدعاء الوكيل

بعد أن يصل active الإصدار إلى الحالة، استخدم get_openai_client لإنشاء عميل OpenAI مرتبط بنقطة نهاية الوكيل.

بالنسبة لبروتوكول الاستجابات :

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

بالنسبة لبروتوكول الاستدعاءات ، استدعي نقطة نهاية الاستدعاءات مباشرة:

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

للحصول على أمثلة أكثر شمولا، راجع عينات الوكلاء المستضافة.

نشر باستخدام واجهة برمجة تطبيقات REST

استخدم واجهة برمجة تطبيقات REST للنشر المباشر المعتمد على HTTP أو عند التكامل مع أدوات مخصصة.

قبل أن تبدأ، قم ببناء ودفع صورة الحاوية الخاصة بكوقم بتكوين صلاحيات سجل الحاويات.

إعداد المتغيرات

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

إنشاء وكيل

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

إنشاء وكيل أيضا ينشئ النسخة 1 ويفعل التفكير.

استطلاع لحالة الإصدار

استطلاع نقطة نهاية الإصدار حتى status يكون:active

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

استدعاء الوكيل

استخدم نقطة النهاية المخصصة للوكيل لإرسال الطلبات. قم بضبط "stream": true لاستقبال الأحداث المرسلة من الخادم.

بروتوكول الردود:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

بروتوكول الاستدعاءات:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

أنشئ نسخة جديدة

نشر الكود أو التكوين المحدث عن طريق إنشاء نسخة جديدة:

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

موارد التنظيف

لتجنب التقاضي، قم بتنظيف الموارد عند الانتهاء. يتم إلغاء تخصيص حساب الوكيل بعد 15 دقيقة من عدم النشاط، لذا لا توجد تكلفة عندما لا يقوم الوكيل بخدمة الطلبات.

تنظيف Azure Developer CLI

azd down

تنظيف SDK

حذف نسخة واحدة:

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

أو حذف الوكيل بالكامل وجميع إصداراته:

project.agents.delete(agent_name="my-agent")

تنظيف واجهة برمجة التطبيقات REST

حذف نسخة واحدة:

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

أو حذف الوكيل بالكامل:

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

تحذير

حذف وكيل يزيل جميع نسخه وينهي الجلسات النشطة. هذا الفعل لا يمكن التراجع عنه.

استكشاف الأخطاء

تظهر أخطاء التوفير في كائنات error.code الإصدار والحقول error.message . تحقق من حالة الإصدار بعد الإنشاء لتحديد المشاكل.

رمز الخطأ رمز HTTP الحل
image_pull_failed 400 تحقق من صحة URI للصورة وأن هوية المشروع المدارة تحتوي على قارئ مستودع سجل الحاويات على ACR
SubscriptionIsNotRegistered 400 سجل مزود الاشتراك
InvalidAcrPullCredentials 401 إصلاح RBAC للهوية المدارة أو السجل
UnauthorizedAcrPull 403 قدم الشهادات أو الهوية الصحيحة
AcrImageNotFound 404 تصحيح اسم/وسم الصورة أو نشر الصورة
RegistryNotFound 400/404 إصلاح DNS في السجل أو إمكانية الوصول إلى الشبكة

للحصول على أخطاء 5xx، تواصل مع دعم Microsoft.

للحصول على متطلبات RBAC التفصيلية واستكشاف أخطاء الأذونات، راجع مرجع صلاحيات الوكيل المستضاف.

الخطوات التالية

إدارة دورة حياة الوكيل المستضاف

محتوى ذو صلة

  • Last updated on