دمج إمكانية مراقبة العامل باستخدام 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 الحاليين قادمة.

المتطلبات المسبقه

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

من 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 القياسي). انظر هوية الوكيل.
فريق التطوير الخاص بك أضف 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 Observability:

    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.

Endpoints

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

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} - المعرف الفريد العمومي لمستأجر العميل. يتعامل الخادم مع هذا على أنه المرجع المعتمد؛ وإذا كانت النطاقات الخاصة بك تعيّن 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 . هذا الـspan هو أصغر عنصر يصل إلى 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 */
  ]
}

Span B: 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 */
  ]
}

المسافة 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 المميز في الترويسة والمحتوى مضمّنًا.

يمكنك إرسال جميع نطاقات التتبّع الخاصة بعملية تشغيل واحدة ضمن جسم طلب POST واحد (وهو الخيار المفضّل: طلب واحد، أثر تتبّع واحد) أو عبر عدة طلبات POST. يقوم الخادم بإعادة إنشاء التشغيل من 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 عبر كل span ضمن تشغيل نصي واحد.
  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