مفاهيم إمكانية الملاحظة في 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 مخطط هوية العامل، بما في ذلك زملاء فريق الذكاء الاصطناعي)، راجع بدء تطوير العامل 365. يحدد اختيارك لنموذج الهوية تدفق المصادقة ونقطة النهاية التي تستخدمها.

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

Authentication

تتفرع المصادقة بحسب ما إذا كانت خدمتك تُجري المصادقة على نفسها أو بالنيابة عن مستخدم. يحدد الفرع تدفق 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 (الجمهور 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 ولكن البيانات لا تظهر في الأنظمة اللاحقة):

# الشرط Behavior
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