Nastavení ověřování pozorovatelnosti

Exportér Agent 365 vyžaduje překladač tokenů k ověření při exportu telemetrie. Tato příručka popisuje nastavení pro agenty vytvořené pomocí Sada SDK pro agenty Microsoft 365, a to jak pro agenty s podporou Agent 365, tak pro agenty s vlastním enginem, napříč platformami .NET, Python a Node.js.

Pro instalaci distribuce, základní konfiguraci a případy, kdy není použit Agent SDK, viz Microsoft OpenTelemetry Distro.

Přehled

Existují čtyři autentizační scénáře, v závislosti na typu vašeho agenta a způsobu, jakým získává tokeny. Získávání tokenů může využívat On-Behalf-Of flow (OBO) nebo Service-to-Service (S2S). Vyberte scénář, který odpovídá vašemu nastavení:

Scénář Popis
Agent 365 s podporou, využívající OBO Vestavěná funkce distribuce AgenticTokenCache automaticky zajišťuje získávání tokenů. Není potřeba žádný vlastní překladač. Toto je doporučený přístup pro agenty s podporou Agent 365.
Agent 365 s podporou, využívající S2S Agent získává token využitím agentního řetězce identit (getAgenticApplicationToken + Microsoft Authentication Libraries (MSAL)). Vyžaduje vlastní TokenResolver. Použijte tento přístup, když OBO není dostupné nebo potřebujete tokeny pouze pro aplikace.
Vlastní engine využívající OBO Agent získá uživatelský token prostřednictvím Azure Bot OAuth, s rozsahem pro API pozorovatelnosti. Vyžaduje vlastní TokenResolver a připojení Azure Bot OAuth.
Vlastní engine využívající S2S Agent získá aplikační token pomocí klientských přihlašovacích údajů. Vyžaduje vlastní TokenResolver. Registrace aplikace musí být standardní aplikace (není typu agent).

Agent 365 s podporou, využívající OBO

Agent 365-enabled agenti přijímají požadavky s agentní identitou (agenticAppId, agenticUserId) z platformy Agent 365. S funkcí OBO zpracovává vestavěná komponenta AgenticTokenCache dané distribuce získávání tokenů automaticky: není vyžadován žádný vlastní překladač tokenů.

Předpoklady

  • Registrace aplikace Entra : Instanční objekt (registrace aplikace) s ID klienta, tajný kód klienta a ID tenanta
  • Delegovaná oprávnění rozhraní API: Přidejte Agent365.Observability.OtelWrite (Delegováno), udělte souhlas administrátora. Podrobné kroky viz Udělit oprávnění.

Nastavení

Při každé iteraci váš agent volá funkci RegisterObservability s kontextem aktuální iterace. Vestavěná cache využívá uživatelův delegovaný token z AgenticUserAuthorization obslužné rutiny pro OBO výměnu, čímž získá token s rozsahem Agent365.Observability.OtelWrite.

Podrobné instrukce včetně balíčků, konfigurace a ukázek kódu naleznete na Agentic token cache s aplikacemi Agent Framework.

Agent 365 s podporou, využívající S2S

Agenti s podporou Agent 365 mohou také používat autentizaci S2S (service-to-service) místo OBO. Agent získává token pomocí své vlastní identity instančního objektu prostřednictvím dvoustupňového agentního řetězce identit:

  1. getAgenticApplicationToken(tenantId, agentId): klientské přihlašovací údaje + mechanismus federované spravované identity (FMI)
  2. MSAL acquireTokenForClient s tokenem aplikace jako clientAssertion a rozsahem api://9b975845-388f-4429-889e-eab1ef63949c/.default

Poznámka:

Federated Managed Identity (FMI) je architektura, ve které spravovaná identita participuje na federaci identit úloh prostřednictvím federovaných pověření identity, což umožňuje výměnu tokenů a autentizaci bez tajných kódů na základě důvěryhodných vztahů mezi identitami.

Musíte poskytnout vlastní TokenResolver a nastavit UseS2SEndpoint = true.

Předpoklady

  • Registrace aplikace Entra : Instanční objekt (registrace aplikace) s ID klienta, tajný kód klienta a ID tenanta

  • Oprávnění rozhraní API aplikace : Přidat Agent365.Observability.OtelWrite (Aplikace), udělit souhlas administrátora

  • Agent365.Observability.OtelWrite role aplikace: Hlavní pracovník služby agenta musí mít roli OtelWrite přiřazenou na zdroji Agent365 Observability. Použití rozhraní příkazového řádku Agent 365:

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

    Poznámka:

    Propagace role může trvat několik minut. Během tohoto období se očekávají počáteční chyby 401 nebo 403 z exportního koncového bodu.

Krok 1: Konfigurace prostředí

Následující příklady kódu ukazují, jak konfigurovat požadované proměnné prostředí pro připojení, klient, klientské údaje a exportér pro pozorovatelnost před povolením vlastního S2S toku tokenů.

Žádný AgenticUserAuthorization handler není potřeba. S2S používá manuální agentní řetězec identity (get_agentic_application_token + MSAL acquire_token_for_client) k získání tokenu s rozsahem pro zdroj pozorovatelnosti.

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

Krok 2: Nakonfigurujte distribuci pomocí vlastního překladače tokenů

Následující příklady ukazují, jak povolit exportování Agent 365 a registrovat vlastní TokenResolver, aby exportér mohl získat S2S tokeny pro každého agenta a klienta.

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

Krok 3: Získejte a uložte token S2S do mezipaměti

U každé příchozí zprávy získejte S2S token prostřednictvím řetězce agentní identity a uložte jej do mezipaměti pro účely překladače.

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

Důležité

Manuální dvoukrokový postup (get_agentic_application_token + MSAL acquire_token_for_client) je nutné použít pro S2S. AgenticUserAuthorization.get_token() vrací token s rozsahem pro 5a807f24-.../.default (Bot Framework), nikoli zdroj pozorovatelnosti api://9b975845-.../.default : S2S koncový bod jej odmítá s 401 InvalidAudience.

  • Použijte context.activity.get_agentic_instance_id() a get_agentic_tenant_id() k načtení agenta a klienta z aktivity (načítá z recipient podle konvence SDK).
  • Získejte a uložte do mezipaměti S2S token před vytvořením spanů. Exportérův BatchSpanProcessor může vyprázdnit data před dokončením obslužné rutiny: pokud token ještě není uložen v mezipaměti, export selže.
  • Zahrňte všechny A365 scopes do BaggageBuilder, aby exportér věděl, pro kterého agenta a klienta má vyřešit tokeny. Bez baggage jsou spany tiše zahozeny s „Nebyly nalezeny žádné spany s identitou nájemce/agenta.“

Vlastní engine využívající OBO

Vlastní agenti používají standardní registrace aplikací s Azure robot OAuth připojeními, nikoli řetězec agentní identity. Použitím OBO agent získá uživatelský token prostřednictvím Azure Bot Framework OAuth, který má již nastavený scope pro A365 Observability API službou Bot Framework Token Service. Jedno volání getToken nebo GetTurnTokenAsync vrátí token s odpovídajícím rozsahem, takže nepotřebujete exchangeToken.

Předpoklady

Registrace aplikace Entra s delegovanými API oprávněními. Přidejte Agent365.Observability.OtelWrite (Delegované) a udělte administrátorský souhlas

Důležité

agentId v tokenové mezipaměti musí odpovídat Client ID registrace aplikace – ne activity agenticAppId, která u agentů vlastního enginu neexistuje. Exportní URL obsahuje agentId, a nesoulad způsobuje HTTP 403.

Krok 1: Konfigurace prostředí a aplikace

Následující příklady ukazují, jak nakonfigurovat aplikaci a běhové prostředí, včetně hodnot připojení ke službám, nastavení klienta a klientů a požadovaných mapování autorizace.

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

Důležité

load_configuration_from_env převádí všechny klíče proměnných prostředí na velká písmena. Názvem obslužné rutiny se stává OBOCONNECTIONPROFILE a ve voláních auth_handlers a get_token() na něj musíte odkazovat přesně s těmito velkými písmeny. Chybějící TYPE způsobuje Auth handler ... not recognized or not configured za běhu.

Krok 2: Nakonfigurujte distribuci pro OBO

Následující příklady ukazují, jak povolit exportování Agent 365, ponechat exportér na OBO koncovém bodu a zaregistrovat vlastní TokenResolver který během exportu vrací delegované tokeny.

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

Poznámka:

Režim OBO vyžaduje jwt_authorization_middleware na aiohttpApplication (ověřuje příchozí JWT (JSON Web Token) z Bot Frameworku). Cesta S2S/emulátoru by tento middleware neměla zahrnovat.

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

Krok 3: Získejte token OBO

Následující příklady ukazují, jak vyžádat delegovaný token OBO z nakonfigurovaného připojení Azure Bot OAuth a poté jej pro exportér uložit do mezipaměti podle klientské aplikace a klienta.

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

Důležité

Nutný požadavek Azure Portálu: OAuth spojení Azure robot pojmenované oboConnectionProfile musí mít své Scopes nastavené na api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite. Bez tohoto nastavení je token omezen na vlastní audience bota (api://botid-...) a export selže s HTTP 401 InvalidAudience.

Poznámka:

AGENT_APP.auth.get_token() vrátí správně nastavený token přímo – není potřeba žádné volání exchange_token(). Služba Bot Framework Token Service zajišťuje výměnu OBO, když rozsah spojení OAuth cílí na zdroj pozorovatelnosti A365.

Vlastní engine využívající S2S

Vlastní agenti mohou využít S2S (klientské přihlašovací údaje) k získání tokenu pouze pro aplikaci prostřednictvím služebních přihlašovacích údajů. Tato metoda používá standardní přihlašovací údaje klienta MSAL – není potřeba žádný agentní řetězec identity.

Předpoklady

  • Registrace aplikace Azure AD: Musí to být aplikace vlastní modul (standardní). Registrace aplikací s povolenou funkcí Agent 365 nemohou pro prostředek monitorování použít běžné client_credentials (AADSTS82001).
  • Oprávnění aplikace: Přidejte Agent365.Observability.OtelWrite (Aplikace, ne delegovaná) a udělte souhlas administrátora.

Důležité

agentId použitý pro ukládání do mezipaměti musí být ServiceConnection ClientId. Exportní URL je /observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces: nesoulad způsobuje HTTP 403.

Krok 1: Konfigurace prostředí a aplikace

Následující příklady ukazují, jak nakonfigurovat aplikaci a běhové prostředí, včetně hodnot připojení ke službám, nastavení klienta a klientů a požadovaných mapování autorizace.

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

Krok 2: Nakonfigurujte distribuci pro S2S

Následující příklady ukazují, jak povolit export Agent 365, nastavit exportér na koncový bod S2S a zaregistrovat vlastní TokenResolver pro vyhledávání tokenů během exportu.

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

Krok 3: Získejte token S2S

Následující příklady ukazují, jak vyžádat přístupový token určený pouze pro aplikaci pro prostředek pozorovatelnosti pomocí přihlašovacích údajů připojení ke službě a poté jej pro exportér uložit do mezipaměti podle agenta a klienta.

# 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

Krok 4: Nastavte baggage pro export spanů

Exportér Agent365 vyžaduje, aby byla v kontextu rozpětí nastavena baggage – ID klienta a ID agenta. Bez něj exportér tiše zahodí spany se zprávou 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])
  • Last updated on