Observability authentication setup

The Agent 365 exporter requires a token resolver to authenticate when exporting telemetry. This guide covers setup for agents built with the Microsoft 365 Agents SDK, covering both Agent 365-enabled agents and custom engine agents across .NET, Python, and Node.js.

For distro installation, general configuration, and non-Agent SDK scenarios, see Microsoft OpenTelemetry Distro.

Overview

There are four authentication scenarios, depending on your agent type and how it acquires tokens. Token acquisition can use On-Behalf-Of flow (OBO) or Service-to-Service (S2S). Choose the scenario that matches your setup:

Scenario	Description
Agent 365-enabled using OBO	The distro's built-in AgenticTokenCache handles token acquisition automatically. No custom resolver needed. This is the recommended approach for Agent 365-enabled agents.
Agent 365-enabled using S2S	The agent acquires a token by using the agentic identity chain (getAgenticApplicationToken + Microsoft Authentication Libraries (MSAL)). Requires a custom TokenResolver. Use this approach when OBO isn't available or you need app-only tokens.
Custom engine using OBO	The agent gets a user token via Azure Bot OAuth, scoped to the observability API. Requires a custom TokenResolver and an Azure Bot OAuth connection.
Custom engine using S2S	The agent acquires an app-only token using client credentials. Requires a custom TokenResolver. The app registration must be a standard (non-agentic) app.

Agent 365-enabled using OBO

Agent 365-enabled agents receive requests with agentic identity (agenticAppId, agenticUserId) from the Agent 365 platform. With OBO, the distro's built-in AgenticTokenCache handles token acquisition automatically : no custom token resolver is needed.

Prerequisites

• Entra app registration : A service principal (app registration) with Client ID, Client Secret, and Tenant ID
• Delegated API permissions : Add Agent365.Observability.OtelWrite (Delegated), grant admin consent. For detailed steps, see Grant the permission.

Setup

On each turn, your agent calls the RegisterObservability function with the turn context. The built-in cache uses the user's delegated token from the AgenticUserAuthorization handler to perform an OBO exchange, acquiring a token scoped to Agent365.Observability.OtelWrite.

For full setup instructions including packages, configuration, and code examples, see Agentic token cache with Agent Framework apps.

Agent 365-enabled using S2S

Agent 365-enabled agents can also use S2S (service-to-service) authentication instead of OBO. The agent acquires a token using its own service principal identity via a two-step agentic identity chain:

1. getAgenticApplicationToken(tenantId, agentId) : client credentials + Federated Managed Identity (FMI) path
2. MSAL acquireTokenForClient with the app token as clientAssertion and scope api://9b975845-388f-4429-889e-eab1ef63949c/.default

Note

Federated Managed Identity (FMI) is an architecture where a managed identity participates in workload identity federation via federated identity credentials, enabling token exchange and secretless authentication based on trust relationships between identities.

You must provide a custom TokenResolver and set UseS2SEndpoint = true.

Prerequisites

• Entra app registration : A service principal (app registration) with Client ID, Client Secret, and Tenant ID

• Application API permissions : Add Agent365.Observability.OtelWrite (Application), grant admin consent

• Agent365.Observability.OtelWrite app role : The agent's service principal must have the OtelWrite role assigned on the Agent365 Observability resource. Use the Agent 365 CLI:

  a365 setup permissions bot --config-dir "<path-to-config-dir>"
  

  Note

  Role propagation might take a few minutes. Initial 401 or 403 errors from the export endpoint are expected during this period.

Step 1: Environment configuration

The following code examples show how to set the required connection, tenant, client credential, and observability exporter environment settings before enabling the custom S2S token flow.

Python

No AgenticUserAuthorization handler needed. S2S uses the manual agentic identity chain (get_agentic_application_token + MSAL acquire_token_for_client) to get a token scoped to the observability resource.

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

Step 2: Configure the distro with custom token resolver

The following examples show how to enable Agent 365 exporting and register a custom TokenResolver so the exporter can retrieve S2S tokens for each agent and tenant.

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 requires a custom TokenResolver. Without it, the distro doesn't propagate UseS2SEndpoint to the exporter.

Warning

Don't inject IExporterTokenCache<AgenticTokenStruct> in your agent constructor when using a custom TokenResolver. The distro auto-registers AgenticTokenCache, and if your agent resolves it via DI, the built-in cache takes precedence over your custom resolver. Use IConnections instead to acquire the S2S token manually.

Step 3: Acquire and cache the S2S token

On each incoming message, acquire the S2S token through the agentic identity chain and cache it for the resolver.

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

The manual two-step flow (get_agentic_application_token + MSAL acquire_token_for_client) is required for S2S. AgenticUserAuthorization.get_token() returns a token scoped to 5a807f24-.../.default (Bot Framework), not the observability resource api://9b975845-.../.default : the S2S endpoint rejects it with 401 InvalidAudience.

• Use context.activity.get_agentic_instance_id() and get_agentic_tenant_id() to read the agent and tenant from the activity (reads from recipient per SDK convention).
• Acquire and cache the S2S token before creating spans. The exporter's BatchSpanProcessor might flush before the handler finishes : if the token isn't cached yet, the export fails.
• Wrap all A365 scopes in BaggageBuilder so the exporter knows which agent and tenant to resolve tokens for. Without baggage, spans are silently dropped with "No spans with tenant/agent identity found."

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

Custom engine using OBO

Custom engine agents use standard app registrations with Azure Bot OAuth connections, not the agentic identity chain. By using OBO, the agent gets a user token through Azure Bot OAuth that's already scoped to the A365 observability API by the Bot Framework Token Service. A single getToken or GetTurnTokenAsync call returns the correctly scoped token, so you don't need exchangeToken.

Prerequisites

Entra app registration with Delegated API permissions. Add Agent365.Observability.OtelWrite (Delegated) and grant admin consent

Important

The agentId in the token cache must match the app registration's Client ID - not the activity's agenticAppId, which doesn't exist for custom engine agents. The export URL includes the agentId, and a mismatch causes HTTP 403.

Step 1: Environment and app configuration

The following examples show how to configure your app and runtime environment, including service connection values, tenant and client settings, and required authorization mappings.

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 uppercases all environment variable keys. The handler name becomes OBOCONNECTIONPROFILE and you must reference it with that exact casing in auth_handlers and get_token() calls. Missing TYPE causes Auth handler ... not recognized or not configured at runtime.

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

Step 2: Configure the distro for OBO

The following examples show how to enable Agent 365 exporting, keep the exporter on the OBO endpoint, and register a custom TokenResolver that returns delegated tokens during export.

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

Note

OBO mode requires jwt_authorization_middleware on the aiohttp Application (validates the inbound JWT (JSON Web Token) from Bot Framework). The S2S/emulator path shouldn't include this middleware.

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

Step 3: Acquire the OBO token

The following examples show how to request a delegated OBO token from the configured Azure Bot OAuth connection, then cache it by app client and tenant for the exporter.

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 Portal prerequisite: The Azure Bot OAuth connection named oboConnectionProfile must have its Scopes set to api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite. Without this setting, the token is scoped to the bot's own audience (api://botid-...) and export fails with HTTP 401 InvalidAudience.

Note

AGENT_APP.auth.get_token() returns the correctly-scoped token directly - no exchange_token() call is needed. The Bot Framework Token Service handles the OBO exchange when the OAuth connection scope targets the A365 observability resource.

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

Note

A single getToken / GetTurnTokenAsync call returns the correctly-scoped token - no exchangeToken / ExchangeTurnTokenAsync is needed. The Azure Bot OAuth connection configured in the Azure Portal performs the OBO exchange internally when its Scopes target the A365 observability resource.

Custom engine using S2S

Custom engine agents can use S2S (client credentials) to acquire an app-only token by using the service connection credentials. This method uses standard MSAL client credentials - no agentic identity chain required.

Prerequisites

• Azure AD app registration : Must be a custom engine (standard) app. Agent 365-enabled app registrations can't use plain client_credentials for the observability resource (AADSTS82001).
• Application permissions : Add Agent365.Observability.OtelWrite (Application, not Delegated), and grant admin consent.

Important

The agentId used for caching must be the ServiceConnection's ClientId. The export URL is /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces : a mismatch causes HTTP 403.

Step 1: Environment and app configuration

The following examples show how to configure your app and runtime environment, including service connection values, tenant and client settings, and required authorization mappings.

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

Step 2: Configure the distro for S2S

The following examples show how to enable Agent 365 exporting, set the exporter to the S2S endpoint, and register a custom TokenResolver for token lookup during export.

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 requires a custom TokenResolver. Without it, the distro doesn't propagate UseS2SEndpoint to the exporter.

Step 3: Acquire the S2S token

The following examples show how to request an app-only access token for the observability resource by using the service connection credentials, then cache it by agent and tenant for the exporter.

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

Step 4: Set baggage for span export

The Agent365 exporter requires baggage (tenant ID and agent ID) to be set on the span context. Without it, the exporter silently drops spans with the message 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

When you configure the ObservabilityHostingManager middleware on the adapter, it automatically sets the baggage.

.NET

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

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