مفاهيم إمكانية الملاحظة في Agent 365

تشرح هذه المقالة نموذج بيانات إمكانية المراقبة في Agent 365، بما في ذلك البيانات التي يُصدرها وكلاء القياس عن بُعد، والجهات التي يمكنها إرسالها، والمكان الذي تصل إليه، والحدود التي تنطبق عليها. استخدم هذه المفاهيم لتخطيط تكاملك وفهم التليمترية عبر توزيعة Microsoft OpenTelemetry، وحزمة تطوير Agent 365، وOTel المباشرة.

ملحوظة

التفاصيل على مستوى الأسلاك - مسارات URL في المصادقة، ورموز خطأ HTTP في الحدود وشروط الإفلات، وحدود الحجم والمعدل لكل طلب - تنطبق على وجه التحديد على مسار OTel المباشر. يتكفّل SDK وDistro بهذه الأمور نيابةً عنك. تنطبق بقية هذه المقالة (المسرد، وتدفق البيانات، ونماذج الهوية، والنطاقات، وشروط الإفلات، حيث تظهر البيانات) على كل مسار.

اختر مسار التكامل الخاص بك

ترسل ثلاثة مسارات نموذج بيانات span نفسه إلى Agent 365. اختر واحدا:

المسار الوصف
توزيع Microsoft OpenTelemetry موصى به للتكاملات الجديدة. حزمة تطوير برمجيات موحّدة لإمكانية الملاحظة عبر Agent 365 وMicrosoft Foundry وAzure Monitor وغيرها.
مجموعة أدوات تطوير Agent 365 (مجموعة أدوات تطوير قابلية الرصد) مجموعة تطوير البرامج السابقة. لا يزال يعمل من دون تغييرات كاسرة للتوافق، لكنه لم يعد الخيار الموصى به لعمليات التكامل الجديدة؛ وإرشادات الترحيل لمستخدمي حِزم SDK الحاليين قادمة.
أوتيل المباشر المسار الخام OTLP/HTTP. استخدمه فقط إذا كان لديك بالفعل مسار OpenTelemetry في مكانه، أو لا يمكن لإطار عمل العامل استخدام Agent 365 SDK، أو أن وكيلك بلغة لا تدعمها SDK بعد (مثل Java).

أيًّا كان المسار الذي تختاره، فإن نموذج البيانات ونماذج الهوية والنطاقات والحدود والواجهات اللاحقة الموضحة أدناه كلها تنطبق.

قاموس قابلية الملاحظة للعامل 365

المصطلح الوصف
معرف التطبيق (appId) يصدر معرف التطبيق عند تسجيل هوية وكيل تطبيق Microsoft Entra أو معرف عامل Microsoft Entra.
- يساوي OAuth client_id، وليس معرّف كائن Microsoft Entra.
- في هذه الوثائق، تعني كل من "معرف الوكيل" و"معرف المخطط" .appId
حوار خيط منطقي من تفاعلات الوكلاء، مثل موضوع دردشة على Teams.
- تم التعرف عليه بواسطة gen_ai.conversation.id.
- مفتاح الانضمام الأساسي لعملية تشغيل.
القناة السطح الذي يعمل عليه الوكيل: msteams، outlook، web، وهكذا.
تشغيل رسالة مستخدم واحدة واردة، وردّ واحد من الوكيل صادر. تُمثَّل على هيئة شجرة من OTel spanات تشترك في traceId.

كيف تعمل إمكانية المراقبة في Agent 365

للحصول على نظرة عامة على Agent 365 وما يجمعه من بيانات عن بعد، راجع نظرة عامة على Microsoft Agent 365.

يمكنك إرسال بيانات القياس عن بُعد كبيانات تتبّع OpenTelemetry:

  • شجرة من الامتدادات تصف تشغيلا واحدا (رسالة مستخدم واحدة في، رد عامل واحد).
  • يصف كل نطاق خطوة واحدة - استدعاء عامل المستوى الأعلى أو استدعاء LLM أو استدعاء أداة أو الرد النهائي.

تدفق بيانات قابلية الرصد للعامل 365

يوضح الرسم التخطيطي التالي كيفية تدفّق بيانات تتبّع العامل عبر المصادقة واستيعاب بيانات قابلية الملاحظة في Agent 365 إلى تجارب Microsoft 365 اللاحقة.

مخطط تدفق بيانات قابلية الرصد للعامل 365.

نماذج الهوية

للحصول على شرح كامل لنماذج هوية الوكيل (تسجيل تطبيق Microsoft Entra القياسي مقابل مخطط هوية الوكيل في معرف عامل Microsoft Entra، بما في ذلك زملاء الذكاء الاصطناعي)، راجع هوية الوكيل. يحدد اختيارك لنموذج الهوية تدفق المصادقة ونقطة النهاية التي تستخدمها.

إذا لم يكن لدى وكيلك تسجيل Microsoft Entra، فلا يمكنه استخدام هذه المسارات مباشرة. حدد الوكيل من خلال سمات التعريف البديلة (انظر مرجع السمة) وتواصل مع فريق الوكيل 365 بخصوص مسار الدخول المناسب.

المصادقة

تتفرع المصادقة بحسب ما إذا كانت خدمتك تُجري المصادقة على نفسها أو بالنيابة عن مستخدم. يحدد الفرع تدفق OAuth، ومطالبة الرمز المميز التي تحمل الإذن، ومسار URL.

  • تُصادق الخدمة على نفسها: لا يوجد مستخدم مسجّل دخوله - ذاتي أو مجدول أو مستند إلى الحدث.

    • تدفق OAuth: بيانات اعتماد عميل خدمة إلى خدمة (S2S ).
    • المطالبة بالرمز المميز: roles.
    • مسار URL: /observabilityService/....

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

    • تدفق OAuth: نيابة عن (OBO).
    • المطالبة بالرمز المميز: scp.
    • مسار URL: /observability/....

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

للحصول على وصفات الرمز المميز الكاملة لكل مجموعة من نماذج الهوية والتدفق، راجع وصفات المصادقة في دليل التكامل.

هوية العامل مرتبطة بعنوان URL

يجب أن يساوي {agentId} في عنوان URL قيمة appId الخاصة بالتطبيق المستدعي (أي مطالبة appid أو azp في الرمز المميز الخاص بك). ترجع حالات عدم التطابق 403 Forbidden. بالنسبة للهويات المشتقة من المخطط، {agentId} هو معرف هوية العامل، وليس معرف تطبيق المخطط.

بالإضافة إلى ذلك، يجب أن يضبط كل مقطع ترسله القيمة gen_ai.agent.id على معرّف التطبيق نفسه؛ إذ يتحقق الخادم من تطابق هوية الوكيل داخل الحمولة مع الوكيل المصادَق عليه، ويرفض أي حالات عدم تطابق. تكشف هذه الخطوة خلط المقاطع من عدة وكلاء في طلب واحد عن طريق الخطأ.

يُعد نطاق (المفوَّض) أو دور التطبيق (التطبيق) الإذن المُسمّى الذي تُضمِّنه Microsoft Entra في رمز الوصول. بالنسبة إلى القياس عن بُعد لـ Agent 365، يكون الإذن هو Agent365.Observability.OtelWrite على مورد Agent 365 Observability (الجمهور 9b975845-388f-4429-889e-eab1ef63949c).

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

  • دور التطبيق لتدفق المستقل (S2S / بيانات اعتماد العميل). الأراضي في المطالبة roles . تم تحديده بواسطة <resource>/.default.
  • النطاق المفوض لتدفق OBO. الأراضي في المطالبة scp . محدد بواسطة <resource>/Agent365.Observability.OtelWrite (أو <resource>/.default).

يتيح Agent 365 أيضًا Agent365.Observability.OtelReadإذنًا للقراءة، يستخدمه المشغلون الذين يستعلمون عن بيانات القياس عن بُعد الخاصة بـ Agent 365. معظم الشركاء لا يحتاجون إليها - تغطي هذه المستندات الاستيعاب فقط.

أضف الإذن إلى تطبيقك

  • بالنسبة إلى تسجيل تطبيق Microsoft Entra القياسي: في مدخل Microsoft Azure، أضف Agent365.Observability.OtelWrite (دور التطبيق لـ S2S، والنطاق للأذونات المفوضة) ضمن أذونات API في تسجيل تطبيق العامل.
  • بالنسبة إلى مخطط: فإن الوكلاء الذين أُنشئت هوياتهم من مخطط هوية الوكيل معرف عامل Microsoft Entra ترث أذونات OAuth المحددة في المخطط، لذلك يزوّد مسؤول المستأجر الأذونات مسبقًا مرة واحدة. يستقبلها كل مثيل عامل تم إنشاؤه من هذا المخطط تلقائيا. راجع تكوين الأذونات القابلة للتوريث لمخططات هوية العامل.

قبل أن تأخذ الرموز الدور أو النطاق، يجب على مسؤول المستأجر في مستأجر العميل منح الموافقة. راجع وصول عوامل Grant إلى موارد Microsoft 365.

بدون موافقة، يفشل اكتساب الرمز مع AADSTS65001 (The user or administrator has not consented to use the application with ID...) أو يصدر الرمز بدون مطالبة roles OR scp وترفض نقطة الإدخال الطلب مع 403.

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

القيود وشروط الإسقاط

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

حدود مستوى الأسلاك:

  • يجب أن تدرج api-version=1 في كل طلب.
  • الحد الأقصى لحجم جسم الطلب هو 1 ميجابايت. ترجع الطلبات الأكبر 413 Payload Too Large.
  • المساران له حدود معدل منفصلة. في 429، التزم بـ Retry-After (المُعيَّن على 1 ثانية) واستخدم التراجع التدريجي مع التفاوت العشوائي.

يمكن للتكاملات الخارجية المدمجة التي تستخدم مصادقة S2S استدعاء نقطة نهاية أهلية المستأجر كإجراء مسبق اختياري قبل إرسال التليمتريات. عند استخدام نقطة النهاية، اعتمد على قرارها بدلا من استنتاج الأهلية بناء على الموافقة أو الترخيص فقط. enabled: false الرد يعني أن المستأجر غير مؤهل حاليا. الجسد الخالي 503 Service Unavailable من الجسد يعني أنه لا يمكن تحديد الأهلية. أعد المحاولة وفقًا لترويسة Retry-After الخاصة به إذا كنت لا تزال بحاجة إلى نتيجة التحقق من الأهلية.

استجابات الخطأ:

  • 403 Forbidden: الرمز المميز يفتقد دور التطبيق أو النطاق المطلوب، أو أن {agentId} في عنوان URL لا يتطابق مع appid أو azp للرمز المميز الخاص بك.
  • 413 Payload Too Large: يتجاوز حجم النص 1 ميجابايت.
  • 429 Too Many Requests: حد المعدل ضرب; احترم Retry-After: 1 وتراجع مع التوتر.

حالات إسقاط البيانات (تم قبول الطلب عبر HTTP ولكن البيانات لا تظهر في الأنظمة اللاحقة):

# الشرط السلوك
1 امتداد gen_ai.operation.name مفقود أو غير موجود في {invoke_agent, execute_tool, chat, output_messages} الانخفاض لكل فترة. ظهر في partialSuccess.rejectedSpans + errorMessage.
2 لا يوجد مستخدم في مستأجر العميل لديه ترخيص Microsoft 365 E7 أو Microsoft Agent 365 معين. يجب أن يكون لدى مستخدم واحد على الأقل في المستأجر الترخيص مُعيَّنًا (فوجود SKU في المستأجر وحده لا يكفي - إذ يؤدي التعيين إلى بدء سير العمل في الواجهة الخلفية لـ Defender). لا يجب أن يكون المستخدم المرخص هو المتصل البشري للعامل. يرجع الطلب 200 OK، لكن إدخال results الخاص بكل span له حالة rejected والسبب tenant_not_licensed.

200 OK ليس دليلًا على تناول. افحص results الاستجابة، واستخدم مسار التحقق للتأكد من وصول البيانات.

مكان ظهور بيانات قابلية الملاحظة الخاصة بالوكيل 365

بمجرد القبول، تظهر امتداداتك في ثلاث تجارب تواجه العملاء. تعتمد الثلاثة على امتداد صالح invoke_agent في جذر التشغيل. يمكن الاستعلام عن عملية تشغيل لا تتضمن سوى chat / execute_tool / output_messages في ميزة الصيد المتقدم في Defender (جدول CloudAppEvents)، لكنها غير ظاهرة في جميع الواجهات الأخرى أدناه.

Experience الوصف
Microsoft Defender يظهر نشاط العامل (invoke_agent، execute_tool، ، chat) في طرق عرض نشاط العامل. يمكن لمسؤولي المستأجر ومحللي الأمان التعمق في عمليات التشغيل الفردية والأدوات واستدعاءات الاستدلال. تعتمد طرق عرض نشاط العامل على الامتداد invoke_agent؛ وفي حال عدم وجوده، فلن يظهر التشغيل هناك، رغم أن الامتدادات الفرعية تظل قابلة للاستعلام عبر البحث المتقدم. طريقة عرض الاستعلام المتقدم - CloudAppEvents - تدعم جميع العمليات: ActionType يعكس العملية (InvokeAgent، InferenceCall، ExecuteToolBySDK، ExecuteToolByGateway، ExecuteToolByMCPServer) والحقول الخاصة بكل span موجودة داخل RawEventData. تعين أسماء الحقول المرئية للعميل مباشرة إلى سمات النطاق التي أرسلتها: ConversationId ← gen_ai.conversation.id← SessionIdentitymicrosoft.session.idAgentId ← gen_ai.agent.idPlatformTargetAgentId ← microsoft.a365.agent.platform.idوما إلى ذلك. راجع مرجع السمة للحصول على التعيين الكامل.
مركز مسؤولي Microsoft 365 كما تظهر أنشطة العامل في طرق عرض مخزون العامل والأمان المستخدمة من قبل مسؤولي المستأجرين لإدارة الوكلاء في المستأجر الخاص بهم. يستوعب مركز الإدارة الصفوف التي تحتوي على invoke_agent فقط: لا يظهر في المخزون الوكلاء الذين لا تحتوي بياناتهم التليمترية على invoke_agent، كما أن عمليات التشغيل التي ترسل chat أو execute_tool أو output_messages فقط لا تظهر هنا. يقرأ مركز الإدارة سمات مثل معرف الوكيل، اسم الوكيل، معرف المخطط، هوية المتصل، معرف المحادثة، القناة، وحالة الخطأ من الفاصل invoke_agent .
Microsoft Purview يظهر نشاط الوكلاء أيضا لمسؤولي الامتثال في Microsoft Purview، حيث يمكنهم تكوين قواعد التعامل مع البيانات والسياسات خلال تشغيل الوكلاء (منع فقدان البيانات، الاحتفاظ بها، الامتثال للاتصالات، وما شابه). السمات التي تفصل سياسات Purview (معرف الوكيل، معرف المخطط، هوية المتصل، المحادثة، القناة، الطلبات، ورسائل الرد) تأتي من الامتداد invoke_agent وذروته.

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

  • Last updated on