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

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

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

المتطلبات المسبقه

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

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

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

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

‏‫ملاحظة‬

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

إضافة وكيل مخصص

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

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

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

تحقق من وكيلك

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

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

جهز مشروعك في Foundry project

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

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

   

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

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

   2. في اللوحة اليسرى، اختر المسؤول.

   3. افتح علامة التبويب بوابة الذكاء الاصطناعي .

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

      

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

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

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

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

   2. في اللوحة اليسرى، اختر المسؤول.

   3. تحت جميع المشاريع، استخدم مربع البحث للبحث عن project الخاص بك.

   4. اختر project.

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

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

      

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

تم إعداد project الخاص بك للملاحظة والتتبع.

تسجيل الوكيل

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

2. في جزء نظرة عامة ، حدد تسجيل العامل.

   

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

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

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

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

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

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

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

   

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

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

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

1. اختر الوكيل المخصص.

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

   

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

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

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)

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

‏‫ملاحظة‬

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

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

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

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

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

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

3. اختر الوكيل الذي تريد حظره. تظهر لوحة المعلومات.

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

   

5. قم بتأكيد العملية.

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

لإلغاء حظر العامل:

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

2. قم بتأكيد العملية.

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

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

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

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

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

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

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

3. حدد العامل.

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

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

   

   نصيحة

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

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

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

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

أرسل الآثار إلى مورد Application Insights الخاص ب project جهازك باستخدام مفتاح الأجهزة الخاص به. للحصول على مفتاح الأجهزة المرتبط بمشروعك، اتبع التعليمات في 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، في قسم الآثار .

نصيحة

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

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

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

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

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

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

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

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

• ما هو مايكروسوفت فاوندري كرولبلين؟
• راقب صحة وأداء الوكلاء عبر أسطولك
• تحسين تكلفة وأداء النموذج