دمج إمكانية مراقبة العامل باستخدام OTel المباشر

يأخذك هذا الدليل خطوة بخطوة خلال عملية إرسال بيانات القياس عن بُعد للوكيل إلى Agent 365 مباشرة عبر OpenTelemetry ‏(OTLP/HTTP+JSON). قبل البدء، اقرأ مفاهيم قابلية مراقبة العامل 365 لفهم النموذج، وتدفقات المصادقة، والسطوح التي تهبط فيها بياناتك.

مهم

مسار OTel المباشر هو الاستثناء، وليس الافتراضي. استخدمه فقط إذا كان لديك بالفعل مسار OpenTelemetry، أو لا يمكن لإطار العمل الخاص بك استخدام Agent 365 SDK، أو أن وكيلك بلغة لا تدعمها SDK بعد (مثل Java). بالنسبة لأي شخص آخر، المسار الموصى به هو Microsoft OpenTelemetry Distro، والذي يوفر SDK موحدا للمراقبة عبر Agent 365، Microsoft Foundry، Azure Monitor، والمزيد. تستمر حزمة SDK الخاصة بالمراقبة السابقة في العمل من دون تغييرات غير متوافقة، ولكن لم يعد يُوصى بها لعمليات التكامل الجديدة؛ وإرشادات الترحيل لمستخدمي SDK الحاليين قادمة.

Prerequisites

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

من What
مسؤول المستأجر اشترك في Agent 365 وامنح الموافقة لتطبيق الوكيل الخاص بك. راجع البدء باستخدام Agent 365. بدون مستأجر مرخّص، يتم تجاهل الاستيعاب بصمت - يُرجع الطلب 200 OK مع partialSuccess: null ولكن البيانات لا تظهر أبدًا في المراحل اللاحقة.
مسؤول المستأجر تعيين ترخيص Microsoft 365 E7 أو Microsoft Agent 365 إلى مستخدم واحد على الأقل ضمن المستأجر. وجود وحدة SKU بحد ذاته لا يكفي. يؤدي تعيينه إلى مستخدم إلى بدء سير عمل Defender في الواجهة الخلفية الذي يُمكّن من استيعاب البيانات. بدون ترخيص معيّن، تُرجِع الطلبات 200 OK مع partialSuccess: null، وتُهمَل البيانات بصمت.
مسؤول المستأجر منح موافقة المستأجر. راجع وصول عوامل Grant إلى موارد Microsoft 365. بدونه، يتم إصدار الرموز المميزة دون الدور/النطاق، وترجع الطلبات 403.
فريق التطوير الخاص بك سجل تطبيقك (تطبيق أو مخطط Microsoft Entra القياسي). راجع بدء استخدام تطوير Agent 365.
فريق التطوير الخاص بك أضف Agent365.Observability.OtelWrite ضمن أذونات واجهة برمجة التطبيقات (دور التطبيق ل S2S، نطاق المفوض). للحصول على المخططات، راجع تكوين الأذونات القابلة للتوريث. قم بالتنسيق مع فريق إعداد Agent 365 لتفعيل الإذن.

وصفات المصادقة

تستخدم الأساليب الأربعة نقطة نهاية الرمز المميز القياسية لـ Microsoft Entra:

الحقل قيمة
نقطة نهاية الرمز المميز https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
المورد (aud في الرمز المُعاد) 9b975845-388f-4429-889e-eab1ef63949c (يقبل api://9b975845-388f-4429-889e-eab1ef63949cأيضا )
نطاق S2S 9b975845-388f-4429-889e-eab1ef63949c/.default
نطاق OBO 9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite

تظهر الوصفات أدناه HTTP الخام للوضوح. في الإنتاج، تفضل Microsoft. Identity.Web أو مكتبة MSAL أخرى، والتي تعالج تحديث الرمز المميز والتخزين المؤقت.

ما هي الوصفة التي أحتاجها؟

نموذج التطبيق الخاص بي تدفق OAuth الخاص بي الانتقال إلى
تسجيل تطبيق Microsoft Entra القياسي S2S (بيانات اعتماد العميل) S2S، تطبيق Microsoft Entra القياسي
تسجيل تطبيق Microsoft Entra القياسي OBO (مفوض) OBO، تطبيق Microsoft Entra القياسي
هوية العامل المشتق من المخطط S2S (بيانات اعتماد العميل) S2S، هوية العامل المشتق من المخطط
هوية العامل المشتق من المخطط OBO / زميل فريق الذكاء الاصطناعي OBO، هوية الوكيل المشتقة من Blueprint

تطبيق Microsoft Entra القياسي من نوع S2S

POST واحد إلى نقطة نهاية الرمز المميز للمستأجر باستخدام grant_type=client_credentials. قم بمصادقة التطبيق باستخدام السر الخاص بالعميل، أو شهادة (تأكيد JWT موقّع)، أو هوية مُدارة، أو بيانات اعتماد فيدرالية.

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_secret={secret}
&grant_type=client_credentials

يحتوي الرمز المميز المُعاد على appid/azp = {your-app-id}، وroles الذي يحتوي على Agent365.Observability.OtelWrite، وaud = 9b975845-.... استخدمه على المسار /observabilityService/.../traces.

للمصادقة المستندة إلى الشهادة، استبدل client_secret={secret} ب client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed-jwt}.

S2S، هوية العامل المشتق من المخطط

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

  1. يقوم المخطط بالمصادقة ويحصل على رمز تبادل للهوية الموحدة T1:

    • {blueprint-credential} هو رمز MSI الخاص بالمخطط، أو JWT موقّع بشهادة، أو تأكيد رمز تبادل سري، وفقًا لتكوين المخطط.
    POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={blueprint-app-id}
&scope=api%3A%2F%2FAzureADTokenExchange%2F.default
&fmi_path={agent-identity-app-id}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={blueprint-credential}
&grant_type=client_credentials

  2. تستبدل هوية العامل T1 بالرمز المميز لمورد مراقبة Agent 365:

    POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={agent-identity-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2F.default
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={T1}
&grant_type=client_credentials
    • الرمز المميز المُعاد يحتوي على appid/azp = {agent-identity-app-id}، وroles الذي يحتوي على Agent365.Observability.OtelWrite، وaud = 9b975845-....
    • استخدم هذا الرمز على المسار /observabilityService/.../traces.
    • عنوان URL {agentId} هو معرف العامل appId، وليس معرف تطبيق المخطط.

OBO، تطبيق Microsoft Entra القياسي

استلم الرمز المميز Tc الوارد للمستخدم من المتصل المصدر (Bearer أو PFAT)، ثم تبادله:

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={your-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_secret={secret}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

بالنسبة لمصادقة الشهادة، استبدل client_secret={secret} بنفس client_assertion_type + client_assertion الزوج كما هو الحال في S2S.

يحتوي الرمز المميز الذي تم إرجاعه على appid/azp = {your-app-id}، وscp الذي يحتوي على Agent365.Observability.OtelWrite، وaud = 9b975845-.... استخدمه على مسار /observability/.../traces. يتم إرجاع رمز التحديث المميز جنبا إلى جنب؛ قم بتخزينه مؤقتا وإعادة استخدامه بدلا من إعادة تشغيل التبادل في كل مكالمة.

OBO، هوية العامل المشتق من المخطط (بما في ذلك زميل الذكاء الاصطناعي)

هناك ثلاث خطوات رئيسية في تدفق نيابة عن. لمزيد من المعلومات، راجع تدفقات OAuth للعاملين: تدفق نيابة عن.

  1. تلقي رمز المستخدم المميز Tc. بالنسبة لزميل فريق الذكاء الاصطناعي، يمثل هذا الرمز المميز حساب المستخدم الخاص بالعامل؛ وإلا، فإنه يمثل المتصل البشري.

  2. يصادق المخطط ويحصل على T1، مثل تدفق هوية العامل المشتق من مخطط S2S.

  3. تتبادل هوية الوكيل T1 و Tc مقابل رمز مميز لمورد مفوَّض:

    POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={agent-identity-app-id}
&scope=9b975845-388f-4429-889e-eab1ef63949c%2FAgent365.Observability.OtelWrite
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={T1}
&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={Tc}
&requested_token_use=on_behalf_of

الرمز المميز الذي تم إرجاعه يحتوي على appid/azp = {agent-identity-app-id}، وscp يحتوي على Agent365.Observability.OtelWrite، ويمثل مستخدم الوكيل. استخدمه على المسار /observability/.../traces. عنوان URL {agentId} هو معرف العامل appId، وليس معرف تطبيق المخطط. يتم إرجاع رمز تحديث معه؛ خزّنه مؤقتًا وأعِد استخدامه.

المطالبات المطلوبة في الرمز المميز المُعاد

مسار S2S (/observabilityService/...) - رمز مميز للتطبيق فقط:

المطلب القيمة المطلوبة
aud 9b975845-388f-4429-889e-eab1ef63949c (أو api://9b975845-...)
roles يجب أن يحتوي على Agent365.Observability.OtelWrite
appid (v1) أو azp (v2) يجب أن يساوي URL {agentId}
scp يجب أن يكون غائبا

المسار المفوض (/observability/...) - الرمز المميز المفوض من قبل المستخدم (Bearer أو PFAT):

المطلب القيمة المطلوبة
aud 9b975845-388f-4429-889e-eab1ef63949c (أو api://9b975845-...)
scp يجب أن يحتوي على Agent365.Observability.OtelWrite
appid / azp يجب أن يساوي URL {agentId}

يقبل المسار المُفوَّض كِلا الرمزين المميزين Bearer وMSAuth1.0 PFAT. يجب أن يستخدم Bearerالمتصلون المباشرون . إذا كنت لا تعرف أي واحد لديك، فاستخدم Bearer.

نقاط النهاية

مساران؛ اختر حسب كيفية مصادقة الخدمة ، وليس حسب ما يفعله المستخدم:

POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1   # S2S
POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1          # OBO

عناوين

Authorization: Bearer <token>      # or MSAuth1.0 ... for delegated PFAT
Content-Type: application/json

معلمات URL

  • {tenantId} - معرف GUID لمستأجر العميل. يتعامل الخادم مع هذا على أنه موثوق؛ وإذا كانت النطاقات الخاصة بك تعيّن microsoft.tenant.id وكان ذلك يتعارض معه، فسيتم رفض الطلب.
  • {agentId} - appId الخاص بتطبيق الاستدعاء (أيضا OAuth client_id). بالنسبة للهويات المشتقة من المخطط، هذا هو معرف هوية العامل ، وليس معرف تطبيق المخطط. يجب أن يساوي مطالبة appid / azp الخاصة بالرمز المميز الخاص بك.
  • api-version=1 -مطلوب.

طلب ترميز النص الأساسي

النص الأساسي هو شكل OTLP/HTTP+JSON القياسي: ExportTraceServiceRequest مع resourceSpans → scopeSpans → spans. ضع في اعتبارك التفاصيل التالية:

  • traceId يتم إرسال (16 بايت) و spanId (8 بايت) كسلاسل سداسية صغيرة.
  • startTimeUnixNano / endTimeUnixNano هي سلاسل نصية تحتوي على نانوثواني حقبة يونكس.
  • kind هي قيمة التعداد الصحيحة في OTLP (على سبيل المثال 1 لـ INTERNAL)؛ status.code هي قيمة التعداد الصحيحة (على سبيل المثال 1 لـ OK، و2 لـ ERROR).
  • يتم إرسال كافة قيم السمات ك stringValue.

شكل الاستجابة

ترجع المكالمة الناجحة 200 OK:

{ "partialSuccess": null }

إذا تم رفض بعض النطاقات بواسطة عامل التصفية لكل نطاق:

{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "Dropped 2 non-A365 span(s) ..."
  }
}

تكون أسماء الحقول بصيغة camelCase في البيانات المنقولة. تحقق دائمًاpartialSuccess: من أن الحصول على 200 مع رفض جميع النطاقات الخاصة بك نتيجة حقيقية يجب أن تظهرها. يسرد الحدود وحالات الإسقاط حالات الإسقاط الصامت التي تُرجِع 200 مع partialSuccess: null على الرغم من عدم ظهور أي بيانات في المراحل اللاحقة.

أصغر طلب ممكن

يرسل أبسط اختبار شامل نطاق invoke_agent واحدًا. هذا النطاق هو أصغر نص أساسي موجود في Microsoft Defender.

الخطوة 1. احصل على رمز Bearer. بالنسبة إلى S2S، استخدم بيانات اعتماد العميل مع النطاق 9b975845-388f-4429-889e-eab1ef63949c/.default (راجع وصفات المصادقة للوصفة الكاملة).

الخطوة 2. نشر نطاق واحد:

TOKEN="$(./get-token.sh)"
TENANT_ID="<customer-tenant-guid>"
AGENT_ID="<your-agent-app-id>"

curl -i -X POST \
  "https://agent365.svc.cloud.microsoft/observabilityService/tenants/${TENANT_ID}/otlp/agents/${AGENT_ID}/traces?api-version=1" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  --data @- <<EOF
{
  "resourceSpans": [{
    "scopeSpans": [{
      "scope": { "name": "my-instrumentation", "version": "1.0.0" },
      "spans": [{
        "traceId": "0102030405060708090a0b0c0d0e0f10",
        "spanId":  "1111111111111111",
        "parentSpanId": "",
        "name": "invoke_agent",
        "kind": 1,
        "startTimeUnixNano": "1736175600000000000",
        "endTimeUnixNano":   "1736175601500000000",
        "status": { "code": 1 },
        "attributes": [
          { "key": "gen_ai.operation.name", "value": { "stringValue": "invoke_agent" } },
          { "key": "gen_ai.agent.id",       "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.agent.name",     "value": { "stringValue": "MyAgent" } },
          { "key": "microsoft.a365.agent.blueprint.id", "value": { "stringValue": "${AGENT_ID}" } },
          { "key": "gen_ai.conversation.id","value": { "stringValue": "conv-001" } },
          { "key": "microsoft.channel.name","value": { "stringValue": "web" } },
          { "key": "user.id",               "value": { "stringValue": "<entra-user-objectid>" } },
          { "key": "client.address",        "value": { "stringValue": "10.1.2.80" } },
          { "key": "server.address",        "value": { "stringValue": "myagent.example.com" } },
          { "key": "server.port",           "value": { "stringValue": "443" } },
          { "key": "gen_ai.input.messages", "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"hi\"}]" } },
          { "key": "gen_ai.output.messages","value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"hello\"}]" } }
        ]
      }]
    }]
  }]
}
EOF

الخطوة 3. توقّع 200 OK مع هذا المحتوى:

{ "partialSuccess": null }

الخطوة 4. تأكد من وصول البيانات بالفعل. لا يُعد A 200 OK إثباتًا على الاستيعاب؛ التحقق من الاستيعاب يستعرض سير عملية التحقق. لنشر ملف نص محفوظ بدلا من ذلك، استبدل --data @- <<EOF ... EOF ب --data @./otlp-request.json.

مثال تشغيل العامل

يسأل مستخدم على Microsoft Teams "ما هو الطقس في سياتل؟". يستدعي وكيلك دالة GetWeather ، ويطلب من LLM تنسيق الإجابة والردود. يتكوّن هذا التشغيل الواحد من أربعة نطاقات:

graph TD
    A["<b>invoke_agent</b> · spanId=A · parentSpanId=∅<br/><i>root - the run itself</i>"]
    B["<b>chat</b> · spanId=B · parentSpanId=A<br/><i>LLM picks the tool / formats reply</i>"]
    C["<b>execute_tool</b> · spanId=C · parentSpanId=A<br/><i>the GetWeather call</i>"]
    D["<b>output_messages</b> · spanId=D · parentSpanId=A<br/><i>final reply emitted to the user</i>"]
    A --> B
    A --> C
    A --> D

تعيين سمات على مستوى المقطع في كل مقطع:

السمة قيمه المثال
traceId 0102030405060708090a0b0c0d0e0f10
gen_ai.conversation.id 19:abc@thread.tacv2
microsoft.session.id session-1234
microsoft.channel.name msteams
gen_ai.agent.id <AGENT_APP_ID>
gen_ai.agent.name WeatherBot
microsoft.a365.agent.blueprint.id <BLUEPRINT_APP_ID>
user.id <entra-user-objectid>
client.address 10.1.2.80
server.address weatherbot.example.com
server.port 443

مهم

لا يتم نشر هذه السمات على مستوى التشغيل تلقائيا. يجب عليك تعيين gen_ai.conversation.idو microsoft.channel.nameو microsoft.session.id على كل امتداد بنفسك.

Span A: invoke_agent (الجذر)

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "1111111111111111",
  "parentSpanId": "",
  "name": "invoke_agent",
  "kind": 1,
  "startTimeUnixNano": "1736175600000000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",   "value": { "stringValue": "invoke_agent" } },
    { "key": "gen_ai.execution.type",   "value": { "stringValue": "HumanToAgent" } },
    { "key": "gen_ai.input.messages",   "value": { "stringValue": "[{\"role\":\"user\",\"content\":\"What's the weather in Seattle?\"}]" } },
    { "key": "gen_ai.output.messages",  "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } },
    { "key": "user.email",              "value": { "stringValue": "alice@contoso.com" } }
    /* plus all the run-wide attributes listed above */
  ]
}

النطاق ب: chat (استدعاء نموذج اللغات الكبير (LLM))

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "2222222222222222",
  "parentSpanId": "1111111111111111",
  "name": "chat",
  "kind": 1,
  "startTimeUnixNano": "1736175600200000000",
  "endTimeUnixNano":   "1736175600900000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "chat" } },
    { "key": "gen_ai.request.model",       "value": { "stringValue": "gpt-4o" } },
    { "key": "gen_ai.provider.name",       "value": { "stringValue": "openai" } },
    { "key": "gen_ai.usage.input_tokens",  "value": { "stringValue": "42" } },
    { "key": "gen_ai.usage.output_tokens", "value": { "stringValue": "23" } }
    /* plus all the run-wide attributes */
  ]
}

النطاق C: execute_tool

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "3333333333333333",
  "parentSpanId": "1111111111111111",
  "name": "execute_tool",
  "kind": 1,
  "startTimeUnixNano": "1736175600950000000",
  "endTimeUnixNano":   "1736175601200000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",      "value": { "stringValue": "execute_tool" } },
    { "key": "gen_ai.tool.name",           "value": { "stringValue": "GetWeather" } },
    { "key": "gen_ai.tool.type",           "value": { "stringValue": "function" } },
    { "key": "gen_ai.tool.call.id",        "value": { "stringValue": "call-001" } },
    { "key": "gen_ai.tool.call.arguments", "value": { "stringValue": "{\"location\":\"Seattle\"}" } },
    { "key": "gen_ai.tool.call.result",    "value": { "stringValue": "{\"tempF\":65,\"condition\":\"partly cloudy\"}" } }
    /* plus all the run-wide attributes */
  ]
}

Span D: output_messages

{
  "traceId": "0102030405060708090a0b0c0d0e0f10",
  "spanId": "4444444444444444",
  "parentSpanId": "1111111111111111",
  "name": "output_messages",
  "kind": 1,
  "startTimeUnixNano": "1736175601400000000",
  "endTimeUnixNano":   "1736175601500000000",
  "status": { "code": 1 },
  "attributes": [
    { "key": "gen_ai.operation.name",  "value": { "stringValue": "output_messages" } },
    { "key": "gen_ai.output.messages", "value": { "stringValue": "[{\"role\":\"assistant\",\"content\":\"It's 65F and partly cloudy in Seattle.\"}]" } }
    /* plus all the run-wide attributes */
  ]
}

إرسال بيانات القياس عن بُعد

استخدام OTel SDK

يرسل معظم الشركاء تتبعات من خلال OTel SDK بدلا من HTTP المدلفة يدويا. يعالج SDK الإرسال في دفعات وإعادة المحاولة وترميز OTLP/HTTP+JSON نيابة عنك. عيّن نقطة نهاية المُصدِّر وأدرج الترويسة Authorization.

نقطة نهاية المُصدِّر هي عنوان URL للمسار نفسه، بما في ذلك سلسلة الاستعلام:

https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1

(استخدم /observability/... بدلا من /observabilityService/... للمسار المفوض.)

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
    headers={"Authorization": f"Bearer {token}"},
)

الحزمة: opentelemetry-exporter-otlp-proto-http.

Node.js / TypeScript

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const exporter = new OTLPTraceExporter({
  url: "https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1",
  headers: { Authorization: `Bearer ${token}` },
});

الحزمة: @opentelemetry/exporter-trace-otlp-http.

.NET

using OpenTelemetry.Exporter;

services.AddOpenTelemetry().WithTracing(b => b
    .AddOtlpExporter(o =>
    {
        o.Endpoint = new Uri("https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1");
        o.Headers = $"Authorization=Bearer {token}";
        o.Protocol = OtlpExportProtocol.HttpJson;
    }));

الحزمة: OpenTelemetry.Exporter.OpenTelemetryProtocol.

HTTP اليدوي

إذا كنت لا تستطيع أو لا تريد استخدام OTel SDK، فنشئ طلب OTLP/HTTP+JSON بنفسك وانشره. يتم تعريف شكل النص بواسطة مواصفات OpenTelemetry OTLP/HTTP+JSON:

{
  "resourceSpans": [{
    "resource":  { "attributes": [ ... ] },          // optional
    "scopeSpans": [{
      "scope":  { "name": "<your-instrumentation>", "version": "1.0.0" },
      "spans":  [ <span>, <span>, ... ]
    }]
  }]
}

كل <span> كائن حقوله المطلوبة هي traceIdو spanIdnameو kindstartTimeUnixNanoendTimeUnixNanoattributes(للامتدادات غير الجذرية). parentSpanId راجع نقاط النهايةوترميز نص الطلب لقواعد الترميز (أوقات ترميز السلسلة، سداسي عشريtraceId / spanId، عدد صحيحkind / status.code، جميع قيم السمات ك ).stringValue

يتم تعريف مجموعة السمات التي يجب تعيينها على كل امتداد في تعاقدات الرسائل. راجع مرجع السمة لقائمة السمات الكاملة. راجع مثال تشغيل العامل للحصول على نموذج عمل متكامل مع رمز Bearer في العامل والنص الأساسي المضمن.

يمكنك إرسال جميع نطاقات التشغيل في نص طلب نشر واحد (مفضل - طلب واحد، تتبع واحد) أو عبر طلبات نشر متعددة. يقوم الخادم بإعادة إنشاء التشغيل من traceId + parentSpanId + gen_ai.conversation.id، لذا يحمل كل نطاق ما يكفي ليتم ربطه بأي طريقة من الطريقتين.

عقود الرسائل

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

أنواع العمليات

ويجب أن يحتوي كل نطاق ترسله على gen_ai.operation.name معيَّنًا إلى إحدى هذه القيم الأربع (غير حساس لحالة الأحرف). يُسقَط أي نطاق ذي قيمة مفقودة أو غير معروفة بصمت ويُحتسَب ضمن partialSuccess.rejectedSpans.

gen_ai.operation.name المعنى أكثر الأخطاء شيوعًا على google
invoke_agent استدعاء عامل. "جذر" تشغيل العامل. مطلوب لكي يظهر التشغيل في طرق عرض نشاط عامل Microsoft Defender أو مركز مسؤولي Microsoft 365. فبدون ذلك، لا تصل بيانات القياس عن بُعد إلا إلى ميزة البحث المتقدم في Microsoft Defender (CloudAppEvents).
execute_tool استدعاء أداة/وظيفة يتم تنفيذه بواسطة عامل. --
chat استدعاء استدلال نموذج اللغات الكبير (LLM). استخدم القيمة الحرفية chat، وليس inference.
output_messages رسالة الإخراج النهائية الصادرة. --

التدرج الهرمي للنطاقات وتجميع عمليات التشغيل

يعيد Agent 365 إنشاء عملية تشغيل من الرسم البياني القياسي لنطاقات OTLP (traceId، وspanId، وparentSpanId) بالإضافة إلى السمات على مستوى التشغيل من مرجع السمات.

ست قواعد:

  1. عيّن parentSpanId دائمًا على كل نطاق غير جذري. بدون ذلك، لا يمكن إعادة إنشاء بنية الشجرة الخاصة بعملية التشغيل.
  2. أعِد استخدام نفس traceId عبر كل نطاق ضمن عملية تشغيل واحدة.
  3. اضبط gen_ai.conversation.id على كل امتداد بنفس القيمة. هذا هو مفتاح الربط الأساسي لـ"جميع النطاقات في عملية التشغيل هذه". لا يتم نشره تلقائيا.
  4. اضبط microsoft.channel.name على كل امتداد بنفس القيمة. يمكن لنطاقات الأدوات التي تفتقر إلى القناة / المحادثة أن ترثها من الأصل invoke_agentفقط إذا كان الأصل موجودًا في نفس طلب OTLP، لذا قم بتعيينها على كل نطاق بنفسك.
  5. اضبط microsoft.session.id على كل امتداد عندما يكون لديك جلسة عمل منطقية.
  6. بالنسبة إلى استدعاءات من وكيل إلى وكيل حيث يكون الوكيل الفرعي في طلب منفصل، أعِد استخدام العنصر نفسه gen_ai.conversation.id واستخدم سمات microsoft.a365.caller.agent.* (راجع مرجع السمات) لالتقاط سياق الوكيل المستدعي.

والشجرة ذات الأربعة نطاقات في مثال تشغيل العامل هي الشكل المتعارف عليه.

أشكال التشغيل الشائعة

شكل النطاقات المُراد إصدارها الملاحظات
روبوت الدردشة أحادي العامل (لا توجد أدوات، ولا نطاق LLM) واحد invoke_agent فقط قم بتعيين السمات على مستوى التشغيل بالإضافة إلى gen_ai.input.messages وgen_ai.output.messages. مطابقة لأصغر طلب ممكن.
عامل مع أدوات (الأكثر شيوعا) invoke_agentالجذر + chat، execute_tool، output_messages التوابع تشترك جميع التوابع في الجذر traceId وتقوم بتعيين parentSpanId = root.spanId. تحمل جميعها نفس السمات على مستوى التشغيل. راجع مثال تشغيل العامل للحصول على مثال كامل.
عامل إلى وكيل يصدر كل عامل invoke_agent الخاص به أعد استخدام gen_ai.conversation.id نفسه عبر كلا العاملين. على الهدف invoke_agent، قم بتعيين gen_ai.execution.type = "Agent2Agent"microsoft.a365.caller.agent.* والسمات (استدعاء العامل appIdوالاسم والمخطط appIdومعرف المستخدم والبريد الإلكتروني). إذا لم يكن لدى عامل الاستدعاء تسجيل Entra، فاستخدم microsoft.a365.caller.agent.platform.id وبدلا gen_ai.caller.agent.type من ذلك.

قائمة مراجعة الإلحاق

راجع قائمة التحقق هذه قبل الانتقال إلى بيئة الإنتاج.

الفئة تحقق
المصادقه تم تسجيل تطبيق Entra (أو المخطط) الخاص بك، ويمكنك إصدار الرموز المميزة له.
المصادقه تم منح تطبيقك Agent365.Observability.OtelWrite (دور التطبيق لـ S2S، ونطاق للتفويض).
المصادقه كل عامل لديه معرف تطبيق Entra الخاص به كما هو الحال {agentId} في عنوان URL. بالنسبة للهويات المشتقة من المخطط، فإن معرف التطبيق هذا هو معرف هوية العامل، وليس معرف تطبيق المخطط. إذا لم يكن لدى العامل تسجيل Entra، فشاهد انتقاء القيم.
المصادقه منح مسؤول مستأجر الموافقة على Agent365.Observability.OtelWrite. بدون موافقة، يتم إصدار الرموز المميزة دون الدور/النطاق ويتم رفض الطلبات مع 403.
الترخيص تم تعيين ترخيص Microsoft 365 E7 أو Microsoft Agent 365 لمستخدم واحد على الأقل في مستأجر العميل (أي التعيين الفعلي، وليس مجرد وجود SKU في المستأجر فقط). دون ترخيص معين، يتم إسقاط الاستيعاب بصمت. انظر المتطلبات المسبقة.
النطاقات يحدّد كل امتداد العناصر الأساسية على مستوى التشغيل بأكمله (التسلسل الهرمي للامتدادات وتجميعات التشغيل).
النطاقات تقوم نطاقات invoke_agent بتعيين gen_ai.input.messages وgen_ai.output.messages.
النطاقات execute_toolامتدادات مجموعة gen_ai.tool.name، gen_ai.tool.type، gen_ai.tool.call.id، gen_ai.tool.call.arguments، . gen_ai.tool.call.result
النطاقات تقوم نطاقات chat بتعيين gen_ai.request.model وgen_ai.provider.name (بشكل مثالي gen_ai.usage.input_tokens / gen_ai.usage.output_tokens - ترميز السلسلة).
النطاقات تقوم كل النطاقات غير الجذرية بتعيين parentSpanId؛ تشترك كل النطاقات ضمن عملية تشغيل في traceId نفسه.
الحمولة نص الطلب ≤ 1 ميغابايت.
التحقق تقوم بتحليل partialSuccess في كل استجابة وتُسجّل حالات الرفض.
التحقق أنت قمت بتشغيل تدفق التحقق في التحقق من الاستيعاب مقابل عمليات التشغيل الأولى.

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

  • Last updated on