การตั้งค่าการรับรองความถูกต้องสำหรับการเฝ้าสังเกต

ตัวส่งออก Agent 365 ต้องการตัวแก้ไขโทเค็นเพื่อรับรองความถูกต้องเมื่อส่งออกข้อมูลการวัดและส่งข้อมูลทางไกล คู่มือฉบับนี้ครอบคลุมการตั้งค่าสำหรับเอเจนต์ที่สร้างด้วย SDK เอเจนต์สำหรับ Microsoft 365 โดยรวมทั้งเอเจนต์ที่เปิดใช้งาน Agent 365 และเอเจนต์โปรแกรมแบบกำหนดเองบน .NET, Python และ Node.js

สำหรับการติดตั้ง distro การกำหนดค่าทั่วไป และสถานการณ์ที่ไม่ใช่ Agent SDK โปรดดูที่ Microsoft OpenTelemetry Distro

ภาพรวม

มีสถานการณ์การรับรองความถูกต้องสี่แบบ ขึ้นอยู่กับประเภทของเอเจนต์ของคุณและวิธีการรับโทเค็น การรับโทเค็นสามารถใช้โฟลว์ในนามของผู้ใช้ (OBO) หรือ Service-to-Service (S2S) ได้ เลือกสถานการณ์ที่ตรงกับการตั้งค่าของคุณ:

สถานการณ์	คำอธิบาย
การเปิดใช้งาน Agent 365 โดยใช้ OBO	AgenticTokenCache ที่ติดตั้งมากับ distro จะจัดการการขอรับโทเค็นโดยอัตโนมัติ ไม่จำเป็นต้องใช้ตัวแก้ไขแบบกำหนดเอง นี่เป็นวิธีการที่แนะนำสำหรับเอเจนต์ที่เปิดใช้งาน Agent 365
การเปิดใช้งาน Agent 365 โดยใช้ S2S	เอเจนต์จะรับโทเค็นโดยใช้ห่วงโซ่ข้อมูลประจำตัวของเอเจนต์ (getAgenticApplicationToken + Microsoft Authentication Libraries (MSAL)) จำเป็นต้องมี TokenResolver แบบกำหนดเอง ใช้วิธีนี้เมื่อ OBO ไม่พร้อมใช้งาน หรือคุณต้องการโทเค็นเฉพาะแอป
โปรแกรมแบบกำหนดเองที่ใช้ OBO	เอเจนต์รับโทเค็นผู้ใช้ผ่าน Azure Bot OAuth โดยมีขอบเขตการใช้งานกับ API การเฝ้าสังเกต ต้องมี TokenResolver แบบกําหนดเองและการเชื่อมต่อ Azure Bot OAuth
โปรแกรมแบบกำหนดเองที่ใช้ S2S	เอเจนต์รับโทเค็นเฉพาะแอปโดยใช้ข้อมูลรับรองไคลเอ็นต์ จำเป็นต้องมี TokenResolver แบบกำหนดเอง การลงทะเบียนแอปต้องเป็นแอปมาตรฐาน (ไม่ใช่แบบเอเจนติก)

การเปิดใช้งาน Agent 365 โดยใช้ OBO

เอเจนต์ที่เปิดใช้งาน Agent 365 จะได้รับคำขอที่มีข้อมูลประจำตัวของเอเจนต์ (agenticAppId, agenticUserId) จากแพลตฟอร์ม Agent 365 ด้วย OBO ตัวจัดการ AgenticTokenCache ที่ติดตั้งมากับ distro จะจัดการการรับโทเค็นโดยอัตโนมัติ: ไม่จำเป็นต้องใช้ตัวแก้ไขโทเค็นแบบกำหนดเอง

ข้อกำหนดเบื้องต้น

• การลงทะเบียนแอป Entra : บริการหลัก (การลงทะเบียนแอป) ที่มีรหัสไคลเอ็นต์, ข้อมูลลับไคลเอ็นต์และรหัสผู้เช่า
• สิทธิ์ API แบบมอบหมาย : เพิ่ม Agent365.Observability.OtelWrite (แบบมอบหมาย), ให้ความยินยอมของผู้ดูแลระบบ สำหรับขั้นตอนโดยละเอียด โปรดดู ให้สิทธิ์

ตั้งค่า

ในการโต้ตอบแต่ละครั้ง เอเจนต์ของคุณจะเรียกใช้ฟังก์ชัน RegisterObservability พร้อมกับบริบทของรอบ แคชในตัวจะใช้โทเค็นที่ได้รับมอบหมายของผู้ใช้จากตัวจัดการ AgenticUserAuthorization เพื่อแลกเปลี่ยนแบบ OBO และรับโทเค็นที่มีขอบเขตเป็น Agent365.Observability.OtelWrite

สําหรับคําสั่งในการตั้งค่าแบบเต็ม รวมถึงแพคเกจ การกําหนดค่า และตัวอย่างโค้ด โปรดดู แคชโทเค็นแบบเอเจนติกกับแอป Agent Framework

การเปิดใช้งาน Agent 365 โดยใช้ S2S

เอเจนต์ที่เปิดใช้งาน Agent 365 ยังสามารถใช้การรับรองความถูกต้องแบบ S2S (service-to-service) แทน OBO ได้ เอเจนต์จะขอรับโทเค็นโดยใช้ข้อมูลประจำตัวบริการหลักของตนเองผ่านห่วงโซ่ข้อมูลประจำตัวแบบเอเจนติกในแบบสองขั้นตอน

1. getAgenticApplicationToken(tenantId, agentId) : ข้อมูลรับรองไคลเอ็นต์ + เส้นทาง Federated Managed Identity (FMI)
2. MSAL acquireTokenForClient ที่มีโทเค็นแอปเป็น clientAssertion และขอบเขต api://9b975845-388f-4429-889e-eab1ef63949c/.default

หมายเหตุ

Federated Managed Identity (FMI) เป็นสถาปัตยกรรมที่ข้อมูลประจำตัวที่มีการจัดการสามารถเข้าร่วมในการรวมศูนย์ข้อมูลประจำตัวในปริมาณงานผ่านข้อมูลประจําตัวที่ติดต่อกับภายนอก ทำให้สามารถแลกเปลี่ยนโทเค็นและรับรองความถูกต้องแบบไม่ต้องใช้ข้อมูลลับ โดยอาศัยความสัมพันธ์ของความน่าเชื่อถือระหว่างข้อมูลประจำตัว

คุณต้องระบุ TokenResolver แบบกำหนดเองและตั้งค่า UseS2SEndpoint = true

ข้อกำหนดเบื้องต้น

• การลงทะเบียนแอป Entra : บริการหลัก (การลงทะเบียนแอป) ที่มีรหัสไคลเอ็นต์, ข้อมูลลับไคลเอ็นต์และรหัสผู้เช่า

• สิทธิ์ API ของแอปพลิเคชัน : เพิ่ม Agent365.Observability.OtelWrite (แอปพลิเคชัน), ให้ความยินยอมของผู้ดูแลระบบ

• บทบาทแอป Agent365.Observability.OtelWrite : บริการหลักของเอเจนต์ต้องมีบทบาท OtelWrite ที่กำหนดทรัพยากรการเฝ้าสังเกตของ Agent365 ใช้ Agent 365 CLI:

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

  หมายเหตุ

  การเผยแพร่บทบาทอาจใช้เวลาสักครู่ คาดว่าจะมีข้อผิดพลาด 401 หรือ 403 เริ่มต้นจากจุดเชื่อมต่อการส่งออกในช่วงเวลานี้

ขั้นตอนที่ 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: กำหนดค่า distro ด้วยตัวแก้ไขโทเค็นแบบกำหนดเอง

ตัวอย่างต่อไปนี้แสดงวิธีเปิดใช้งานการส่งออก Agent 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;
    });

สำคัญ

S2S ต้องการ TokenResolver แบบกำหนดเอง หากไม่มีสิ่งนี้ distro จะไม่ส่งต่อ UseS2SEndpoint ไปยังตัวส่งออก

คำเตือน

อย่าส่ง IExporterTokenCache<AgenticTokenStruct> เข้าในตัวสร้างเอเจนต์ของคุณเมื่อใช้ TokenResolver แบบกำหนดเอง distro จะลงทะเบียน 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])

สำคัญ

จําเป็นต้องใช้โฟลว์สองขั้นตอนแบบด้วยตนเอง (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 ส่วน Span จะถูกปล่อยไว้โดยมีค่าเป็น "ไม่พบช่วงที่มีข้อมูลประจำตัวของผู้เช่า/เอเจนต์"

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

โปรแกรมแบบกำหนดเองที่ใช้ OBO

เอเจนต์โปรแกรมแบบกำหนดเองใช้การลงทะเบียนแอปมาตรฐานกับการเชื่อมต่อ Azure Bot OAuth, ไม่ใช่ห่วงโซ่ข้อมูลประจำตัวเอเจนต์ เมื่อใช้ OBO เอเจนต์จะได้รับโทเค็นผู้ใช้ผ่าน Azure Bot OAuth ซึ่งมีขอบเขตสำหรับ API การเฝ้าสังเกต A365 โดยบริการโทเค็น Bot Framework การเรียกใช้ getToken หรือ GetTurnTokenAsync เพียงครั้งเดียวจะส่งคืนโทเค็นที่มีขอบเขตที่ถูกต้อง ดังนั้นคุณจึงไม่จำเป็นต้องใช้ exchangeToken

ข้อกำหนดเบื้องต้น

การลงทะเบียนแอป Entra ด้วยสิทธิ์ API ที่ได้รับมอบหมาย เพิ่ม Agent365.Observability.OtelWrite (แบบมอบหมาย) และให้ความยินยอมของผู้ดูแลระบบ

สำคัญ

agentId ในแคชโทเค็นต้องตรงกับ รหัสไคลเอ็นต์ ของการลงทะเบียนแอป - ไม่ใช่ agenticAppId ของกิจกรรม ซึ่งไม่มีอยู่สำหรับเอเจนต์โปรแกรมแบบกำหนดเอง URL การส่งออกจะรวม agentId และหากข้อมูลไม่ตรงกันจะทำให้เกิดข้อผิดพลาด 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

สำคัญ

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: กำหนดค่า distro สำหรับ 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,
)

หมายเหตุ

โหมด OBO ต้องการ jwt_authorization_middleware บน aiohttpApplication (ตรวจสอบ JWT ขาเข้า (JSON Web Token) จาก Bot Framework) พาธ S2S/ตัวจำลองไม่ควรรวมมิดเดิลแวร์นี้

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

สำคัญ

ข้อกำหนดเบื้องต้นของพอร์ทัล Azure: การเชื่อมต่อ 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 ภายในเมื่อขอบเขตกําหนดเป้าหมายทรัพยากรการเฝ้าสังเกต A365

โปรแกรมแบบกำหนดเองที่ใช้ S2S

เอเจนต์โปรแกรมแบบกำหนดเองสามารถใช้ S2S (ข้อมูลรับรองไคลเอ็นต์) เพื่อรับโทเค็นเฉพาะแอปโดยใช้ข้อมูลรับรองการเชื่อมต่อบริการ วิธีนี้ใช้ข้อมูลรับรองไคลเอ็นต์ MSAL มาตรฐาน โดยไม่จำเป็นต้องใช้ห่วงโซ่ข้อมูลประจำตัวแบบเอเจนติก

ข้อกำหนดเบื้องต้น

• การลงทะเบียนแอป Azure AD : ต้องเป็นแอปโปรแกรมแบบกำหนดเอง (มาตรฐาน) การลงทะเบียนแอปที่เปิดใช้งาน Agent 365 ไม่สามารถใช้ client_credentials แบบทั่วไปสำหรับทรัพยากรการเฝ้าสังเกต (AADSTS82001)
• สิทธิ์ของแอปพลิเคชัน : เพิ่ม Agent365.Observability.OtelWrite (แอปพลิเคชัน ไม่ใช่การมอบหมาย) และให้ความยินยอมของผู้ดูแลระบบ

สำคัญ

ค่า agentId ที่ใช้สำหรับการแคชต้องเป็น ClientId ของ ServiceConnection 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: กำหนดค่า distro สำหรับ S2S

ตัวอย่างต่อไปนี้แสดงวิธีเปิดใช้งานการส่งออก Agent 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;
    });

สำคัญ

S2S ต้องการ TokenResolver แบบกำหนดเอง หากไม่มีสิ่งนี้ distro จะไม่ส่งต่อ 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: ตั้งค่า baggage สำหรับการส่งออก span:

ตัวส่งออก Agent365 จำเป็นต้องตั้งค่า baggage (รหัสผู้เช่าและรหัสเอเจนต์) ในบริบทของ span หากไม่มี ตัวส่งออกจะปล่อย span อย่างเงียบ ๆ พร้อมข้อความ 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 บนอะแดปเตอร์ ระบบจะตั้งค่า 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 });