Havaittavuuden todennuksen määritys

Agent 365 -vientitoiminto tarvitsee todennukseen tunnuksen selvityksen telemetriaa vietäessä. Tämä oppaassa käsitellään Microsoft 365 -agenttien SDK:n avulla kehitettyjä agentteja. Oppaassa käsitellään sekä Agent 365:n käyttöönottamat agentit että mukautettujen moduulien agentit .NET-, Python- ja Node.js-ympäristöissä.

Lisätietoja Distro-asennuksesta, yleisistä määrityksistä ja muista kuin agenttien SDK-skenaarioista on kohdassa Microsoft OpenTelemetry Distro.

Yleiskatsaus

Käytössä on neljä todennusskenaariota, jotka määräytyvät agentin tyypin ja sen tavan mukaan, jolla agentti hankkii tunnuksia. Tunnusten hankinnassa voi olla käytössä OBO (On-Behalf-Of-vuo) tai S2S (palvelujen välinen). Valitse määritystä vastaava skenaario:

Skenaario	Description
Agent 365:n käyttöönottamat OBO:n avulla	Distroon sisältyvä `AgenticTokenCache` käsittelee tunnusten hankinnan automaattisesti. Mukautettua selvitystä ei tarvita. Tämä on suositeltava menetelmää Agent 365:n käyttöönottamissa agenteissa.
Agent 365:n käyttöönottamat S2S:n avulla	Agentti hankkii tunnuksen agenttipohjaisen käyttäjätietoketjun avulla (`getAgenticApplicationToken` + Microsoftin todennuskirjastot (MSAL)). Tarvitaan mukautettu `TokenResolver`. Käytä tätä menetelmää, OBO ei ole saatavilla tai tarvitset vain sovellusten tunnuksia.
Mukautettu moduuli OBO:n avulla	Agentti hankkii käyttäjätunnuksen Azure Bot OAuthin kautta, vaikutusalueen havaittavuuden ohjelmointirajapinta. Tarvitaan mukautettu `TokenResolver` ja Azure Bot OAuth-yhteys.
Mukautettu moduuli S2S:n avulla	Agentti hankkii vain sovelluksen tunnuksen asiakasohjelman tunnistetietojen avulla. Tarvitaan mukautettu `TokenResolver`. Sovelluksen rekisteröinnin on oltava tavallinen (ei agenttipohjainen) sovellus.

Agent 365:n käyttöönottamat OBO:n avulla

Agent 365:n käyttöönottamat agentit vastaanottavat Agent 365 -ympäristöstä pyyntöjä, joissa on agenttipohjaiset tunnistetiedot (agenticAppId, agenticUserId). OBO mahdollistaa sen, että Distroon sisältyvä AgenticTokenCache käsittelee tunnuksen hankinnan automaattisesti: mukautettua selvitystä ei tarvita.

Edellytykset

Entra-sovelluksen rekisteröinti : palvelun päänimi (sovelluksen rekisteröinti) sekä asiakastunnus, asiakasohjelman salasana ja vuokraajan tunnus
Delegoidut ohjelmointirajapinnan oikeudet: lisää Agent365.Observability.OtelWrite (delegoitu) ja myönnä järjestelmänvalvojan suostumus. Lisätietoja on kohdassa Oikeuden myöntäminen.

Asetukset

Agentti kutsuu kunkin vuoron aikana RegisterObservability-funktiota vuoron kontekstilla. Sisältyvä välimuisti käyttää käyttäjän AgenticUserAuthorization-käsittelijästä peräisin olevaa delegoitua tunnistetta OBO-vaihdon suorittamiseen. Tällä tavoin saadaan tunniste, jonka vaikutusalueen on Agent365.Observability.OtelWrite.

Täydelliset määritysohjeet, mukaan lukien paketit, määritys ja koodiesimerkit ovat kohdassa Agent Framework -sovellusten agenttipohjaisten tunnusten välimuisti.

Agent 365:n käyttöönottamat S2S:n avulla

Agent 365:n käyttöönottamat agentit voivat käyttää myös S2S (palvelujen välistä) -todennusta OBO:n sijaan. Agentti hankkii tunnuksen käyttämällä oman palvelun päänimen käyttäjätietoja kaksivaiheisessa agenttipohjaisessa käyttäjätietoketjussa:

getAgenticApplicationToken(tenantId, agentId): asiakasohjelman tunnistetiedot + organisaation ulkopuoliset hallitut käyttäjätiedot (FMI) -polku
MSAL acquireTokenForClient, jossa sovelluksen tunniste on clientAssertion ja laajuus api://9b975845-388f-4429-889e-eab1ef63949c/.default

Muistiinpano

Ulkopuoliset hallitut käyttäjätiedot (FMI) on arkkitehtuuri, jossa hallitut käyttäjätiedot osallistuvat työkuorman tunnistetietojen yhdistämiseen yhdistettyjen käyttäjätietojen tunnistetietojen kautta, mikä mahdollistaa tunnusten vaihdon todennuksella, jossa ei käytetä salaista koodia ja joka perustuu käyttäjätietojen väliseen luottamussuhteeseen.

Mukautettu TokenResolver on annettava ja UseS2SEndpoint = true määritettävä.

Edellytykset

Entra-sovelluksen rekisteröinti : palvelun päänimi (sovelluksen rekisteröinti) sekä asiakastunnus, asiakasohjelman salasana ja vuokraajan tunnus
Sovelluksen ohjelmointirajapinnan oikeudet: lisää Agent365.Observability.OtelWrite (Sovellus), myönnä järjestelmänvalvojan suostumus.
Agent365.Observability.OtelWrite-sovellusrooli: Agentin palvelunpäänimessä on oltava OtelWrite-rooli Agent365:n havaittavuusresurssissa määritettynä. Käytä Agent 365 CLI -sovellusta:
```
a365 setup permissions bot --config-dir "<path-to-config-dir>"
```
Muistiinpano

Rooli leviäminen voi kestää muutaman minuutin. Vientipäätepisteestä peräisen olevat alun 401- tai 403-virheet ovat odotettuja tässä vaiheessa.

Vaihe 1: Ympäristömääritykset

Seuraavat koodiesimerkit näyttävät, miten vaaditut yhteyksien, vuokraajan, asiakasohjelman tunnistetietojen ja havaittavuuden vientitoiminnon ympäristöasetukset määritetään ennen mukautetun S2S-työnkulun käyttöönottoa.

AgenticUserAuthorization-käsittelijää ei tarvita. S2S käyttää manuaalista agenttipohjaista käyttäjätietoketjua (get_agentic_application_token + MSAL acquire_token_for_client) havaittavuusresurssiin kohdennetun tunnuksen hakemiseen.

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" }]
}

Vaihe 2: Distron määrittäminen mukautetun tunnuksen selvityksen avulla

Seuraavat esimerkit näyttävät, miten Agent 365:n vienti otetaan käyttöön ja mukautettu TokenResolver rekisteröidään, jonka jälkeen vientitoiminto voi noutaa kunkin agentin ja vuokraajan S2S-tunnukset.

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

Tärkeää

S2S-todennuksessa tarvitaan mukautettu TokenResolver. Ilman sitä Distro ei levitä UseS2SEndpoint-arvoa vientitoimintoon.

Varoitus

Älä tee IExporterTokenCache<AgenticTokenStruct>-lisäystä agentin konstruktoriin, kun käytössä on mukautettu TokenResolver. Distro tee automaattisen AgenticTokenCache-rekisteröinnin automaattisesti, ja jos agentti selvittää sen DI:n kautta, sisältyvä välimuisti ohittaa mukautetun selvityksen. Ota sen sijaan IConnections käyttöön ja hanki S2S-tunnus manuaalisesti.

Vaihe 3: S2S-tunnuksen hankkiminen ja välimuistiin tallentaminen

Hanki S2S-tunnus kussakin saapuvassa viestissä agenttipohjaisen käyttäjätietoketjun kautta ja tallenna se välimuistiin selvitystä varten.

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

Tärkeää

Manuaalinen kaksivaiheinen prosessi (get_agentic_application_token + MSAL acquire_token_for_client) on pakollinen S2S-menetelmässä. AgenticUserAuthorization.get_token() palauttaa todennuksen, jonka vaikutusalue on 5a807f24-.../.default (Bot Framework) eikä havaittavuusresurssia api://9b975845-.../.default: S2S-päätepiste hylkää sen virheellä 401 InvalidAudience.

context.activity.get_agentic_instance_id() ja get_agentic_tenant_id() mahdollistavat agentin ja vuokraajan lukemiseen aktiviteetista (lukee recipient-arvon SDK-käytännön mukaisesti).
Hanki S2S-tunnus ja tallenna se välimuistiin ennen span-ominaisuuksien luontia. Vientitoiminnon BatchSpanProcessor saattaa tyhjentyä, ennen kuin käsittelijä lopettaa: jos tunnusta ei ole vielä tallennettu välimuistiin, vienti epäonnistuu.
Paketoi kaikki A365-vaikutusalueet BaggageBuilder-arvoon, jolloin vientitoiminto tietää, mihin agenttiin ja vuokraajaan tunnukset selvitetään. Ilman baggage-tietoja span-ominaisuudet jätetään ilmoittamatta pois ja ilmoitetaan, ettei vuokraajan tai agentin käyttäjätietoja sisältynyttä span-ominaisuutta löytynyt.

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

Mukautettu moduuli OBO:n avulla

Mukautetun moduulin agentit tavallisia sovellusrekisteröintejä Azure Bot OAuth -yhteyksissä agenttipohjaisen käyttäjätietoketjun sijaan. Kun OBO on käytössä agentissa, se saa käyttäjätunnuksen sellaisen Azure Bot OAuth -todennuksen kautta, jonka Bot Framework -tunnuspalvelu on jo kohdistanut A365:n havaittavuuden ohjelmointirajapintaan. Yksi getToken- tai GetTurnTokenAsync-kutsu palauttaa oikein kohdistetun tunnuksen, joten exchangeToken on tarpeeton.

Edellytykset

Entra-sovelluksen rekisteröintidelegoitujen ohjelmointirajapinnan oikeuksien avulla. Lisää Agent365.Observability.OtelWrite (delegoitu) ja myönnä järjestelmänvalvojan suostumus

Tärkeää

Tunnuksen välimuistissa on agentId ja se on vastattava sovelluksen rekisteröinnin asiakastunnusta eikä aktiviteetin agenticAppId-arvoa, jota ei mukautetun moduulin agenteissa. Viennin URL-osoitteessa on agentId ja ristiriita aiheuttaa HTTP 403 -virheen.

Vaihe 1: Ympäristön ja sovelluksen määritys

Seuraavat esimerkit näyttävät, miten sovellus ja suorituspalveluympäristö määritetään, mukaan lukien palveluyhteyden arvot, vuokraajan ja asiakasohjelman asetukset sekä pakolliset valtuutuksen yhdistämismääritykset.

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

Tärkeää

load_configuration_from_env muuttaa kaikki ympäristömuuttujien avaimet isoiksi kirjaimiksi. Käsittelijän nimestä tulee OBOCONNECTIONPROFILE ja auth_handlers- ja get_token()-kutsuissa siihen on viitattava käyttämällä täsmälleen tätä kirjainkoko. Jos TYPE puuttuu, seurauksena on Auth handler ... not recognized or not configured suorituspalvelussa.

# .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" }]
}

Vaihe 2: OBO:n Distro-määritys

Seuraavat esimerkit näyttävät, miten Agent 365:n vienti otetaan käyttöön, vientitoiminto pidetään OBO-päätepisteessä ja delegoidut tunnukset viennin aikana palauttava mukautettu TokenResolver rekisteröidään.

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

Muistiinpano

OBO-tila edellyttää, että jwt_authorization_middleware on aiohttpApplication-arvossa (tarkistaa Bot Frameworkin kautta saapuvan JWT:n (JSON Web Token)). S2S/emulaattoripolku ei saa sisältää tätä väliohjelmistoa.

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

Vaihe 3: OBO-tunnuksen hankkiminen

Seuraavat esimerkit näyttävät, miten delegoitua OBO-tunnusta pyydetään määritetystä Azure botti OAuth -yhteydestä ja miten sovelluksen asiakasohjelman ja vientitoiminnon vuokraaja tallentaa sen välimuistiin.

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

Tärkeää

Azure-portaalin edellytys:oboConnectionProfile-nimisen Azure Bot OAuth -yhteyden vaikutusalueiden määrityksenä on oltava api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite. Ilman tätä asetusta tunnuksen vaikutusalue on botin oma käyttäjäryhmä api://botid-... ja vienti epäonnistuu virheen HTTP 401 InvalidAudience vuoksi.

Muistiinpano

AGENT_APP.auth.get_token() palauttaa suoraan tunnuksen, jonka vaikutusalue on oikea; exchange_token()-kutsua ei siis tarvita. Bot Framework -tunnuspalvelu käsittelee OBO-vaihdon, kun OAuth-yhteyden vaikutusalue kohdistuu A365:n havaittavuusresurssiin.

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

Muistiinpano

Yksi getToken / GetTurnTokenAsync-kutsu palauttaa oikean vaikutusalueen tunnuksen; exchangeToken / ExchangeTurnTokenAsync-kutsua ei siis tarvita. Azure-portaalissa määritetty Azure Bot OAuth -yhteys suorittaa OBO-vaihdon sisäisesti, kun sen vaikutusalueet kohdistuvat A365:n havaittavuusresurssiin.

Mukautettu moduuli S2S:n avulla

Mukautetun moduulin agentit voivat käyttää S2S-todennus (asiakasohjelman tunnistetiedot) vain sovellusta koskevan tunnuksen hankkimiseen käyttämällä palveluyhteyden tunnistetietoja. Tämä menetelmä käyttää tavallisia asiakasohjelman MSAL-tunnistetietoja; agentin käyttäjätietoketjua ei siis tarvita.

Edellytykset

Azure AD -sovelluksen rekisteröinti: Kyseessä on oltava mukautetun moduulin(tavallinen) sovellus. Agent 365:n käyttöönottamat sovellusrekisteröinnit eivät voi käyttää pelkkää client_credentials-arvoa havaittavuusresurssissa (AADSTS82001).
Sovelluksen oikeudet: lisää Agent365.Observability.OtelWrite (Sovellus, ei delegoitu) ja myönnä järjestelmänvalvojan suostumus.

Tärkeää

Välimuistiin tallentamisessa käytetyn agentId-tunnuksen on oltava palveluyhteyden ClientId. Viennin URL-osoite on /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces: ristiriita aiheuttaa HTTP 403 -virheen.

Vaihe 1: Ympäristön ja sovelluksen määritys

# .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" }]
}

Vaihe 2: S2S:n Distro-määritys

Seuraavat esimerkit näyttävät, miten Agent 365:n vienti otetaan käyttöön, vientitoiminto määritetään S2S-päätepisteessä ja tunnushaun viennin aikana suorittava mukautettu TokenResolver rekisteröidään.

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

Tärkeää

S2S-todennuksessa tarvitaan mukautettu TokenResolver. Ilman sitä Distro ei levitä UseS2SEndpoint-arvoa vientitoimintoon.

Vaihe 3: S2S-tunnuksen hankkiminen

Seuraavat esimerkit näyttävät, miten havaittavuusresurssin vain sovelluksen käyttöoikeustietuetta pyydetään käyttämällä palveluyhteyden tunnistetietoja sekä miten agentti ja vuokraaja tallentavat sen sitten välimuistiin vientitoiminta varten.

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

Vaihe 4: baggage-tietojen määrittäminen span-vientiä varten

Agent365:n vientitoiminnossa edellyttää, että baggage (vuokraajan tunnus ja agentin tunnus) määritetään span-kontekstiin. Ilman sitä vientitoiminto jättää span-ominaisuuden ilmoittamatta pois ja tuloksen on viesti 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 });

Palaute

Onko tästä sivusta apua?

Last updated on 2026-07-30

Havaittavuuden todennuksen määritys

Yleiskatsaus

Agent 365:n käyttöönottamat OBO:n avulla

Edellytykset

Asetukset

Agent 365:n käyttöönottamat S2S:n avulla

Edellytykset

Vaihe 1: Ympäristömääritykset

Vaihe 2: Distron määrittäminen mukautetun tunnuksen selvityksen avulla

Vaihe 3: S2S-tunnuksen hankkiminen ja välimuistiin tallentaminen

Mukautettu moduuli OBO:n avulla

Edellytykset

Vaihe 1: Ympäristön ja sovelluksen määritys

Vaihe 2: OBO:n Distro-määritys

Vaihe 3: OBO-tunnuksen hankkiminen

Mukautettu moduuli S2S:n avulla

Edellytykset

Vaihe 1: Ympäristön ja sovelluksen määritys

Vaihe 2: S2S:n Distro-määritys

Vaihe 3: S2S-tunnuksen hankkiminen

Vaihe 4: baggage-tietojen määrittäminen span-vientiä varten

Palaute

Lisäresursseja