إعداد مصادقة إمكانية الملاحظة

يتطلب مُصدِّر الوكيل 365 مُحلِّلَ رمزٍ مميزٍ للمصادقة عند تصدير بيانات القياس عن بُعد. يغطي هذا الدليل إعداد العوامل التي تم إنشاؤها باستخدام Microsoft 365 Agents SDK، والتي تغطي كل من العوامل الممكنة ل Agent 365 ووكلاء المحركات المخصصة عبر .NET Python Node.js.

لتثبيت التوزيع، ولإجراء التكوين العام، ولسيناريوهات حزمة تطوير البرامج (SDK) التي لا تستخدم العامل، راجع Microsoft OpenTelemetry Distro.

Overview

هناك أربعة سيناريوهات مصادقة، اعتمادا على نوع العامل وكيفية حصوله على الرموز المميزة. يمكن أن يستخدم اكتساب الرمز المميز تدفق بالنيابة عن (OBO) أو من خدمة إلى خدمة (S2S). اختر السيناريو الذي يطابق الإعداد الخاص بك:

سيناريو	الوصف
الوكيل الممكّن لـ 365 باستخدام OBO	يتولى المكوّن المدمج في التوزيعة AgenticTokenCache اكتساب الرموز تلقائيا على المسار المفوض. لا حاجة إلى محلل مخصص. هذا المسار يحتاج إلى إذن مفوض Agent365.Observability.OtelWrite وموافقة المسؤول، والتي a365 setup all لا تضبط لوكلاء Blueprint.
تمكين العامل 365 باستخدام S2S	يحصل الوكيل على رمز مخصص للتطبيق فقط باستخدام سلسلة الهوية الوكيلة (getAgenticApplicationToken + مكتبات Microsoft Authentication Libraries (MSAL)). يتطلب TokenResolver مخصصًا وخيار نقطة النهاية S2S. لا يحتاج مثيل الوكيل المسجل إلى إذن Observability أو موافقة المسؤول، لذا هذا هو النهج الموصى به لوكلاء Blueprint الذين تم إعدادهم باستخدام a365 setup all.
محرك مخصص باستخدام OBO	يحصل العامل على رمز مميز للمستخدم عبر Azure Bot OAuth، محدد النطاق إلى واجهة برمجة تطبيقات إمكانية المراقبة. يتطلب الأمر مكوّناً مخصصاً TokenResolver، واتصال Azure Bot OAuth، والإذن المفوض Agent365.Observability.OtelWrite مع موافقة المسؤول.
محرك مخصص باستخدام S2S	يحصل العامل على رمز مميز للتطبيق فقط باستخدام بيانات اعتماد العميل. يتطلب TokenResolver مخصّصًا. يجب أن يكون تسجيل التطبيق من النوع القياسي (غير قائم على الوكلاء). تسجيلات التطبيقات القياسية ليست مثيلات وكيل مسجلة، لذا تحتاج إلى Agent365.Observability.OtelWrite إذن التطبيق بموافقة المسؤول.

الوكيل المُمكَّن لـ 365 باستخدام OBO

يتلقى الوكلاء الممكَّنون بواسطة Agent 365 طلبات بهوية وكيل (agenticAppId، agenticUserId) من منصة Agent 365. باستخدام OBO، تتولى التوزيعة المضمنة AgenticTokenCache الحصول على الرموز المميزة تلقائيًا على المسار المفوَّض، لذا لا تحتاج إلى مُعين رموز مميزة مخصص.

Prerequisites

• تسجيل تطبيق Microsoft Entra: اسم رئيسي للخدمة (تسجيل التطبيق) مع معرف العميل، سر العميل، ومعرف المستأجر.

• صلاحيات API المفوضة: أضف Agent365.Observability.OtelWrite (مفوض) وامنح موافقة المسؤول. الأمر a365 setup all لا يضيف هذا الإذن لوكلاء المخطط. يمكن للمسؤول العمومي إضافتها ومنح موافقة المسؤول العمومي عن طريق تشغيل الأمر التالي:

  a365 setup permissions custom --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c --scopes Agent365.Observability.OtelWrite
  

  لمزيد من الخيارات، بما في ذلك مركز مسؤولي Microsoft Entra، راجع منح الإذن.

Tip

لتجنب إذن Observability المفوَّض وموافقة المسؤول، استخدم Agent 365-enabled using S2S لوكلاء Blueprint المُعدّة باستخدام a365 setup all.

الإعداد

في كل تكرار، يستدعي وكيلك الدالة RegisterObservability مستخدمًا سياق التكرار. تستخدم ذاكرة التخزين المؤقت المضمنة الرمز المميز المفوض للمستخدم من AgenticUserAuthorization المعالج لإجراء تبادل OBO، والحصول على رمز مميز محدد النطاق إلى Agent365.Observability.OtelWrite.

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

تمكين العامل 365 باستخدام S2S

يمكن أيضًا للوكلاء المُمكَّنين في Agent 365 استخدام مصادقة S2S (من خدمة إلى خدمة) بدلًا من OBO. يوصى بهذا المسار لوكلاء البلوبرينت الذين يتم إعدادهم باستخدام a365 setup all. يكتسب العامل رمزا مميزا باستخدام الهوية الأساسية للخدمة الخاصة به عبر سلسلة هوية عاملية مكونة من خطوتين:

1. اتصل getAgenticApplicationToken(tenantId, agentId) للحصول على رمز بيانات اعتماد العميل باستخدام مسار الهوية المدارة الفيدرالية (FMI).
2. اتصل ب MSAL acquireTokenForClient باستخدام رمز التطبيق ك clientAssertion و نطاق api://9b975845-388f-4429-889e-eab1ef63949c/.default.

ملحوظة

الهوية المدارة الموحدة (FMI) هي بنية تشارك فيها الهوية المدارة في اتحاد هوية حمل العمل عبر بيانات اعتماد الهوية الموحدة، ما يتيح تبادل الرمز المميز والمصادقة السرية استنادا إلى علاقات الثقة بين الهويات.

تستخدم توزيعة Microsoft OpenTelemetry المسار المفوض بشكل افتراضي، لذا يجب عليك توفير TokenResolver مخصص وتعيين خيار نقطة نهاية S2S للغتك، مثل UseS2SEndpoint = true، useS2SEndpoint: true، أو a365_use_s2s_endpoint=True.

Prerequisites

• تسجيل الوكيل 365: يجب أن يكون مثيل الوكيل مسجلاً لدى Agent 365. يقوم الأمر a365 setup all بتسجيل مثيلات وكيل Blueprint. إنشاء هوية Microsoft Entra وحده لا يسجل مثيل وكيل.
• بيانات اعتماد Blueprint لتبادل FMI: استخدم سر عميل Blueprint أو هوية مدارة للحصول على رمز Federated Managed Identity (FMI) لـ api://AzureADTokenExchange/.default، ثم استبدله برمز Observability الخاص بمثيل العامل.
• مطابقة قيم الهوية: يجب أن يتطابق معرّف الوكيل ومعرّف المستأجر في baggage ورابط التصدير مع معرّف العميل لمثيل الوكيل والمستأجر في الرمز المميز الخاص بالتطبيق فقط.

ملحوظة

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

الخطوة 1: تكوين البيئة

توضح أمثلة التعليمات البرمجية التالية كيفية تعيين إعدادات بيئة الاتصال والمستأجر وبيانات اعتماد العميل ومصدر إمكانية المراقبة المطلوبة قبل تمكين تدفق الرمز المميز S2S المخصص.

Python

لا حاجة AgenticUserAuthorization إلى معالج. يستخدم S2S سلسلة الهوية الوكيلة اليدوية (get_agentic_application_token + MSAL acquire_token_for_client) للحصول على رمز مميز محدد النطاق لمورد إمكانية المراقبة.

CONNECTIONSMAP__0__SERVICEURL=*
CONNECTIONSMAP__0__CONNECTION=SERVICE_CONNECTION

CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<your-client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<your-client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

ENABLE_A365_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true

Node.js

connections__service_connection__settings__clientId=<your-client-id>
connections__service_connection__settings__clientSecret=<your-client-secret>
connections__service_connection__settings__tenantId=<your-tenant-id>
connections__service_connection__settings__scopes=5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default

connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

ENABLE_A365_OBSERVABILITY_EXPORTER=true

.NET

{
  "EnableAgent365Exporter": "true",
  "TokenValidation": { "Enabled": false, "TenantId": "<your-tenant-id>" },
  "AgentApplication": {
    "UserAuthorization": {
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": { "Scopes": ["https://graph.microsoft.com/.default"] }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "AuthType": "ClientSecret",
        "AuthorityEndpoint": "https://login.microsoftonline.com/<your-tenant-id>",
        "ClientId": "<your-client-id>",
        "ClientSecret": "<your-client-secret>",
        "Scopes": ["5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default"]
      }
    }
  },
  "ConnectionsMap": [{ "ServiceUrl": "*", "Connection": "ServiceConnection" }]
}

الخطوة 2: تكوين توزيعة باستخدام محلل الرمز المميز المخصص

توضح الأمثلة التالية كيفية تمكين تصدير عامل 365 وتسجيل مخصص TokenResolver حتى يتمكن المصدر من استرداد رموز S2S المميزة لكل وكيل ومستأجر.

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

_token_cache: dict[str, str] = {}

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _token_cache.get(f"{agent_id}:{tenant_id}")

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    a365_use_s2s_endpoint=True,
    a365_enable_observability_exporter=True,
)

Node.js

import { useMicrosoftOpenTelemetry } from '@microsoft/opentelemetry';

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId, tenantId) => tokenCache.get(`${agentId}:${tenantId}`) ?? '',
    useS2SEndpoint: true,  // S2S uses /observabilityService endpoint
  },
});

.NET

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.Exporters = ExportTarget.Agent365;
        o.Agent365.Exporter.TokenResolver = (agentId, tenantId) =>
            Task.FromResult(TokenCache.Get(agentId, tenantId) ?? string.Empty);
        o.Agent365.Exporter.UseS2SEndpoint = true;
    });

Important

يتطلب S2S عنصرًا مخصصًا TokenResolver. بدونها، لا تمرّر التوزيعة UseS2SEndpoint إلى المُصدِّر.

Warning

لا تقم بإدخال IExporterTokenCache<AgenticTokenStruct> في الدالة الإنشائية للعامل عند استخدام مخصص TokenResolver. تُسجِّل التوزيعة AgenticTokenCache تلقائيًا، وإذا كان الوكيل لديك يحلّه باستخدام DI، فإن ذاكرة التخزين المؤقت المدمجة تكون لها الأسبقية على آلية الحلّ المخصّصة لديك. استخدم IConnections بدلا من ذلك للحصول على الرمز المميز S2S يدويا.

الخطوة 3: الحصول على الرمز المميز S2S وتخزينه مؤقتا

في كل رسالة واردة، احصل على الرمز المميز S2S من خلال سلسلة الهوية الوكيلة واخزنه مؤقتا للمحلل.

Python

import asyncio
from msal import ConfidentialClientApplication
from microsoft.opentelemetry.a365.core import BaggageBuilder, InvokeAgentScope, InvokeAgentScopeDetails, Request

OBSERVABILITY_S2S_SCOPE = "api://9b975845-388f-4429-889e-eab1ef63949c/.default"

async def get_agentic_s2s_token(connection, tenant_id: str, agent_id: str) -> str:
    # Step 1: Get agentic application token (client_credentials + fmi_path)
    app_token = await connection.get_agentic_application_token(tenant_id, agent_id)
    if not app_token:
        raise ValueError(f"Failed to get agentic app token for agent {agent_id}")

    # Step 2: Exchange for observability-scoped token
    cca = ConfidentialClientApplication(
        client_id=agent_id,
        authority=f"https://login.microsoftonline.com/{tenant_id}",
        client_credential={"client_assertion": app_token},
    )
    result = await asyncio.to_thread(
        lambda: cca.acquire_token_for_client(scopes=[OBSERVABILITY_S2S_SCOPE])
    )
    if not result or "access_token" not in result:
        raise ValueError(f"Token acquisition failed: {result}")
    return result["access_token"]

# In your message handler : use SDK helpers to get agent/tenant from the activity:
@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    # get_agentic_instance_id reads from recipient (SDK convention)
    agent_id = context.activity.get_agentic_instance_id()
    tenant_id = context.activity.get_agentic_tenant_id()

    # Acquire S2S token and cache BEFORE creating spans
    connection = CONNECTION_MANAGER.get_connection("SERVICE_CONNECTION")
    token = await get_agentic_s2s_token(connection, tenant_id, agent_id)
    _token_cache[f"{agent_id}:{tenant_id}"] = token

    # Wrap spans in BaggageBuilder so the exporter can resolve the token
    request = Request(content=user_message, session_id=None)
    with BaggageBuilder().tenant_id(tenant_id).agent_id(agent_id).build():
        invoke_scope = InvokeAgentScope.start(request, InvokeAgentScopeDetails(), agent_details)
        with invoke_scope:
            invoke_scope.record_input_messages([user_message])
            invoke_scope.record_output_messages([response])

Important

التدفق اليدوي المكون من خطوتين (get_agentic_application_token + MSAL acquire_token_for_client) مطلوب ل S2S. يعيد AgenticUserAuthorization.get_token() رمزًا مميزًا ضمن النطاق الخاص بـ 5a807f24-.../.default (Bot Framework)، وليس مورد قابلية الملاحظة api://9b975845-.../.default: إذ ترفضه نقطة نهاية S2S مع 401 InvalidAudience.

• استخدم context.activity.get_agentic_instance_id() و get_agentic_tenant_id() لقراءة الوكيل والمستأجر من النشاط (مع القراءة من recipient وفقًا لاصطلاحات SDK).
• الحصول على رمز S2S المميز وتخزينه مؤقتًا قبل إنشاء النطاقات. قد يُفرِّغ المُصدِّر BatchSpanProcessor قبل أن ينتهي المعالج: إذا لم يكن الرمز مخزَّنًا مؤقتًا بعد، فسيفشل التصدير.
• أحِط جميع نطاقات A365 بـ BaggageBuilder حتى يعرف المُصدِّر أي وكيل وأي مستأجر يجب حلّ الرموز المميزة الخاصة بهما. بدون بيانات الـBaggage، تُسقَط نطاقات التتبّع بصمت مع ظهور الرسالة "لم يتم العثور على نطاقات تتبّع تتضمن هوية المستأجر/الوكيل".

Node.js

import { ConfidentialClientApplication } from '@azure/msal-node';
import { PROD_OBSERVABILITY_SCOPE } from '@microsoft/agents-a365-runtime';

async function getAgenticS2SToken(connection, tenantId: string, agentId: string): Promise<string> {
  // Step 1: Get agentic application token
  const appToken = await connection.getAgenticApplicationToken(tenantId, agentId);

  // Step 2: Exchange for observability-scoped token
  const cca = new ConfidentialClientApplication({
    auth: { clientId: agentId, clientAssertion: appToken,
            authority: `https://login.microsoftonline.com/${tenantId}` },
  });
  const result = await cca.acquireTokenByClientCredential({ scopes: [PROD_OBSERVABILITY_SCOPE] });
  if (!result?.accessToken) throw new Error('No access token returned');
  return result.accessToken;
}

// In your message handler:
const connection = adapter.connectionManager.getConnection('service_connection');
const token = await getAgenticS2SToken(connection, tenantId, agentId);
tokenCache.set(`${agentId}:${tenantId}`, token);

.NET

using Microsoft.Agents.Authentication.Msal;
using Microsoft.Identity.Client;

// In your message handler:
var msalAuth = (MsalAuth)_connections.GetConnection("ServiceConnection");
var appToken = await msalAuth.GetAgenticApplicationTokenAsync(tenantId, agentId, cancellationToken);

var cca = ConfidentialClientApplicationBuilder
    .Create(agentId)
    .WithClientAssertion(appToken)
    .WithAuthority($"https://login.microsoftonline.com/{tenantId}")
    .Build();

var result = await cca.AcquireTokenForClient(
    new[] { "api://9b975845-388f-4429-889e-eab1ef63949c/.default" })
    .ExecuteAsync(cancellationToken);

TokenCache.Set(agentId, tenantId, result.AccessToken);

Important

قبل أن يعيد محلّل الأسماء لديك رمز Observability النهائي ويخزّنه مؤقتًا:

• تحقق من أن الرمز مخصص للتطبيق فقط. قبول idtyp=app. إذا idtyp كان غائبا، اقبل فقط رمزا له مطالبة غير فارغة roles أو مطالبة غير فارغة oid تساوي sub. ارفض الرموز التي لها مطالبة scp أو قيمة idtyp أخرى.
• تحقق من أن هذا aud هو 9b975845-388f-4429-889e-eab1ef63949c أو api://9b975845-388f-4429-889e-eab1ef63949c، وأن الرمز لم ينته الصلاحية.
• لا ترسل أبدا إثبات المخطط الوسيط، أو رمز المخطط، أو رمز مستخدم أو رمز OBO إلى Observability.
• خزّن الرمز المميز النهائي وقم بتحديثه قبل انتهاء صلاحيته. يقوم المصدر باستدعاء مُحلِّل التعارض مرة واحدة لكل مستأجر ولكل هوية وكيل في كل دفعة تصدير.

للتطبيقات الكاملة التي تستخدم التوزيعة، راجع عينات Agent 365 ل Node.jsو Python و .NET.

محرك مخصص باستخدام OBO

يستخدم وكلاء المحرك المخصصون تسجيلات التطبيقات القياسية مع اتصالات Azure Bot OAuth، وليس سلسلة الهوية الوكيلة. باستخدام OBO، يحصل العامل على رمز مميز للمستخدم من خلال Azure Bot OAuth الذي تم تحديد نطاقه بالفعل إلى API إمكانية المراقبة A365 بواسطة خدمة الرمز المميز ل Bot Framework. يقوم استدعاء واحد getToken أو GetTurnTokenAsync بإرجاع الرمز المميز المحدد بشكل صحيح، لذلك لا تحتاج إلى exchangeToken.

Prerequisites

تسجيل تطبيق Microsoft Entra مع صلاحيات API المفوضة. أضف Agent365.Observability.OtelWrite (مفوَّض) وامنح موافقة الإدارة.

Important

يجب أن يتطابق agentId في ذاكرة التخزين المؤقت للرمز المميز مع معرّف العميل الخاص بتسجيل التطبيق، وليس agenticAppId الخاص بالنشاط، لأنه غير موجود لعوامل المحرك المخصصة. يتضمن agentIdعنوان URL للتصدير ، ويؤدي عدم التطابق إلى HTTP 403.

الخطوة 1: تكوين البيئة والتطبيق

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

Python

# .env
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<your-client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<your-client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

CONNECTIONSMAP__0__CONNECTION=SERVICE_CONNECTION
CONNECTIONSMAP__0__SERVICEURL=*

# Auth handler config : TYPE is required, name is uppercased by load_configuration_from_env
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__OBOCONNECTIONPROFILE__TYPE=UserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__OBOCONNECTIONPROFILE__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME=oboConnectionProfile
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__OBOCONNECTIONPROFILE__SETTINGS__SCOPES=api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite

ENABLE_A365_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true

Important

load_configuration_from_env يحوّل جميع مفاتيح متغيرات البيئة إلى أحرف كبيرة. يصبح اسم المعالج OBOCONNECTIONPROFILE، ويجب عليك الإشارة إليه بنفس حالة الأحرف تمامًا في استدعاءات auth_handlers وget_token(). يؤدي غياب TYPE إلى حدوث Auth handler ... not recognized or not configured في وقت التشغيل.

Node.js

# .env
connections__serviceConnection__settings__clientId=<your-client-id>
connections__serviceConnection__settings__clientSecret=<your-client-secret>
connections__serviceConnection__settings__tenantId=<your-tenant-id>

connectionsMap__0__connection=serviceConnection
connectionsMap__0__serviceUrl=*

# Azure Bot OAuth connection names (must match Azure Portal config)
oboConnectionProfile_azureBotOAuthConnectionName=oboConnectionProfile
oboConnectionProfile_scopes=api://botid-<your-client-id>/default
agentic_azureBotOAuthConnectionName=agentic
agentic_scopes=https://graph.microsoft.com/.default

.NET

// appsettings.json
{
  "TokenValidation": {
    "Enabled": true,
    "Audiences": ["<your-client-id>"],
    "TenantId": "<your-tenant-id>"
  },
  "AgentApplication": {
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AzureBotUserAuthorization",
          "Settings": {
            "AzureBotOAuthConnectionName": "agentic",
            "Scopes": ["https://graph.microsoft.com/.default"]
          }
        },
        "oboConnectionProfile": {
          "Type": "AzureBotUserAuthorization",
          "Settings": {
            "AzureBotOAuthConnectionName": "oboConnectionProfile",
            "Scopes": ["api://botid-<your-client-id>/default"]
          }
        }
      }
    }
  },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "ClientId": "<your-client-id>",
        "ClientSecret": "<your-client-secret>",
        "TenantId": "<your-tenant-id>",
        "Scopes": ["https://api.botframework.com/.default"]
      }
    }
  },
  "ConnectionsMap": [{ "ServiceUrl": "*", "Connection": "ServiceConnection" }]
}

الخطوة 2: تكوين توزيعة OBO

توضح الأمثلة التالية كيفية تمكين التصدير في Agent 365، والإبقاء على المُصدِّر على نقطة نهاية OBO، وتسجيل TokenResolver مخصص يُرجع رموزًا مميزةً مفوَّضة أثناء التصدير.

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

_token_cache: dict[str, str] = {}

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _token_cache.get(f"{agent_id}:{tenant_id}")

environ["ENABLE_A365_OBSERVABILITY_EXPORTER"] = "true"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    a365_use_s2s_endpoint=False,  # OBO uses /observability endpoint
    a365_enable_observability_exporter=True,
)

ملحوظة

يتطلب jwt_authorization_middleware وضع OBO على aiohttpApplication (للتحقق من صحة JWT الوارد (رمز ويب JSON) من Bot Framework). يجب ألا يتضمن مسار S2S/emulator هذا البرنامج الوسيط.

from microsoft_agents.hosting.aiohttp import jwt_authorization_middleware
app = Application(middlewares=[jwt_authorization_middleware])

Node.js

import { useMicrosoftOpenTelemetry } from '@microsoft/opentelemetry';

const tokenCache = new Map<string, string>();

const otelTokenResolver = async (agentId: string, tenantId: string): Promise<string> => {
  return tokenCache.get(`${agentId}:${tenantId}`) ?? '';
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: otelTokenResolver,
    useS2SEndpoint: false,  // OBO uses /observability endpoint
  },
});

.NET

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.Exporters = ExportTarget.Agent365;
        o.Agent365.Exporter.TokenResolver = (agentId, tenantId) =>
            Task.FromResult(TokenCache.Get(agentId, tenantId) ?? string.Empty);
        // UseS2SEndpoint defaults to false : exports to /observability
    });

الخطوة 3: الحصول على رمز OBO المميز

توضح الأمثلة التالية كيفية طلب رمز OBO مميزًا مفوضًا من اتصال Azure Bot OAuth المكوَّن، ثم تخزينه مؤقتًا حسب عميل التطبيق والمستأجر للمُصدِّر.

Python

from microsoft_agents.hosting.core import (
    AgentApplication, Authorization, MemoryStorage, TurnContext, TurnState,
)
from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter

# Auth handlers are loaded from .env via load_configuration_from_env (see Environment config above)
agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config,
)

CLIENT_ID = environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID", "")
TENANT_ID = environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID", "")

# Message handler : get_token returns a token already scoped to the observability API.
# The Azure Bot Token Service performs the OBO exchange internally based on the
# OAuth connection's configured scope. No manual MSAL exchange_token call is needed.
@AGENT_APP.activity("message", auth_handlers=["OBOCONNECTIONPROFILE"])
async def on_message(context: TurnContext, _state: TurnState):
    token_response = await AGENT_APP.auth.get_token(context, "OBOCONNECTIONPROFILE")
    # token_response.token has aud=<a365-observability-app-id>,
    # scp=Agent365.Observability.OtelWrite
    _token_cache[f"{CLIENT_ID}:{TENANT_ID}"] = token_response.token

Important

المتطلب الأساسي لبوابة Azure: عيّن Scopes لاتصال Azure Bot OAuth المسمى oboConnectionProfile إلى api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite. بدون هذا الإعداد، يتم تحديد نطاق الرمز المميز لجمهور الروبوت الخاص (api://botid-...) ويفشل التصدير مع HTTP 401 InvalidAudience.

ملحوظة

AGENT_APP.auth.get_token() يعيد الرمز المميز المحدد بشكل صحيح مباشرة - لا حاجة إلى استدعاء exchange_token(). تتعامل خدمة الرموز المميزة لـ Bot Framework مع عملية تبادل OBO عندما يكون نطاق اتصال OAuth موجّهًا إلى مورد قابلية الملاحظة A365.

Node.js

// In constructor : configure Azure Bot OAuth connection handler:
super({
  storage: new MemoryStorage(),
  authorization: {
    oboConnectionProfile: {
      azureBotOAuthConnectionName: 'oboConnectionProfile',
      scopes: ['api://botid-<your-client-id>/default'],
    },
  },
})
// autoSignIn triggers the Azure Bot OAuth SSO flow before the handler runs:
this.onActivity('message', this.handleMessage, ['oboConnectionProfile'])

// In handler : single call, no exchangeToken needed:
const oboToken = await this.authorization.getToken(ctx, 'oboConnectionProfile');

// Cache using the app's Client ID (not from activity : custom engine agents have no agenticAppId):
const clientId = process.env.connections__serviceConnection__settings__clientId;
const tenantId = process.env.connections__serviceConnection__settings__tenantId;
tokenCache.set(`${clientId}:${tenantId}`, oboToken.token);

.NET

// In constructor : autoSignInHandlers triggers Azure Bot OAuth SSO before the handler runs:
OnActivity(ActivityTypes.Message, OnMessageAsync,
    autoSignInHandlers: new[] { "oboConnectionProfile" });

// In handler : single call, no ExchangeTurnTokenAsync needed:
var token = await UserAuthorization.GetTurnTokenAsync(
    turnContext, "oboConnectionProfile", cancellationToken);

// Cache using the app's Client ID (not from activity : custom engine agents have no agenticAppId):
var agentId = _configuration["Connections:ServiceConnection:Settings:ClientId"];
var tenantId = _configuration["TokenValidation:TenantId"];
TokenCache.Set(agentId, tenantId, token);

ملحوظة

يعيد استدعاء واحد getToken أو GetTurnTokenAsync الرمز المميز بالنطاق الصحيح - ولا حاجة إلى استدعاء exchangeToken أو ExchangeTurnTokenAsync. اتصال Azure Bot OAuth الذي تقوم بتكوينه في بوابة Azure يقوم بإجراء تبادل OBO داخليًا عندما تستهدف Scopes مورد قابلية الرصد A365.

محرك مخصص باستخدام S2S

يمكن لوكلاء المحرك المخصص استخدام S2S (بيانات اعتماد العميل) للحصول على رمز مميز خاص بالتطبيق فقط باستخدام بيانات اعتماد اتصال الخدمة. تستخدم هذه الطريقة بيانات اعتماد عميل MSAL القياسية - ولا تحتاج إلى سلسلة هوية وكيلية.

Prerequisites

• تسجيل تطبيق Microsoft Entra: يجب أن يكون تسجيل التطبيق محركًا مخصصًا (قياسيًا). لا يمكن لتسجيلات التطبيقات الممكّنة لـ Agent 365 استخدام client_credentials وحده لمورد قابلية الملاحظة (AADSTS82001).
• أذونات التطبيق: إضافة Agent365.Observability.OtelWrite (التطبيق، وليس مفوضًا)، ومنح موافقة المسؤول. تسجيلات التطبيقات القياسية ليست مثيلات وكيل مسجلة لدى Agent 365، لذا فهي تحتاج إلى دور التطبيق هذا على مسار S2S.

Important

agentId التي تستخدمها للتخزين المؤقت يجب أن تكون الخاصة بـ ClientIdServiceConnection. عنوان URL للتصدير هو /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces : عدم التطابق يؤدي إلى HTTP 403.

الخطوة 1: تكوين البيئة والتطبيق

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

Python

# .env
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<your-client-id>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<your-client-secret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

CONNECTIONSMAP__0__CONNECTION=SERVICE_CONNECTION
CONNECTIONSMAP__0__SERVICEURL=*

ENABLE_A365_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true

Node.js

# .env
connections__serviceConnection__settings__clientId=<your-client-id>
connections__serviceConnection__settings__clientSecret=<your-client-secret>
connections__serviceConnection__settings__tenantId=<your-tenant-id>

connectionsMap__0__connection=serviceConnection
connectionsMap__0__serviceUrl=*

.NET

// appsettings.json : S2S does not require token validation or UserAuthorization handlers
{
  "TokenValidation": { "Enabled": false, "TenantId": "<your-tenant-id>" },
  "Connections": {
    "ServiceConnection": {
      "Settings": {
        "ClientId": "<your-client-id>",
        "ClientSecret": "<your-client-secret>",
        "TenantId": "<your-tenant-id>",
        "Scopes": ["https://api.botframework.com/.default"]
      }
    }
  },
  "ConnectionsMap": [{ "ServiceUrl": "*", "Connection": "ServiceConnection" }]
}

الخطوة 2: تكوين توزيعة S2S

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

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

_token_cache: dict[str, str] = {}

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _token_cache.get(f"{agent_id}:{tenant_id}")

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    a365_use_s2s_endpoint=True,  # S2S uses /observabilityService endpoint
    a365_enable_observability_exporter=True,
)

Node.js

import { useMicrosoftOpenTelemetry } from '@microsoft/opentelemetry';

const tokenCache = new Map<string, string>();

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId, tenantId) => tokenCache.get(`${agentId}:${tenantId}`) ?? '',
    useS2SEndpoint: true,  // S2S uses /observabilityService endpoint
  },
});

.NET

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.Exporters = ExportTarget.Agent365;
        o.Agent365.Exporter.TokenResolver = (agentId, tenantId) =>
            Task.FromResult(TokenCache.Get(agentId, tenantId) ?? string.Empty);
        o.Agent365.Exporter.UseS2SEndpoint = true;
    });

Important

يتطلب S2S عنصرًا مخصصًا TokenResolver. بدونها، لا تمرّر التوزيعة UseS2SEndpoint إلى المُصدِّر.

الخطوة 3: الحصول على الرمز المميز S2S

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

Python

# Force agentId to ServiceConnection ClientId (custom engine agents have no agenticAppId)
agent_id = os.environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID")
tenant_id = os.environ.get("CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID")

connection = CONNECTION_MANAGER.get_connection("SERVICE_CONNECTION")
token = await connection.get_access_token(
    resource_url="https://login.microsoftonline.com",
    scopes=["api://9b975845-388f-4429-889e-eab1ef63949c/.default"],
)
_token_cache[f"{agent_id}:{tenant_id}"] = token

Node.js

const clientId = process.env.connections__serviceConnection__settings__clientId;
const tenantId = process.env.connections__serviceConnection__settings__tenantId;

const connection = this.adapter.connectionManager.getConnection('serviceConnection');
const token = await connection?.getAccessToken('api://9b975845-388f-4429-889e-eab1ef63949c');
tokenCache.set(`${clientId}:${tenantId}`, token);

.NET

// Force agentId to ServiceConnection ClientId (custom engine agents have no agenticAppId)
var agentId = _configuration["Connections:ServiceConnection:Settings:ClientId"];
var tenantId = _configuration["TokenValidation:TenantId"];

var connection = _connections.GetConnection("ServiceConnection");
var token = await connection.GetAccessTokenAsync(
    "https://login.microsoftonline.com",
    new List<string> { "api://9b975845-388f-4429-889e-eab1ef63949c/.default" });

TokenCache.Set(agentId, tenantId, token);

الخطوة 4: تعيين الأمتعة لتصدير النطاق

يتطلب Exporter ‏Agent365 بيانات baggage (معرّف المستأجر ومعرّف الوكيل) في سياق المدى. بدون هذا baggage، يقوم المصدر بإسقاط الامتدادات ويسجل الرسالة No spans with tenant/agent identity found..

Python

from microsoft.opentelemetry.a365.core import BaggageBuilder, InvokeAgentScope

# Baggage must wrap the span as a context manager
with BaggageBuilder().tenant_id(tenant_id).agent_id(agent_id).build():
    invoke_scope = InvokeAgentScope.start(request, InvokeAgentScopeDetails(), agent_details)
    with invoke_scope:
        invoke_scope.record_input_messages([user_message])
        invoke_scope.record_output_messages([response])

Node.js

عند تكوين ObservabilityHostingManager البرنامج الوسيط على المحول، فإنه يقوم تلقائيا بتعيين الأمتعة.

.NET

using var baggageScope = new BaggageBuilder()
    .TenantId(tenantId)
    .AgentId(agentId)
    .Build();

using var invokeScope = InvokeAgentScope.Start(request, new InvokeAgentScopeDetails(), agentDetails);
invokeScope.RecordOutputMessages(new[] { response });