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

توضح هذه المقالة نموذج البيانات الذي تستند إليه قابلية الرصد في Agent 365، وما بيانات القياس عن بُعد التي ترسلها الوكلاء، ومن يمكنه إرسالها، وأين تُخزَّن، والحدود التي تنطبق عليها. تنطبق هذه المفاهيم على مسار التكامل every: Microsoft OpenTelemetry Distro، Agent 365 SDK، direct OTel.

ملحوظة

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

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

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

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

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

المعجم

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

طريقة العمل

للاطلاع على نظرة عامة حول Microsoft Agent 365 ومصادر بيانات القياس عن بُعد التي تُغذّيه، راجع نظرة عامة على Microsoft Agent 365.

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

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

تدفق البيانات

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

نماذج الهوية

للحصول على شرح كامل لنماذج هوية الوكيل (تسجيل تطبيق 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 ("لم يوافق المستخدم أو المسؤول") أو يتم إصدار الرمز المميز دون المطالبةroles / scpوترفض نقطة نهاية الاستيعاب الطلب مع .403

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

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

إن معرفة هذه الحدود مقدما تمنع حدوث مفاجآت أثناء التكامل - معظمها صامت (تقبل واجهة برمجة التطبيقات الطلب ولكن البيانات لا تظهر أبدا في المراحل النهائية).

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

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

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

  • 403 Forbidden--الرمز المميز يفتقد دور / نطاق التطبيق المطلوب، أو {agentId} في عنوان URL لا يتطابق مع appid / azp الرمز المميز الخاص بك.
  • 413 Payload Too Large--body يتجاوز حجمه 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 { "partialSuccess": null }.

200 موافق ليس دليلا على الاستيعاب. استخدم تدفق التحقق لتأكيد أراضي البيانات.

مكان ظهور بياناتك

بمجرد القبول، تظهر امتداداتك في ثلاث تجارب تواجه العملاء. تعتمد الثلاثة على امتداد صالح invoke_agent في جذر التشغيل. يمكن الاستعلام عن عملية تشغيل لا تتضمن سوى chat / execute_tool / output_messages في ميزة الصيد المتقدم في Defender (جدول 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