الترحيل إلى Microsoft Agent 365 SDK 2.0

Microsoft Agent 365 SDK 2.0 متوفر ل Python وJavaScript و.NET. يتضمن هذا الإصدار تغييرات جذرية، لكن معظمها يؤثر فقط على حزم الرصد المهجورة، ولكل تغيير مسار ترحيل مباشر. استخدم هذا المقال للعثور على التغييرات التي تنطبق على وكيلك وتحديث الكود الخاص بك.

ملخص التغييرات غير المتوافقة

Area Languages Change الإجراء
الإعلامات Python تغيرت القيمة AgentLifecycleEvent.USERDELETED . قم بتحديث الكود الذي يقارن بقيمة السلسلة الخام.
امتدادات الأدوات .NET authToken لم يعد يُجري مصادقة خوادم MCP. مرر UserAuthorization و authHandlerName، أو حدد متغيرات البيئة BEARER_TOKEN.
وقت التشغيل Python get_observability_authentication_scope() يعيد النطاق الخاص بالتطبيق فقط /.default . استخدم النطاق مع محلّل رمز مميز خاص بالتطبيق فقط.
تصدير إمكانية المراقبة Python، JavaScript، .NET يستخدم التصدير دائمًا نقطة النهاية من خدمة إلى خدمة (S2S) ويتطلب مكوّن حلّ الرموز المميّزة الخاص بالتطبيق فقط. استبدل رمز التفويض المميز بمُحلِّل خاص بالتطبيق فقط.
القياس عن بُعد لقابلية الملاحظة Python, JavaScript, .NET تم تغيير سمات الرسالة، وأسماء السمات، والتحقق من صحة الاستدلال. قم بتحديث الكود، والاستعلامات، ولوحات المعلومات التي تعتمد على التنسيق السابق.

Note

تم إهمال حزم قابلية المراقبة. لا تزال SDK 2.0 تنشرها، لكن لا تستخدمها في تكاملات جديدة. بدلا من تحديث تكامل إمكانية الملاحظة الحالي إلى SDK 2.0، فكر في الانتقال إلى توزيعة Microsoft OpenTelemetry.

قم بتحديث حزمك إلى Agent 365 SDK 2.0

قم بتحديث كل حزمة SDK من Agent 365 في مشروعك إلى الإصدار 2.0 في نفس الوقت. للاطلاع على القائمة الكاملة للحزم، انظر حزم Agent 365 SDK.

pip install --upgrade microsoft-agents-a365-notifications microsoft-agents-a365-tooling microsoft-agents-a365-runtime

أضف أي حزم Agent 365 أخرى يستخدمها وكيلك، مثل امتدادات الأدوات، إلى نفس الأمر.

الإخطارات

راجع قيمة حدث دورة الحياة المحدثة والأحداث الجديدة المتاحة في SDK 2.0.

Python: تغيّرت قيمة حدث دورة حياة المستخدم المحذوف

AgentLifecycleEvent.USERDELETED القيمة الآن agenticuserdeletedهي . في الإصدارات السابقة، كانت القيمة هي agenticuseridentitydeleted.

إذا كان كودك يقارن حدث دورة الحياة مع سلسلة خام، فقارن نوع الحدث بالأحرف الصغيرة بقيمة العضو AgentLifecycleEvent بدلا من ذلك:

from microsoft_agents_a365.notifications import AgentLifecycleEvent, AgentNotification

agent_notification = AgentNotification(app)

@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
    event_type = (notification.activity.value_type or "").lower()
    if event_type == AgentLifecycleEvent.USERDELETED.value:
        await context.send_activity("User identity deleted")

أحداث دورة حياة جديدة

يضيف SDK 2.0 خمسة أحداث ومعالجات دورة حياة إلى Python وJavaScript. حزمة تطوير .NET تتضمنها بالفعل. للاطلاع على القائمة الكاملة، راجع أحداث دورة حياة الوكيل.

امتدادات أدوات التطوير

إذا كنت تستخدم امتدادات أدوات .NET، قم بتحديث كيفية مصادقة وكيلك على خوادم MCP.

.NET: لم تعد المعلمة authToken تصادق خوادم MCP

ينطبق هذا التغيير على إضافات أدوات نواة دلالية وAgent Framework ومنصة Azure للذكاء الاصطناعي.

عندما لا تزود UserAuthorization و authHandlerName، تستخدم الإضافة authToken فقط لاكتشاف خوادم MCP عبر بوابة الأدوات. ثم يقوم بالمصادقة على كل خادم MCP فقط باستخدام رمز من متغير البيئة BEARER_TOKEN_<SERVERNAME> أو BEARER_TOKEN. تتخطى الإضافة أي خادم لا يحتوي على رمز مميز وتسجله، لذا قد لا يُرجع الوكيل الذي يعتمد على authToken وحده أي أدوات MCP دون حدوث خطأ.

يؤثر هذا التغيير أيضا على طرق منصة Azure للذكاء الاصطناعي التالية، والتي تستخدم هذا المسار دائما:

  • AddToolServersToAgent (متزامن)
  • GetMcpToolDefinitionsAndResourcesAsync(agentInstanceId, authToken, turnContext)

للانتقال، استخدم أحد الخيارات التالية:

  • المصادقة الوكيلية (موصى بها): مرّر UserAuthorization وauthHandlerName حتى يكتسب الملحق الرموز المميزة عبر تدفق التفويض بالنيابة (OBO) الوكيلي.

    // Semantic Kernel
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);

// Azure AI Foundry: use the async method instead of AddToolServersToAgent
await toolService.AddToolServersToAgentAsync(agentClient, userAuthorization, authHandlerName, turnContext);

  • متغيرات البيئة: قم بتعيين BEARER_TOKEN_<SERVERNAME> لكل خادم MCP، أو اضبط BEARER_TOKEN لاستخدام رمز واحد لجميع الخوادم. هذا الخيار مناسب للتطوير المحلي والاختبار.

لمزيد من المعلومات، راجع تسجيل الأدوات مع المنسّق الخاص بك.

Runtime

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

Python: نطاق مصادقة قابلية المراقبة مخصص فقط للتطبيقات

get_observability_authentication_scope() الآن يعيد نطاق مورد /.default قابلية الرصد، api://9b975845-388f-4429-889e-eab1ef63949c/.default. في الإصدارات السابقة، كانت تعيد النطاق المفوض Agent365.Observability.OtelWrite.

استخدم هذا النطاق فقط للحصول على رمز مميز خاص بالتطبيق فقط لمثيل عامل التصدير. للتفاصيل، انظر يستخدم تصدير Observability المصادقة بالتطبيق فقط.

تغييرات الرصد في SDK 2.0

تنطبق التغييرات التالية على حزم قابلية الملاحظة الخاصة بـ Agent 365 المهجورة في جميع اللغات الثلاث.

يستخدم تصدير إمكانية المراقبة المصادقة عبر التطبيق فقط

تزيل SDK 2.0 المصادقة المفوضة لتصدير قابلية الملاحظة:

  • المُصدِّر يرسل دائمًا بيانات التليمترية إلى مسار S2S. use_s2s_endpoint يتم تجاهل خيارات (Python)، useS2SEndpoint (JavaScript)، و UseS2SEndpoint (.NET)، حتى عند تعيينها على false.
  • يتطلب المُصدِّر مُحلِّلًا للرموز المميزة يُرجع رمزًا مميزًا خاصًا بالتطبيق فقط لمثيل عامل التصدير. يرفض مسار S2S الرموز المفوضة.
  • تكتسب ذاكرة التخزين المؤقت لرموز الاستضافة الرموز المميزة الخاصة بالتطبيق فقط. طرق التسجيل المفوضة لم تعد تحصل على الرموز.
  • في .NET، EnvironmentUtils.GetObservabilityAuthenticationScope() يعيد النطاق /.default الخاص بالتطبيق فقط بدلا من النطاق Agent365.Observability.OtelWrite المفوض.
Language إزالة استخدم هذا بدلاً من ذلك
Python AgenticTokenCache.register_observability(...)، وهو الآن no-op يسجل خطأ AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver)
JavaScript RefreshObservabilityToken مع TurnContext و Authorization، و runWithExportToken لرموز المُصدِّر RefreshObservabilityToken(agentId, tenantId, tokenResolver) مع withTokenResolver(...) أو exporterOptions.tokenResolver
.NET AgenticTokenCache.RegisterObservability(...) مع AgenticTokenStruct، والذي أصبح الآن متقادمًا ويتسبب في حدوث خطأ في المترجم ObservabilityTokenResolver مع AgenticTokenCache.RefreshObservabilityToken(...)، وTokenResolver أو ContextualTokenResolver في خيارات المُصدِّر

مصادقة عبء العمل لخوادم MCP وMicrosoft Graph وتدفقات OBO لا تتغير.

للاطلاع على متطلبات محلّل الرموز وأمثلة التعليمات البرمجية في كل لغة، انظر Token resolver.

تغييرات صيغة القياس عن بعد في إمكانية المراقبة

تحديث الكود الذي ينشئ بيانات التليمترية وأي استفسارات أو لوحات تحكم تعتمد على تنسيق الرسالة، قواعد التحقق، أو أسماء السمات الموضحة في هذا القسم.

سمات الرسائل هي مصفوفات JSON

تتبع السمات gen_ai.input.messages و gen_ai.output.messages الآن الاتفاقيات الدلالية للذكاء الاصطناعي التوليدي في OpenTelemetry. يتم تسلسلها كمصفوفة JSON عادية، مثل [{"role": ..., "parts": [...]}]، بدلا من الغلاف {"version": "0.1.0", "messages": [...]} .

  • Python: الثابت A365_MESSAGE_SCHEMA_VERSION والحقل version على InputMessages و OutputMessages تمت إزالتهما. OutputMessage.finish_reason تكون قيمته الافتراضية "stop".
  • JavaScript: تمت إزالة التصدير A365_MESSAGE_SCHEMA_VERSION والخاصية version على InputMessages و OutputMessages استخدم DEFAULT_FINISH_REASON بدلا من ذلك. الرسائل التي تنشئها من سلاسل نصية عادية يكون الإعداد الافتراضي فيها من finish_reason إلى "stop".
  • .NET: تتم إزالة الفئة MessageConstants والخاصيتين InputMessages.Version وOutputMessages.Version. OutputMessage.FinishReason غير قابل لأن تكون قيمته null ويكون افتراضيًا "stop".

قم بتحديث أي كود أو استفسارات أو لوحات تحكم تحلل هذه السمات بحيث تتوقع مصفوفة JSON.

يتم التحقق من صحة تفاصيل الاستنتاج

  • Python:InferenceCallDetails يتطلب عددًا غير فارغ من المسافات model أو responseModel. إذا كان كلاهما مفقودًا أو فارغًا، يثير المنشئ ValueError.
  • جافا سكريبت:InferenceDetails.providerName مطلوب. model اختياري، لكن يجب عليك توفير قيمة غير فارغة لـ model أو responseModel. InferenceScope.start() يطرح استثناءً إذا كانت هذه القيم مفقودة. كما أنه يرمي إذا endpoint.port لم يكن عددا صحيحا من 1 إلى 65535.

تغييرات أسماء السمات والعمليات

  • Python: تستخدم أسماء عمليات الاستدلال وبادئات أسماء المدى القيم القياسية في OpenTelemetry بالأحرف الصغيرة، وهي chat وtext_completion وgenerate_content. على سبيل المثال، Chat gpt-4 تصبح chat gpt-4. قم بتحديث الفلاتر، ولوحات المعلومات، والتنبيهات المطابقة لحالة الأحرف.
  • JavaScript:
    • يسجل نطاقات الاستدلال server.port عندما يكون المنفذ هو 443.
    • تُبلّغ نطاقات استجابة امتدادات OpenAI عن النموذج المُقدَّم في gen_ai.response.model بدلًا من gen_ai.request.model.
    • لم يعد امتداد لانغتشين يستخدم النموذج المقدم كبديل ل gen_ai.request.model. يبلغ عن النموذج المُقدَّم للخدمة فقط في gen_ai.response.model.
  • .NET: تمت إعادة تسمية السمة gen_ai.tool.arguments إلى gen_ai.tool.call.arguments.

.NET: تغييرات واجهة IA365EtwLogger

تضيف واجهة IA365EtwLogger طريقة LogApplyGuardrail(...) ومعلمة Exception? error اختيارية إلى كل طريقة Log* موجودة. إذا قمت بتطبيق IA365EtwLogger، فحدّث تطبيقك وأعد الترجمة.

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

  • تاريخ آخر تحديث في