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

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

ملحوظة

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

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

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

المسار الوصف
توزيع Microsoft OpenTelemetry موصى به للتكاملات الجديدة. حزمة تطوير برمجيات موحّدة لإمكانية الملاحظة عبر Agent 365 وMicrosoft Foundry وAzure Monitor وغيرها.
SDK قابلية الملاحظة للوكيل 365 المتوقف حزمة SDK القديمة. التكاملات الحالية لا تزال تعمل، لكن لا تستخدمه في التكاملات الجديدة. تتضمن المقالة أدلة الترحيل.
أوتيل المباشر المسار الخام OTLP/HTTP. استخدمه فقط إذا كان لديك خط أنابيب OpenTelemetry بالفعل، أو إذا كان إطار عمل الوكيل لا يستطيع استخدام توزيعة Microsoft OpenTelemetry، أو إذا كان وكيلك بلغة لا تدعمها التوزيعة بعد (مثل 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، بما في ذلك زملاء الذكاء الاصطناعي)، راجع هوية الوكيل. يحدد اختيارك لنموذج الهوية تدفق المصادقة ونقطة النهاية التي تستخدمها.

تصبح هوية الوكيل المشتقة من المخطط التفصيلي مثيلًا مسجّلًا في الوكيل 365 فقط بعد اكتمال تسجيل الوكيل 365، مثل من خلال a365 setup all. إنشاء هوية Microsoft Entra وحده لا يسجل المثيل. تسجيلات التطبيق القياسية في Microsoft Entra، مثل تلك التي يستخدمها وكلاء المحرك المخصص، ليست مثيلات وكيل مسجلة.

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

مصادقة

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

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

    • تدفق OAuth: بيانات اعتماد عميل خدمة إلى خدمة (S2S ).
    • المطالبة بالرمز المميز: roles. الهوية غير المسجلة تحتاج إلى Agent365.Observability.OtelWrite صلاحية التطبيق. يمكن لمثيل وكيل مسجل في Agent 365 استخدام رمز مميز خاص بالتطبيق فقط بدون هذا الدور.
    • مسار URL: /observabilityService/....

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

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

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

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

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

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

بالإضافة إلى ذلك، يجب أن يضبط كل span ترسله 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).

في مسار S2S، يمكن لنسخة وكيل مسجلة في Agent 365 التصدير باستخدام رمز مميز للتطبيق فقط لا يحتوي على دور Agent365.Observability.OtelWrite. لا يحتاج إلى إذن Observability أو موافقة المسؤول لتصدير بيانات القياس عن بُعد. الهوية غير المسجلة لا تزال تحتاج إلى دور التطبيق، والمسار المفوض لا يزال يحتاج إلى النطاق المفوض بالإضافة إلى موافقة المسؤول.

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

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

  • لتسجيل تطبيق Microsoft Entra القياسي: في بوابة Azure، أضف Agent365.Observability.OtelWrite ضمن أذونات API في تسجيل تطبيق الوكيل. استخدم دور التطبيق ل S2S ونطاق العمل المفوض ل OBO.
  • بالنسبة لمثيل وكيل مشتق من blueprint على مسار S2S: أكمل تسجيل Agent 365 لمثيل الوكيل. المثيل المسجل لا يحتاج إلى إذن واجهة برمجة تطبيقات Observability أو موافقة المسؤول لتصدير بيانات التليمترية عبر مسار S2S.
  • بالنسبة إلى مثيل وكيل مشتق من المخطط على المسار المفوض: أضف النطاق المفوض Agent365.Observability.OtelWrite إلى المخطط بحيث ترثه مثيلات الوكلاء. راجع تكوين الأذونات القابلة للتوريث لمخططات هوية العامل. لإضافتها باستخدام Agent 365 CLI، انظر أذونات قابلية المراقبة.

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

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

مثيل وكيل مسجل في Agent 365 يصدر عبر مسار S2S لا يحتاج إلى موافقة مسؤول المراقبة. لا تزال الموافقة مطلوبة للهويات غير المسجلة في S2S التي تستخدم دور التطبيق ولجميع عمليات التصدير عبر المسار المفوض التي تستخدم النطاق المفوض.

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

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

معرفة هذه الحدود مسبقا تمنع المفاجآت أثناء التكامل. تُرجع بعض حالات الفشل رمز حالة 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

بعد قبول الـ spans، تظهر في ثلاث تجارب موجهة للعملاء. تعتمد التجارب الثلاث على عنصر span صالح invoke_agent في جذر التشغيل. يمكن الاستعلام عن مقطع يحتوي فقط على chat أو execute_tool أو output_messages من خلال Defender Advanced Hunting (الجدول CloudAppEvents)، لكنه غير مرئي في أي واجهة أخرى.

الخبرة الوصف
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