अवलोकन प्रमाणीकरण सेटअप

Agent 365 निर्यातक को टेलीमेट्री निर्यात करते समय प्रमाणीकरण के लिए एक टोकन रिज़ॉल्वर की आवश्यकता होती है। यह गाइड Microsoft 365 एजेंट SDK के साथ निर्मित Agent 365-सक्षम एजेंटों की सेटअप प्रक्रिया को कवर करता है, जिसमें .NET, Python और Node.js पर चलने वाले Agent 365-सक्षम एजेंट और कस्टम इंजन एजेंट दोनों शामिल हैं।

डिस्ट्रो इंस्टॉलेशन, सामान्य कॉन्फ़िगरेशन, और गैर-एजेंट SDK परिदृश्यों के लिए, Microsoft OpenTelemetry Distro देखें।

अवलोकन

आपके एजेंट प्रकार और टोकन प्राप्ति के तरीके के आधार पर चार प्रमाणीकरण परिदृश्य हैं। टोकन प्राप्त करने के लिए ऑन-बेहाफ-ऑफ फ्लो (OBO) या सर्विस-टू-सर्विस (S2S) का उपयोग किया जा सकता है। अपने सेटअप के अनुसार परिदृश्य चुनें:

परिदृश्य	विवरण
OBO का उपयोग करके Agent 365-सक्षम	डिस्ट्रो का बिल्ट-इन `AgenticTokenCache` टोकन अधिग्रहण को स्वचालित रूप से संभालता है। किसी कस्टम रिज़ॉल्वर की आवश्यकता नहीं है। यह Agent 365-सक्षम एजेंटों के लिए अनुशंसित दृष्टिकोण है।
S2S का उपयोग करके Agent 365-सक्षम	एजेंट एजेंटिक पहचान श्रृंखला (`getAgenticApplicationToken` + Microsoft प्रमाणीकरण लाइब्रेरीज़ (MSAL)) का उपयोग करके टोकन प्राप्त करता है। कस्टम `TokenResolver` की आवश्यकता होती है। इस विधि का उपयोग तब करें जब OBO उपलब्ध न हो या आपको केवल ऐप-ओनली टोकन की आवश्यकता हो।
OBO का उपयोग करने वाला कस्टम इंजन	एजेंट को Azure बॉट OAuth के माध्यम से एक उपयोगकर्ता टोकन मिलता है, जो ऑब्जर्वेबिलिटी API के लिए स्कोप किया गया है। कस्टम `TokenResolver` और Azure बॉट OAuth कनेक्शन आवश्यक है।
S2S का उपयोग करने वाला कस्टम इंजन	एजेंट क्लाइंट क्रेडेंशियल्स का उपयोग करके ऐप-ओनली टोकन प्राप्त करता है। कस्टम `TokenResolver` की आवश्यकता होती है। ऐप पंजीकरण एक मानक (गैर-एजेंटिक) ऐप होना चाहिए।

OBO का उपयोग करके Agent 365-सक्षम

Agent 365-सक्षम एजेंटों को Agent 365 प्लेटफ़ॉर्म से एजेंटिक पहचान (agenticAppId, agenticUserId) के साथ अनुरोध प्राप्त होते हैं। OBO के साथ, डिस्ट्रो का अंतर्निहित AgenticTokenCache टोकन अधिग्रहण को स्वचालित रूप से संभालता है : कोई कस्टम टोकन रिज़ॉल्वर आवश्यक नहीं है।

आवश्यकताएँ

Entra ऐप पंजीकरण : क्लाइंट ID, क्लाइंट सीक्रेट और टेनेंट ID के साथ सेवा प्रिंसिपल (ऐप पंजीकरण)
प्रत्यायोजित एपीआई अनुमतियाँ : Agent365.Observability.OtelWrite जोड़ें (प्रत्यायोजित), एडमिन सहमति दें। विस्तृत चरणों के लिए, अनुमति प्रदान करें देखें.

सेटअप

हर टर्न पर, आपका एजेंट RegisterObservability फ़ंक्शन को टर्न कॉन्टेक्स्ट के साथ कॉल करता है। बिल्ट-इन कैश AgenticUserAuthorization हैंडलर से उपयोगकर्ता के प्रत्यायोजित टोकन का उपयोग करके OBO एक्सचेंज करता है, जिससे Agent365.Observability.OtelWrite के लिए स्कोप किया गया टोकन प्राप्त होता है।

पूर्ण सेटअप निर्देशों (पैकेज, कॉन्फ़िगरेशन और कोड उदाहरण सहित) के लिए देखें: Agentic टोकन कैश विथ Agent Framework ऐप्स।

S2S का उपयोग करके Agent 365-सक्षम

Agent 365-सक्षम एजेंट भी OBO के बजाय S2S (सेवा-से-सेवा) प्रमाणीकरण का उपयोग कर सकते हैं। एजेंट अपनी सर्विस प्रिंसिपल पहचान का उपयोग करते हुए दो-चरणीय एजेंटिक पहचान श्रृंखला के माध्यम से एक टोकन प्राप्त करता है:

getAgenticApplicationToken(tenantId, agentId) : क्लाइंट क्रेडेंशियल्स + फेडरेटेड प्रबंधित पहचान (FMI) पथ
MSAL acquireTokenForClient ऐप टोकन के रूप में clientAssertion और दायरे के साथ api://9b975845-388f-4429-889e-eab1ef63949c/.default

नोट

फ़ेडरेटेड प्रबंधित पहचान (FMI) एक आर्किटेक्चर है जहाँ एक प्रबंधित पहचान फ़ेडरेटेड पहचान क्रेडेंशियल्स के माध्यम से कार्यभार पहचान फेडरेशन में भाग लेती है, जो पहचानों के बीच विश्वास संबंधों के आधार पर टोकन विनिमय और बिना सीक्रेट के प्रमाणीकरण को सक्षम करती है।

आपको एक कस्टम TokenResolver प्रदान करना होगा और UseS2SEndpoint = true सेट करना होगा।

आवश्यकताएँ

Entra ऐप पंजीकरण : क्लाइंट ID, क्लाइंट सीक्रेट और टेनेंट ID के साथ सेवा प्रिंसिपल (ऐप पंजीकरण)
एप्लिकेशन एपीआई अनुमतियाँ : Agent365.Observability.OtelWrite जोड़ें (एप्लिकेशन), और व्यवस्थापक सहमति दें
Agent365.Observability.OtelWrite ऐप भूमिका : एजेंट के सेवा प्रिंसिपल के पास Agent365 Observability संसाधन पर OtelWrite भूमिका असाइन की गई होनी चाहिए। Agent 365 सीएलआई का उपयोग करें:
```
a365 setup permissions bot --config-dir "<path-to-config-dir>"
```
नोट

भूमिका प्रसार में कुछ मिनट लग सकते हैं। इस अवधि के दौरान निर्यात समापन बिंदु से प्रारंभिक 401 या 403 त्रुटियाँ अपेक्षित हैं।

चरण 1: पर्यावरण कॉन्फ़िगरेशन

निम्नलिखित कोड उदाहरण दिखाते हैं कि कस्टम S2S टोकन प्रवाह को सक्षम करने से पहले आवश्यक कनेक्शन, टेनेंट, क्लाइंट क्रेडेंशियल और ऑब्जर्वेबिलिटी निर्यातक पर्यावरण सेटिंग्स कैसे सेट की जाती हैं।

हैंडलर 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

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

{
  "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: कस्टम टोकन रिज़ॉल्वर के साथ डिस्ट्रो को कॉन्फ़िगर करें

निम्न उदाहरण दिखाते हैं कि Agent 365 निर्यात को कैसे सक्षम करें और एक कस्टम TokenResolver पंजीकृत करें ताकि निर्यातक प्रत्येक एजेंट और टेनेंट के लिए S2S टोकन प्राप्त कर सके।

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,
)

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

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

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;
    });

महत्त्वपूर्ण

S2S को एक कस्टम TokenResolver की आवश्यकता होती है। इसके बिना, डिस्ट्रो निर्यातक को प्रचारित UseS2SEndpoint नहीं करता है।

चेतावनी

कस्टम TokenResolver का इस्तेमाल करते समय अपने एजेंट कंस्ट्रक्टर में IExporterTokenCache<AgenticTokenStruct> इंजेक्ट न करें। डिस्ट्रो स्वतः AgenticTokenCache को रजिस्टर करता है, और यदि आपका एजेंट इसे DI के माध्यम से हल करता है, तो अंतर्निहित कैश कस्टम रिज़ॉल्वर से अधिक प्राथमिकता प्राप्त करता है। S2S टोकन को मैन्युअल रूप से प्राप्त करने के लिए IConnections का उपयोग करें।

चरण 3: S2S टोकन प्राप्त करें और कैश करें

प्रत्येक आने वाले संदेश पर, एजेंटिक पहचान श्रृंखला के माध्यम से S2S टोकन प्राप्त करें और इसे रिज़ॉल्वर के लिए कैश करें।

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])

महत्त्वपूर्ण

S2S के लिए मैनुअल दो-चरणीय प्रवाह (get_agentic_application_token + MSAL acquire_token_for_client) आवश्यक है। AgenticUserAuthorization.get_token(), 5a807f24-.../.default (Bot Framework), के लिए स्कोप वाला टोकन लौटाता है, न कि ऑब्जर्वेबिलिटी रिसोर्स api://9b975845-.../.default : S2S एंडपॉइंट इसे 401 InvalidAudience के साथ रिजेक्ट कर देता है।

एजेंट और टैनेंट को गतिविधि से पढ़ने के लिए context.activity.get_agentic_instance_id() और get_agentic_tenant_id() का उपयोग करें (यह SDK कन्वेंशन के अनुसार recipient से पढ़ता है)।
S2S टोकन प्राप्त करें और कैश करें स्पैन बनाने से पहले. निर्यातक का BatchSpanProcessor हैंडलर समाप्त होने से पहले फ्लश हो सकता है: यदि टोकन अभी तक कैश नहीं किया गया है, तो निर्यात विफल हो जाता है।
सभी A365 स्कोप्स को BaggageBuilder में रैप ताकि निर्यातक यह पहचान सके कि किस एजेंट और किरायेदार के लिए टोकन रिज़ॉल्व करना है। बैगेज के बिना, स्पैन चुपचाप ड्रॉप कर दिए जाते हैं और "कोई स्पैन नहीं मिला जिसमें टेनेंट/एजेंट पहचान हो" दिखाया जाता है।

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);

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);

OBO का उपयोग करने वाला कस्टम इंजन

कस्टम इंजन एजेंट Azure Bot OAuth कनेक्शन के साथ मानक ऐप पंजीकरण का उपयोग करते हैं, एजेंटिक पहचान श्रृंखला का उपयोग नहीं करते। OBO का उपयोग करने पर, एजेंट को Azure Bot OAuth के माध्यम से एक यूज़र टोकन प्राप्त होता है, जिसे Bot Framework Token Service द्वारा पहले ही A365 ऑब्जर्वेबिलिटी API के लिए स्कोप किया गया होता है। एक getToken या GetTurnTokenAsync कॉल से सही ढंग से स्कोप किया गया टोकन प्राप्त हो जाता है, इसलिए exchangeToken की आवश्यकता नहीं है।

आवश्यकताएँ

Entra ऐप पंजीकरण जिसमें प्रत्यायोजित API अनुमतियाँ हों। Agent365.Observability.OtelWrite (प्रत्यायोजित) जोड़ें और व्यवस्थापक सहमति प्रदान करें

महत्त्वपूर्ण

टोकन कैश में agentId को ऐप रजिस्ट्रेशन के क्लाइंट आईडी से मेल खाना चाहिए - न कि गतिविधि के agenticAppId, जो कस्टम इंजन एजेंटों के लिए मौजूद नहीं है। export URL में agentId शामिल है, और मेल न होने पर HTTP 403 त्रुटि उत्पन्न होती है।

चरण 1: परिवेश और ऐप्लिकेशन कॉन्फ़िगरेशन

निम्न उदाहरण दिखाते हैं कि अपने ऐप और रनटाइम एनवायरनमेंट को कैसे कॉन्फ़िगर करें, जिसमें सेवा कनेक्शन मान, टेनेंट और क्लाइंट सेटिंग्स, और आवश्यक प्राधिकरण मैपिंग्स शामिल हैं।

# .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

महत्त्वपूर्ण

load_configuration_from_env अपरकेस सभी पर्यावरण चर कुंजियाँ। हैंडलर नाम OBOCONNECTIONPROFILE बन जाता है और आपको auth_handlers तथा get_token() कॉल में उसी अक्षर केस के साथ उसका संदर्भ देना होगा। TYPE की अनुपस्थिति से रनटाइम पर Auth handler ... not recognized or not configured होता है।

# .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

// 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 पंजीकृत करें जो निर्यात के दौरान प्रतिनिधि टोकन लौटाता है।

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,
)

नोट

OBO मोड के लिए jwt_authorization_middleware की आवश्यकता होती है, जो aiohttpApplication पर लागू होता है (जो Bot Framework से प्राप्त इनबाउंड JWT (JSON वेब टोकन) को मान्य करता है)। S2S/एमुलेटर पथ में इस मिडलवेयर को शामिल न करें।

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

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
  },
});

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 टोकन प्राप्त करें

निम्न उदाहरण दर्शाते हैं कि कॉन्फ़िगर किए गए Azure बॉट OAuth कनेक्शन से एक प्रत्यायोजित OBO टोकन का अनुरोध कैसे करें, फिर उसे निर्यातक के लिए ऐप क्लाइंट और टेनेंट के अनुसार कैश करें।

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

महत्त्वपूर्ण

Azure पोर्टल पूर्वापेक्षा: Azure बॉट 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 Token Service OBO एक्सचेंज को तब संभालती है जब OAuth कनेक्शन का दायरा A365 ऑब्जर्वेबिलिटी संसाधन को लक्षित करता है।

// 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);

// 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 पोर्टल में कॉन्फ़िगर किया गया Azure Bot OAuth कनेक्शन तब OBO एक्सचेंज आंतरिक रूप से करता है जब उसके स्कोप A365 ऑब्ज़र्वेबिलिटी संसाधन को लक्ष्यित करते हैं।

S2S का उपयोग करने वाला कस्टम इंजन

कस्टम इंजन एजेंट S2S (क्लाइंट क्रेडेंशियल्स) के माध्यम से सेवा कनेक्शन क्रेडेंशियल्स का उपयोग करके केवल ऐप टोकन प्राप्त कर सकते हैं। यह विधि मानक MSAL क्लाइंट क्रेडेंशियल्स का उपयोग करती है - कोई एजेंटिक पहचान श्रृंखला की आवश्यकता नहीं है।

आवश्यकताएँ

Azure AD ऐप पंजीकरण : एक कस्टम इंजन (मानक) ऐप होना चाहिए। Agent 365-सक्षम ऐप पंजीकरण साधारण client_credentials का उपयोग अवलोकन संसाधन (AADSTS82001) के लिए नहीं कर सकते हैं।
आवेदन अनुमतियाँ : जोड़ें Agent365.Observability.OtelWrite (आवेदन, प्रतिनिधि नहीं), और व्यवस्थापक सहमति प्रदान करें।

महत्त्वपूर्ण

कैशिंग के लिए उपयोग किया जाने वाला agentId, अनिवार्य रूप से ServiceConnection का ClientId होना चाहिए। निर्यात URL है /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces : एक बेमेल HTTP 403 का कारण बनता है।

चरण 1: परिवेश और ऐप्लिकेशन कॉन्फ़िगरेशन

# .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

# .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=*

// 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 के लिए डिस्ट्रो कॉन्फ़िगर करें

निम्न उदाहरण दिखाते हैं कि Agent 365 निर्यात को कैसे सक्षम करें, निर्यातक को S2S एंडपॉइंट पर कैसे सेट करें, और निर्यात के दौरान टोकन लुकअप के लिए एक कस्टम TokenResolver कैसे पंजीकृत करें।

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,
)

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
  },
});

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;
    });

महत्त्वपूर्ण

चरण 3: S2S टोकन प्राप्त करें

निम्न उदाहरण दिखाते हैं कि सेवा कनेक्शन क्रेडेंशियल्स का उपयोग करके observability संसाधन के लिए केवल ऐप-एक्सेस टोकन कैसे अनुरोध करें, और फिर उसे निर्यातक के लिए प्रत्येक एजेंट और टैनेंट के हिसाब से कैसे कैश करें।

# 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

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);

// 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: स्पैन निर्यात के लिए बैगेज सेट करें

Agent365 निर्यातक के लिए स्पैन संदर्भ में बैगेज (टेनेंट ID और एजेंट ID) सेट होना अनिवार्य है। इसके बिना, निर्यातक चुपचाप स्पैन को छोड़ देता है और संदेश No spans with tenant/agent identity found. दिखाता है।

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])

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

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

प्रतिक्रिया

क्या यह पेज मददगार था?

पिछली बार 2026-08-01 को अपडेट किया गया

अवलोकन प्रमाणीकरण सेटअप