تسجيل وإدارة الوكلاء المخصصين

يوفر Microsoft Foundry Control Plane إدارة مركزية وقابلية للرصد للوكلاء الذين يعملون عبر منصات وبنى تحتية مختلفة. يمكنك تسجيل وكلاء مخصصين يعملون في خدمات الحوسبة Azure أو بيئات سحابية أخرى للحصول على رؤية لعملياتهم والتحكم في سلوكهم.

توضح لك هذه المقالة كيفية تسجيل وكيل مخصص في مستوى التحكم في مسبك. تتعلم كيفية إعداد وكيلك للتسجيل، وإعداد جمع البيانات، واستخدام قدرات إدارة Foundry Control Plane.

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

• حساب Azure مع اشتراك نشط. إذا لم يكن لديك واحد، أنشئ حساب Azure مجاني مجاني، يشمل اشتراكا تجريبيا مجانيا.

• مشروع مسبك. إذا لم يكن لديك مشروع، أنشئ مشروعا.

• بوابة ذكاء اصطناعي مهيأة في مورد Foundry الخاص بك. يستخدم Foundry إدارة Azure API لتسجيل الوكلاء كواجهات برمجة تطبيقات (APIs).

• وكيل تقوم بنشره وعرضه من خلال نقطة نهاية يمكن الوصول إليها. يمكن أن تكون نقطة النهاية إما نقطة نهاية عامة أو نقطة نهاية يمكن الوصول إليها من خلال الشبكة التي تنشر فيها مورد Foundry.

ملاحظة

هذه القدرة متاحة فقط في بوابة Foundry (الجديدة). ابحث في لافتة البوابة لتتأكد من أنك تستخدم Foundry (جديد).

أضف وكيل مخصص

يمكنك تسجيل وكيل مخصص في Foundry Control Plane. طور الوكيل في التكنولوجيا التي تختارها، سواء للمنصات أو للبنية التحتية المختلفة.

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

يوضح المخطط التالي البنية الناتجة عند تسجيل وكيل مخصص.

تحقق من وكيلك

تحقق من أن وكيلك يستوفي متطلبات التسجيل:

• وكيلك يكشف عن نقطة نهاية حصرية.
• الشبكة التي تنشر فيها مورد Foundry يمكنها الوصول إلى نقطة نهاية الوكيل.
• يتواصل الوكيل باستخدام أحد البروتوكولات المدعومة: HTTP (عام) أو A2A (أكثر تحديدا).
• يقوم وكيلك بإرسال البيانات باستخدام قواعد دلالية OpenTelemetry لحلول الذكاء الاصطناعي التوليدي (أو أنك لا تحتاج إلى هذه القدرة).
• يمكنك تكوين نقطة النهاية التي يستخدمها المستخدمون للتواصل مع الوكيل. بعد تسجيل وكيل، يقوم Foundry Control Plane بإنشاء عنوان URL جديد. يجب على العملاء والمستخدمين استخدام هذا الرابط للتواصل مع الوكيل.

جهز مشروع Foundry الخاص بك

قبل تسجيل الوكيل المخصص الذي أضفته إلى مشروع Foundry، تأكد من أنك قمت بتكوين المشروع بشكل صحيح:

1. سجل الدخول إلى Microsoft Foundry. تأكد من تفعيل مفتاح New Foundry . تشير هذه الخطوات إلى Foundry (جديد).

   

2. تأكد من أن بوابة الذكاء الاصطناعي مهيأة في مشروعك:

   1. على شريط الأدوات، حدد إدارة.

   2. في الجزء الأيمن، حدد AI Gateway.

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

      

   4. إذا لم يكن لدى مورد Foundry الذي تريد استخدامه بوابة ذكاء اصطناعي معدة (غير مدرجة)، أضف واحدة باستخدام خيار إضافة بوابة الذكاء الاصطناعي .

      بوابة الذكاء الاصطناعي مجانية في إعداد وفتح ميزات حوكمة قوية مثل الأمان، والبيانات التشخيصية، وحدود الأسعار لوكلائك وأدواتك ونماذجك. لمزيد من المعلومات، راجع إنشاء بوابة ذكاء اصطناعي.

3. تأكد من أن لديك قابلية الرصد مضبوطة في المشروع. يستخدم Foundry Control Plane مورد Application Insights المرتبط بمشروعك المختار لإرسال البيانات لمساعدتك في تشخيص وكيلك.

   1. على شريط الأدوات، حدد إدارة.

   2. في الجزء الأيمن، حدد Project التفاصيل.

   3. اختر تبويب الموارد المتصلة .

   4. تأكد من وجود مورد مرتبط في فئة AppInsights الخاصة ب AppSights .

      

   5. إذا لم يكن هناك مورد مرتبط، أضف واحدا باختيار إضافةبرؤى تطبيقات>.

مشروعك مهيأ ليكون قابلية الملاحظة والتتبع.

تسجيل الوكيل (الأصل)

1. في شريط الأدوات، اختر تشغيل.

2. في قسم النظرة العامة ، اختر تسجيل الأصل.

   

3. يظهر ساحر التسجيل. أولا، أكمل التفاصيل عن الوكيل الذي ترغب في تسجيله. الخصائص التالية تصف الوكيل أثناء تشغيله على منصته:

   الملكية	الوصف	مطلوب
   رابط الوكيل	نقطة النهاية (URL) حيث يقوم وكيل الطلبات بتشغيل واستلام الطلبات. بشكل عام، لكن حسب بروتوكولك، تشير إلى عنوان URL الأساسي الذي يستخدمه عملاؤك. على سبيل المثال، إذا كان وكيلك يستخدم واجهة OpenAI لإكمال الدردشة، فأنت تشير https://<host>/v1/ إلى الإشارة إلى اللعبة لأن /chat/completions العملاء عادة يضيفونها.	نعم
   البروتوكول	بروتوكول التواصل الذي يدعمه وكيلك. استخدم HTTP بشكل عام. أو إذا كان وكيلك يدعم A2A بشكل أكثر تحديدا، حدد ذلك.	نعم
   رابط بطاقة الوكيل A2A	المسار إلى مواصفات JSON الخاصة ببطاقة الوكيل. إذا لم تحددها، النظام يستخدم الإعداد الافتراضي /.well-known/agent-card.json.	نعم، عندما يكون البروتوكولA2A
   معرف وكيل OpenTelemetry	معرف الوكيل الذي يستخدمه وكيلك لإصدار التتبع يتوافق مع القواعد الدلالية لنظام OpenTelemetry للذكاء الاصطناعي التوليدي. تشير الآثار إلى ذلك في gen_ai.agent.id السمة للامتدادات التي تحمل اسم create_agentالعملية . إذا لم تحدد هذه القيمة، يستخدم النظام قيمة اسم الوكيل للعثور على المسارات والسجلات التي يبلغ عنها هذا الوكيل الجديد.	لا
   رابط بوابة الإدارة	رابط بوابة الإدارة حيث يمكنك تنفيذ عمليات إدارة إضافية لهذا الوكيل. يمكن للمفاوندري تخزين هذه القيمة من أجل الراحة. لا يملك Foundry أي وصول لتنفيذ العمليات مباشرة إلى هذه البوابة.	لا

4. قم بضبط الطريقة التي تريد بها ظهور الوكيل في مستوى التحكم في Foundry:

   الملكية	الوصف	مطلوب
   Project	المشروع الذي تسجل فيه الوكيل. يستخدم Foundry بوابة الذكاء الاصطناعي المهيأة في المورد الذي يحتوي على المشروع لتكوين نقطة النهاية الواردة إلى الوكيل. يمكنك اختيار المشاريع فقط التي تحتوي على بوابة ذكاء اصطناعي مفعلة في مواردها. إذا لم تر أي بوابات ذكاء اصطناعي، قم بتكوين بوابة ذكاء اصطناعي في مورد Foundry الخاص بك. كما نوصي بتكوين رؤى التطبيقات في المشروع المحدد. تستخدم فاوندري مورد Application Insights الخاص بالمشروع لاستخراج الآثار والسجلات.	نعم
   اسم الوكيل	اسم الوكيل كما تريد أن يظهر في Foundry. قد يستخدم النظام هذا الاسم أيضا للعثور على الآثار والسجلات ذات الصلة في Application Insights إذا لم تحدد قيمة مختلفة لمعرف وكيل OpenTelemetry.	نعم
   الوصف	وصف واضح لهذا العميل.	لا

5. احفظ التغييرات.

6. أضافت فاوندري الوكيل الجديد. للتحقق من قائمة الوكلاء، اختر الأصول في اللوحة اليسرى.

7. لعرض الوكلاء المخصصين فقط، استخدم فلتر المصدر واختر مخصص.

   

ربط العملاء بالوكيل

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

لتوزيع الرابط الجديد بحيث يتمكن عملاؤك من الاتصال بالوكيل:

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

2. في لوحة المعلومات، تحت عنوان الوكيل، اختر خيار النسخ .

   

3. استخدم عنوان URL الجديد لاستدعاء الوكيل بدلا من نقطة النهاية الأصلية.

في هذا المثال، تقوم بنشر وكيل LangGraph. يستخدم العملاء مجموعة تطوير البرمجيات الخاصة ب LangGraph لاستهلاكها. يستخدم العميل قيمة URL الجديدة للوكيل . هذا الكود ينشئ خيطا، ويرسل رسالة تسأل عن الطقس، ويرسل الرد مرة أخرى.

import asyncio
from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/")

async def stream_run():
    thread = await client.threads.create()
    input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}

    async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
        print(chunk)

asyncio.run(stream_run())

الناتج المتوقع: يعالج الوكيل الرسالة ويعيد إرسال الردود على شكل قطع. كل جزء يحتوي على نتائج جزئية من تنفيذ الوكيل. قد تشمل هذه النتائج استدعاءات أدوات لدالة الطقس والرد النهائي حول طقس لوس أنجلوس.

ملاحظة

على الرغم من أن Foundry يعمل كوكيل للطلبات الواردة لوكيلك، إلا أن مخطط التفويض والمصادقة الأصلي في نقطة النهاية الأصلية لا يزال ساريا. عندما تستهلك نقطة النهاية الجديدة، قدم نفس آلية المصادقة كما لو كنت تستخدم النقطة الأصلية.

حجب وإلغاء حظر الوكيل

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

لحجب الطلبات الواردة إلى وكيلك:

1. في شريط الأدوات، اختر تشغيل.

2. في اللوحة اليسرى، اختر الأصول.

3. اختر زر الراديو بجانب الوكيل الذي تريد حظره. تظهر لوحة المعلومات. لا تختار اسم الوكيل، لأن هذا الرابط يبتعد عن لوحة الأصول .

4. اختر حالة التحديث، ثم اختر الحظر.

   

5. أكد العملية.

بعد حظر الوكيل، يتم حظر قيمة الحالة للوكيل في Foundry. الوكلاء في الحالة المحظوبة يعملون في البنية التحتية المرتبطة بهم لكن لا يمكنهم استقبال الطلبات الواردة. يقوم Foundry بحظر أي محاولة للتواصل مع الوكيل.

لرفع الحظر عن الوكيل:

1. اختر حالة التحديث، ثم اختر رفع الحظر.

2. أكد العملية.

تمكين بيانات التشخيص للوكيل

يستخدم فاوندري معيار OpenTelemetry المفتوح لفهم ما يفعله الوكلاء. إذا كان مشروعك يحتوي على Application Insights مهيأ، يقوم Foundry بتسجيل الطلبات في Application Insights بشكل افتراضي. تستخدم Foundry أيضا هذه البيانات لحساب:

• السلاسل
• معدل الخطأ
• الاستخدام (إذا كان متاحا)

للحصول على أفضل مستوى من الدقة، تتوقع Foundry من الوكلاء المخصصين الامتثال للقواعد الدلالية لحلول الذكاء الاصطناعي التوليدي ضمن معيار OpenTelemetry.

عرض الآثار والسجلات المرسلة إلى Foundry

1. في شريط الأدوات، اختر تشغيل.

2. في اللوحة اليسرى، اختر الأصول.

3. اختر زر الراديو بجانب الوكيل لفتح لوحة المعلومات. لا تختار اسم الوكيل، لأن هذا الرابط يبتعد عن لوحة الأصول .

4. يظهر قسم التتبع إدخال واحد لكل استدعاء HTTP يتم إلى نقطة نهاية الوكيل.

   لرؤية التفاصيل، اختر إدخالا.

   

   نصيحة

   في هذا المثال، يمكنك رؤية كيف يستخدم العملاء نقطة نهاية الوكيل الجديد للتواصل مع الوكيل. يظهر المثال وكيلا تم تقديمه مع بروتوكول الوكيل من LangChain. يستخدم العملاء المسار /runs/stream.

في هذا المثال، التتبع لا يتضمن أي تفاصيل تتجاوز منشور HTTP. رمز الوكيل لا يتضمن أي أجهزة إضافية. في القسم التالي، تتعلم كيفية تجهيز كودك بالآلات والحصول على تفاصيل مثل استدعاءات الأدوات ونماذج اللغة الكبيرة (LLM).

وكلاء الشيفرة المخصصة للآلات

إذا قمت ببناء وكيلك باستخدام كود مخصص، قم بتركيب أداة لإرسال الآثار وفقا لمعيار OpenTelemetry وإرسلها إلى Application Insights. تمنح الأجهزة Foundry إمكانية الوصول إلى معلومات مفصلة حول ما يقوم به وكيلك.

أرسل الآثار إلى مورد Application Insights الخاص بمشروعك باستخدام مفتاح الأجهزة الخاص به. للحصول على مفتاح الأجهزة المرتبط بمشروعك، اتبع التعليمات في Connect Application Insights إلى مشروع Foundry الخاص بك.

في هذا المثال، تقوم بتكوين وكيل تم تطويره باستخدام LangGraph لإصدار الآثار في معيار OpenTelemetry. يلتقط المتتبع جميع عمليات الوكلاء، بما في ذلك استدعاءات الأدوات وتفاعلات النماذج. ثم يرسل المتتبع العمليات إلى Application Insights للمراقبة.

يستخدم هذا الكود حزمة langchain-azure-ai . للحصول على إرشادات حول أدوات الحلول المحددة باستخدام OpenTelemetry، اعتمادا على لغة البرمجة والإطار الذي يستخدمه الحل، راجع واجهات برمجة التطبيقات ومجموعات تطوير اللغات.

pip install -U langchain-azure-ai[opentelemetry]

ثم، قم بتسجيل أداة لوكيلك:

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = "InstrumentationKey=12345678-..."

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

المخرج المتوقع: يعمل الوكيل بشكل طبيعي أثناء إرسال تتبع OpenTelemetry تلقائيا إلى Application Insights. تشمل الآثار أسماء العمليات، والمدة، واستدعاءات النماذج، واستدعاءات الأدوات، واستخدام الرموز. يمكنك مشاهدة هذه الآثار في بوابة Foundry، في قسم الآثار .

نصيحة

يمكنك تمرير سلسلة الاتصال إلى Application Insights باستخدام متغير البيئة APPLICATIONINSIGHTS_CONNECTION_STRING.

حلول منصة الأدوات

إذا كان وكيلك يعمل على حل منصة يدعم OpenTelemetry لكنه لا يدعم Application Insights، قم بنشر جامع OpenTelemetry وقم بتكوين برنامجك لإرسال بيانات OTLP إلى المجمع (تكوين OpenTelemetry القياسي).

قم بتكوين المجمع باستخدام مصدر Azure Monitor لإعادة توجيه البيانات إلى Application Insights باستخدام سلسلة الاتصال الخاص بك. للحصول على تفاصيل حول كيفية تنفيذها، راجع Configure Azure Monitor OpenTelemetry.

استكشاف الأخطاء وإصلاحات التتبع

إذا لم تر آثارا، تحقق من العناصر التالية:

• المشروع الذي تسجل فيه وكيلك يحتوي على Application Insights مهيأ. إذا قمت بإعداد Application Insights بعد تسجيل الوكيل المخصص، عليك إلغاء تسجيل الوكيل وتسجيله مرة أخرى. إعدادات Application Insights لا يتم تحديثها تلقائيا بعد التسجيل إذا قمت بتغييرها.
• لقد قمت بتكوين الوكيل (الذي يعمل على بنية تحته) لإرسال التتبع إلى Application Insights، وأنت تستخدم نفس مورد Application Insights الذي يستخدمه مشروعك.
• تلتزم الأجهزة بمعايير دلالية OpenTelemetry للذكاء الاصطناعي التوليدي.
• تشمل الآثار امتدادات مع السمة gen_ai.operation.name="create_agent" و gen_ai.agent.id="<agent-id>" (أو gen_ai.agent.name="<agent-id>"). في السمة الأخيرة، "<agent-id>" هي قيمة معرف وكيل OpenTelemetry التي قمت بتهيئة أثناء التسجيل.

محتوى ذو صلة

• ما هي طائرة التحكم Microsoft Foundry؟
• راقب صحة وأداء الوكلاء عبر أسطولك