Sada SDK pozorovatelnosti

Důležité

Pro povolení pozorovatelnosti v Agent 365 použijte distribuci Microsoft OpenTelemetry. Tato distribuce poskytuje jednotné SDK pro pozorovatelnost napříč Microsoftem, které pohání Agent 365, Microsoft Foundry, Azure Monitor a další. Stávající přístup popsaný v tomto článku funguje i bez přerušování změn. Pro migrační doporučení podle jazyka viz následující průvodce:

Poznámka

Pozorovatelnost je jedním ze stupňů rozšiřovaných funkcí v Začínáme s vývojem Agent 365 a platí pro všechny typy agentů.

Pro účast v ekosystému Agent 365 přidejte do svého agenta schopnosti Agent 365 Observability. Agent 365 Observability je postaven na OpenTelemetry (OTel) a nabízí jednotný rámec pro konzistentní a bezpečné zachycování telemetrie napříč všemi agentními platformami. Zavedením této požadované komponenty umožníte IT administrátorům monitorovat aktivitu vašeho agenta v Centru pro správu Microsoft a bezpečnostním týmům využívat Defender a Purview pro zajištění souladu a detekci hrozeb.

Klíčové výhody

  • Komplexní sledovatelnost: Zachyťte komplexní telemetrii při každém spuštění agenta, včetně relací, volání nástrojů a výjimek, což vám poskytuje plnou sledovatelnost napříč platformami.
  • Zabezpečení a podpora compliance: Zadejte sjednocené auditní protokoly do Defenderu a Purview, což umožňuje pokročilé bezpečnostní scénáře a reportování souladu pro vašeho agenta.
  • Flexibilita napříč platformami: Stavějte na standardech OTel a podporujte různá běhová prostředí a platformy, jako jsou Copilot Studio, Foundry a budoucí rámce agentů.
  • Provozní efektivita pro administrátory: Zajistěte centralizovanou sledovatelnost v Centru pro správu Microsoft 365, snížením času potřebného k řešení problémů a zlepšením správy díky rolovým kontrolám přístupu pro IT týmy spravující vašeho agenta.

Podporovaní agenti

Následující typy agentů podporují pozorovatelnost Agent 365:

Instalace

Pomocí těchto příkazů nainstalujte moduly pro monitorovatelnost pro jazyky podporované řešením Agent 365.

Nainstalujte základní balíčky pozorovatelnosti a runtime. Každý agent, který používá Agent 365 Observability, potřebuje tyto balíčky.

pip install microsoft-agents-a365-observability-core
pip install microsoft-agents-a365-runtime

Pokud váš agent používá balíček Microsoft Agents Hosting, nainstalujte balíček integrace hostingu. Poskytuje middleware, který automaticky doplňuje baggage a rozsahy z TurnContext a zahrnuje ukládání tokenů do mezipaměti pro exportéra pozorovatelnosti.

pip install microsoft-agents-a365-observability-hosting

Pokud váš agent používá jeden z podporovaných AI frameworků, nainstalujte příslušné rozšíření pro automatickou instrumentaci, abyste automaticky zachytili telemetrii bez potřeby ruční instrumentace. Podrobnosti o konfiguraci najdete v části Automatická instrumentace.

# For Semantic Kernel
pip install microsoft-agents-a365-observability-extensions-semantic-kernel

# For OpenAI Agents SDK
pip install microsoft-agents-a365-observability-extensions-openai

# For Microsoft Agent Framework
pip install microsoft-agents-a365-observability-extensions-agent-framework

# For LangChain
pip install microsoft-agents-a365-observability-extensions-langchain

Konfigurace

Použijte následující nastavení k aktivaci a konfiguraci Agent 365 Observability pro vašeho agenta.

Nastavte proměnnou prostředí ENABLE_A365_OBSERVABILITY_EXPORTER na hodnotu true pro účely pozorovatelnosti. Toto nastavení exportuje protokoly do služby a vyžaduje poskytnutí token_resolver. V opačném případě se použije konzolový exportér.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Implement secure token retrieval here
    return "Bearer <token>"

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_resolver,
)

Řešitel tokenů není zahrnut do záznamů do konzole.

Chování exportéru lze upravit předáním instance Agent365ExporterOptions do exporter_options. Pokud je zadán exporter_options, má přednost před parametry token_resolver a cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    exporter_options=Agent365ExporterOptions(
        cluster_category="prod",
        token_resolver=token_resolver,
    ),
    suppress_invoke_agent_input=True,
)

Následující tabulka popisuje volitelné parametry pro configure().

Parametr Popis Výchozí
logger_name Název loggeru v Pythonu používaného pro ladění a konzolový výstup logů. microsoft_agents_a365.observability.core
exporter_options Instance Agent365ExporterOptions, která konfiguruje tokenový resolver a kategorii clusteru společně. None
suppress_invoke_agent_input Pokud je True aktivní, potlačí vstupní zprávy na InvokeAgent spanech. False

Následující tabulka popisuje volitelné vlastnosti pro Agent365ExporterOptions.

Vlastnost Popis Výchozí
use_s2s_endpoint Při True se používá cesta koncového bodu pro komunikaci mezi službami. False
max_queue_size Maximální velikost fronty pro dávkový procesor. 2048
scheduled_delay_ms Zpoždění v milisekundách mezi dávkami exportů. 5000
exporter_timeout_ms Časový limit v milisekundách pro exportní operaci. 30000
max_export_batch_size Maximální velikost dávky pro exportní operace. 512

Atributy baggage

Použijte BaggageBuilder k nastavení kontextových informací, které procházejí všemi spany v požadavku. SDK implementuje objekt SpanProcessor, který kopíruje všechny neprázdné položky baggage do nově spuštěných spanů, aniž by přepisoval existující atributy.

from microsoft_agents_a365.observability.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

Chcete-li automaticky naplnit BaggageBuilder z TurnContext, použijte pomocníka populate v balíčku microsoft-agents-a365-observability-hosting. Tento pomocník automaticky extrahuje podrobnosti o volajícím, agentovi, klientovi, kanálu a konverzaci z aktivity.

from microsoft_agents.hosting.core.turn_context import TurnContext
from microsoft_agents_a365.observability.core import BaggageBuilder
from microsoft_agents_a365.observability.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

Middleware pro baggage

Pokud váš agent používá integrační balíček pro hosting, zaregistrujte baggage middleware, aby se baggage automaticky doplňovala pro každý příchozí požadavek. Tento krok odstraňuje potřebu manuálně volat BaggageBuilder v každé obslužné funkci aktivit.

Zaregistrujte BaggageMiddleware v sadě middleware adaptéru. Automaticky extrahuje údaje o volajícím, agentovi, klientovi, kanálu a konverzaci z každého příchozího TurnContext a obalí požadavek v baggage scope.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternativně použijte ObservabilityHostingManager ke konfiguraci baggage middleware spolu s dalšími hostingovými funkcemi:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

Middleware přeskočí nastavení baggage pro asynchronní odpovědi (události typu ContinueConversation), aby nedošlo k přepsání baggage, kterou již původní požadavek nastavil.

Funkce pro získání tokenu

Při použití exportéru Agent 365 musíte poskytnout funkci pro získání tokenu, která vrací autentizační token. Při použití Agent 365 Observability SDK s Agent Hosting frameworkem můžete generovat tokeny pomocí TurnContext z aktivit agenta.

Následující ukázka kódu ukazuje, jak vygenerovat token pomocí microsoft_agents.hosting.core SDK. Autentizační token vygenerovaný zde slouží k exportu spanů do ingestní služby A365. Agenti si mohou token vygenerovat sami, například s využitím Identity a ověřování Microsoftu (MSAL), ale musí zajistit, že token má rozsah pozorovatelnosti.

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

Pro agenta vytvořeného pomocí A365 CLI, který používá AI spolupracovníka a balíček Microsoft Agent 365 Observability Hosting Library, použijte AgenticTokenCache pro automatickou správu tokenů v cache. Zaregistrujte token jednou pro každého agenta a tenanta během aktivity obslužné rutiny a předejte cache.get_observability_token jako token_resolver ve vaší konfiguraci pozorovatelnosti.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

Automatická instrumentace

Autoinstrumentace automaticky sleduje existující telemetrické signály agentických frameworků (SDK) pro trasování a odesílá je službě pozorovatelnosti Agent 365. Tato funkce odstraňuje nutnost ručního psaní monitorovacího kódu, zjednodušuje konfiguraci a zajišťuje konzistentní sledování výkonu.

Důležité

Autoinstrumentace nastavuje pouze standardní atributy OTel. Musíte přidat atributy specifické pro Microsoft pomocí BaggageBuilder. Chcete-li zjistit, které atributy chybí, ověřte výstup konzolového rozpětí proti záznamům obchodu pro rozdílovou sadu.

Různé SDK a platformy podporují autoinstrumentaci:

Platforma Podporované sady SDK / architektury
.NET Sémantické jádro, OpenAI, Agent Framework
Python Sémantické jádro, OpenAI, Agent Framework, LangChain
Node.js OpenAI, LangChain

Poznámka

Podpora automatické instrumentace se liší podle platformy a implementace SDK.

Sémantické jádro

Automatická instrumentace vyžaduje použití nástroje baggage builder. Nastavte ID agenta a ID tenanta pomocí BaggageBuilder.

Nainstalujte balíček.

pip install microsoft-agents-a365-observability-extensions-semantic-kernel

Konfigurujte pozorovatelnost.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

OpenAI

Automatická instrumentace vyžaduje použití nástroje baggage builder. Nastavte ID agenta a ID tenanta pomocí BaggageBuilder.

Nainstalujte balíček.

pip install microsoft-agents-a365-observability-extensions-openai

Konfigurujte pozorovatelnost.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

Agent Framework

Automatická instrumentace vyžaduje použití nástroje baggage builder. Nastavte ID agenta a ID tenanta pomocí BaggageBuilder.

Nainstalujte balíček.

pip install microsoft-agents-a365-observability-extensions-agent-framework

Konfigurujte pozorovatelnost.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.agentframework import (
    AgentFrameworkInstrumentor,
)

# Configure observability
configure(
    service_name="AgentFrameworkTracingWithAzureOpenAI",
    service_namespace="AgentFrameworkTesting",
)

# Enable auto-instrumentation
AgentFrameworkInstrumentor().instrument()

LangChain Framework

Poznámka

Autoinstrumentace pro rámec LangChain také podporuje LangGraph a Deep Agents. Stejné rozšíření automaticky zachycuje telemetrii pro agenty vytvořené v kterémkoli z těchto rámců.

Automatická instrumentace vyžaduje použití nástroje baggage builder. Nastavte ID agenta a ID tenanta pomocí BaggageBuilder.

Nainstalujte balíček.

pip install microsoft-agents-a365-observability-extensions-langchain

Konfigurujte pozorovatelnost.

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor

# Configure observability
configure(
    service_name="my-langchain-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

Manuální instrumentace

Použijte sadu SDK pozorovatelnosti Agent 365 pro pochopení vnitřního fungování agenta. SDK poskytuje rozsahy, které můžete spustit: InvokeAgentScope, ExecuteToolScope, InferenceScope a OutputScope.

Volání agenta

Použijte tento rozsah na začátku procesu vašeho agenta. Pomocí rozsahu vyvolání agenta můžete zachytit vlastnosti, jako je aktuálně vyvolávaný agent, uživatelská data agenta a další.

from microsoft_agents_a365.observability.core import (
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    AgentDetails,
    CallerDetails,
    UserDetails,
    Channel,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="My Agent",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

request = Request(
    content="User asks a question",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

caller_details = CallerDetails(
    user_details=UserDetails(
        user_id="user-123",
        user_email="jane.doe@contoso.com",
        user_name="Jane Doe",
    ),
)

with InvokeAgentScope.start(request, scope_details, agent_details, caller_details):
    # Perform agent invocation logic
    response = call_agent(...)

Spuštění nástroje

Následující příklady ukazují, jak přidat sledování pozorovatelnosti do spouštění nástrojů agenta. Toto sledování zachycuje telemetrii pro účely monitorování a auditu.

from microsoft_agents_a365.observability.core import (
    ExecuteToolScope,
    ToolCallDetails,
    Request,
    ServiceEndpoint,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=ServiceEndpoint(hostname="tools.contoso.com", port=8080),
)

with ExecuteToolScope.start(request, tool_details, agent_details) as scope:
    result = run_tool(tool_details)
    scope.record_response(result)

Odvozování

Následující příklady ukazují, jak instrumentovat volání inference AI modelu s pomocí sledování pozorovatelnosti za účelem zachycení využití tokenů, detailů modelu a metadat odpovědí.

from microsoft_agents_a365.observability.core import (
    InferenceScope,
    InferenceCallDetails,
    InferenceOperationType,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
)

with InferenceScope.start(request, inference_details, agent_details) as scope:
    completion = call_llm(...)
    scope.record_output_messages([completion.text])
    scope.record_input_tokens(completion.usage.input_tokens)
    scope.record_output_tokens(completion.usage.output_tokens)

Výstup

Tento rozsah použijte pro asynchronní scénáře, kde InvokeAgentScope, ExecuteToolScope nebo InferenceScope nemohou synchronně zachytit výstupní data. Začněte OutputScope jako podřízený rozsah, abyste zaznamenali konečné výstupní zprávy po dokončení nadřazeného rozsahu.

from microsoft_agents_a365.observability.core import (
    OutputScope,
    Response,
    SpanDetails,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

# Get the parent context from the originating scope
parent_context = invoke_scope.get_context()

response = Response(messages=["Here is your organized inbox with 15 urgent emails."])

with OutputScope.start(
    request,
    response,
    agent_details,
    span_details=SpanDetails(parent_context=parent_context),
):
    # Output messages are recorded automatically from the response
    pass

Ověřte lokálně

Pro ověření úspěšné integrace pozorovatelnosti SDK zkontrolujte konzolové protokoly generované vaším agentem a protokoly z pozorovatelnosti SDK.

Nastavte proměnnou prostředí ENABLE_A365_OBSERVABILITY_EXPORTER to false. Toto nastavení exportuje spany (stopy) do konzole.

Pro vyšetření problémů s exportem povolte podrobné protokolování nastavením ENABLE_A365_OBSERVABILITY_EXPORTER na true a konfigurací ladicího protokolování při spuštění vaší aplikace:

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("microsoft_agents_a365.observability.core").setLevel(logging.DEBUG)

# Or target only the exporter:
logging.getLogger(
    "microsoft_agents_a365.observability.core.exporters.agent365_exporter"
).setLevel(logging.DEBUG)

Klíčové zprávy protokolu:

DEBUG  Token resolved for agent {agentId} tenant {tenantId}
DEBUG  Exporting {n} spans to {url}
DEBUG  HTTP 200 - correlation ID: abc-123
ERROR  Token resolution failed: {error}
ERROR  HTTP 401 exporting spans - correlation ID: abc-123
INFO   No spans with tenant/agent identity found; nothing exported.

Prohlížení exportovaných protokolů

Pro zobrazení telemetrie agentů v Microsoft Purview nebo Microsoft Defender se ujistěte, že jsou splněny následující požadavky:

Validace pro publikování v obchodě

Důležité

Pro úspěšnou validaci úložiště musí váš agent implementovat rozsahy InvokeAgentScope, InferenceScope a ExecuteToolScope. Tyto tři rozsahy jsou vyžadovány pro publikování.

Před publikováním použijte konzolové protokoly k ověření integrace pozorovatelnosti agenta implementací požadovaných rozsahů invoke agent, execute tool, inference a output. Poté porovnejte záznamy vašeho agenta s následujícími seznamy atributů, abyste ověřili, že jsou všechny požadované atributy přítomny. Zachyťte atributy na každém rozsahu nebo pomocí nástroje baggage builder a přidejte volitelné atributy podle svého uvážení.

Pro více informací o požadavcích na publikování v obchodě si přečtěte pokyny pro ověření v obchodě.

Atributy InvokeAgentScope

Následující seznam shrnuje povinné a volitelné atributy telemetrie zaznamenané při spuštění InvokeAgentScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "microsoft.a365.caller.agent.blueprint.id": "Optional",
        "microsoft.a365.caller.agent.id": "Optional",
        "microsoft.a365.caller.agent.name": "Optional",
        "microsoft.a365.caller.agent.platform.id": "Optional",
        "microsoft.a365.caller.agent.user.email": "Optional",
        "microsoft.a365.caller.agent.user.id": "Optional",
        "microsoft.a365.caller.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "server.address": "Required",
        "server.port": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

Atributy ExecuteToolScope

Následující seznam shrnuje povinné a volitelné atributy telemetrie zaznamenané při spuštění ExecuteToolScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.tool.call.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.call.result": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

Atributy InferenceScope

Následující seznam shrnuje povinné a volitelné atributy telemetrie zaznamenané při spuštění InferenceScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.a365.agent.thought.process": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "gen_ai.provider.name": "Required",
        "gen_ai.request.model": "Required",
        "gen_ai.response.finish_reasons": "Optional",
        "gen_ai.usage.input_tokens": "Optional",
        "gen_ai.usage.output_tokens": "Optional",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.tenant.id": "Required"
    }

Atributy OutputScope

Následující seznam shrnuje povinné a volitelné atributy telemetrie zaznamenané při spuštění OutputScope. Tento rozsah použijte pro asynchronní scénáře, kdy nadřazený rozsah nemůže synchronně zachytit výstupní data.

"attributes": {
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

Otestujte svého agenta pomocí pozorovatelnosti

Poté, co implementujete pozorovatelnost ve svém agentu, otestujte ji, abyste se ujistili, že správně zachycuje telemetrii. Postupujte podle testovacího průvodce pro nastavení vašeho prostředí. Poté se zaměřte především na sekci Zobrazit záznamy pozorovatelnosti, abyste ověřili, že vaše implementace pozorovatelnosti funguje podle očekávání.

Ověření:

  • Přejděte na adresu https://admin.cloud.microsoft/#/agents/all.
  • Vyberte agenta > Aktivita
  • Zobrazují se relace a volání nástrojů

Řešení problému

Tato sekce popisuje běžné problémy při implementaci a používání pozorovatelnosti.

Problém Popis
Data o pozorovatelnosti se nezobrazují Telemetrická data nejsou viditelná, protože export není aktivován, konfigurace je nesprávná nebo dojde k selhání rozlišení tokenu.
Chybí klient ID nebo agent ID – spany přeskočeny Spany jsou zahazovány před exportem, pokud chybí identitní atributy potřebné pro rozdělení.
Selhání při získání tokenu – export přeskočen nebo nepovolen Exportní požadavky selžou nebo jsou přeskočeny, pokud resolver nevrátí žádný token nebo narazí na výjimku.
HTTP 401 Neautorizováno Autentizace syntakticky uspěje, ale token není platný pro ingestování kvůli rozsahu, typu nebo expiraci.
HTTP 403 Zakázáno Přístup je odepřen kvůli nedostatkům v licencování tenanta nebo chybějícím oprávněním k pozorovatelnosti.
HTTP 403 Forbidden - Nesoulad ID agenta Požadavek je zamítnut, pokud identita agenta v URL neodpovídá identitě reprezentované tokenem.
Chyby HTTP 429 nebo 5xx – Přechodné chyby Dočasné omezení nebo selhání na straně služby přeruší export a může vyžadovat nastavení opakování.
Exportní časový limit Telemetrické dávky překračují nastavené časové limity kvůli latenci sítě nebo pomalé odezvě koncových bodů.
Export uspěje, ale telemetrie se v Defenderu ani Purview nezobrazuje Ingestování je dokončeno, ale následná viditelnost je zpožděna nebo blokována předpoklady produktu.

Zpropitné

Průvodce odstraňováním problémů Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Data o pozorovatelnosti se nezobrazují

Příznaky:

  • Agent běží
  • Žádná telemetrie v administračním centru
  • Není vidět aktivita agenta

Hlavní příčina:

  • Pozorovatelnost není povolena
  • Chyby konfigurace
  • Problémy s resolverem tokenů

ŘEŠENÍ: Vyzkoušejte následující kroky k vyřešení problému:

  • Zkontrolujte, zda je exportér pozorovatelnosti povolen.

    Musíte explicitně povolit exportér Agent 365. Pokud není exportér povolen, SDK přepne na konzolový exportér a telemetrie se do služby neodesílá. Podrobnosti o konfiguraci najdete v části Konfigurace.

  • Zkontrolujte konfiguraci překladače tokenů

    Exportér vyžaduje platný tokenový resolver, který vrací Bearer token pro každý požadavek na export. Pokud tokenový resolver chybí nebo vrátí null, export se tiše přeskočí. Ujistěte se, že váš kód správně implementuje resolver tokenů. Podrobnosti naleznete v Resolver tokenů.

  • Zkontrolujte chyby v protokolech

    Povolte podrobné protokolování a použijte az webapp log tail příkaz k vyhledání chyb týkajících se pozorovatelnosti v protokolech. Podrobnosti o tom, jak povolit protokolování podle platformy, viz Ověřit lokálně.

    # Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

  • Ověřit export telemetrie

    Potvrďte, že telemetrie je generována a exportována podle očekávání.

    • Přidejte konzolový exportér a zkontrolujte, zda je telemetrie generována lokálně. Podrobnosti o použití konzolového exportéru a ověření výstupu naleznete v sekci Ověřit lokálně.

Chybí klient ID nebo agent ID – spany přeskočeny

Příznaky: Systém tiše zahazuje spany a nikdy je neexportuje. Některá SDK zaznamenávají počet přeskočených spanů nebo zobrazí zprávu jako „Nebyly nalezeny žádné spany s identitou tenant/agent.“ Jiné je zahazují bez záznamu do logu.

Řešení

  • Před exportem SDK rozděluje spany podle identity tenanta a agenta. Systém zahazuje spany, které nemají buď ID nájemce, nebo ID agenta, a nikdy je neposílá do služby.
  • Před vytvářením spanů ověřte, že BaggageBuilder je nastaven s ID nájemce a ID agenta. Tyto hodnoty se propagují kontextem OpenTelemetry a připojují se ke všem spanům vytvořeným v rámci baggage scope. Pro platformově specifické API viz Baggage attributes.
  • Ověřte, že aktivita TurnContext má platného příjemce s agentní identitou, pokud používáte baggage middleware nebo context helper z integračního balíčku hostingu pro nastavení těchto ID.

Selhání tokenového překladače — export přeskočen nebo neoprávněný

Symptomy: Tokenový resolver vrátí null nebo vyhodí chybu. V závislosti na použitém SDK je export buď zcela přeskočen, nebo je požadavek odeslán bez autorizační hlavičky a selže s HTTP 401.

Řešení

  • Resolver tokenů je nutný při inicializaci. Pokud chybí, exportér při startu vyhodí chybu. Ověřte, že je k dispozici token resolver a vrací platný Bearer token.
  • Ověřte, že správné tenant ID a agent ID jsou použity pro BaggageBuilder, protože tyto hodnoty jsou předávány překladače tokenu.
  • U agentů hostovaných v Azure ověřte, že spravovaná identita má požadované oprávnění API pro rozsah pozorovatelnosti.

HTTP 401 Neautorizováno

Symptomy: Export selhal s chybou HTTP 401. Exportér tuto chybu neopakuje.

Řešení

  • Ověřte, že cílová skuina tokenu odpovídá koncovému bodu rozsahu pozorovatelnosti.
  • Zkontrolujte, že tokenový resolver nevrací delegovaný uživatelský token, token pro nesprávnou audience nebo expirovaný token.

HTTP 403 – Zakázáno

Symptomy: Export selhal s chybou HTTP 403. Exportér tuto chybu neopakuje.

Hlavní příčina: Chyba HTTP 403 může mít různé příčiny. Zkontrolujte následující řešení v uvedeném pořadí.

Řešení

  • Chybějící licence — Ověřte, že váš klient má přiřazenou jednu z následujících licencí v Centru pro správu Microsoft 365:

    • Test – Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Chybějící Agent365.Observability.OtelWriteoprávnění – Pokud jste nedávno aktualizovali své balíčky pozorovatelnosti, musíte toto oprávnění udělit. Viz důležitou poznámku v následující části.

Důležité

Stávající agenti přecházející na tyto verze balíčků vyžadují další krok

Tento krok platí pouze v případě, že upgradujete stávajícího agenta. Instalace nových agentů tento krok nevyžadují. Pokud přecházíte na následující verze balíčku nebo novější, musíte udělit nová oprávnění Agent365.Observability.OtelWrite ke své identitě (spravovaná identita nebo registrace aplikace). Bez tohoto oprávnění selže export telemetrie s HTTP 403.

Platforma Minimální verze vyžadující tento krok
.NET 0.3-beta
Node.js 0.2.0-preview.1
Python 0.3.0

Oprávnění udělte pomocí jedné z následujících možností.

Možnost A – Agent 365 CLI (vyžaduje účet globálního administrátora; spustit z adresáře projektu agenta obsahujícího a365.config.json, nebo použít --agent-name)

a365 setup permissions bot

Nebo bez konfiguračního souboru:

a365 setup permissions bot --agent-name "<agent-name>"

Tento příkaz uděluje všechna chybějící oprávnění podrobnému plánu, včetně rozsahů pozorovatelnosti.

Option B – Entra Portal (nejsou potřeba žádné konfigurační soubory; vyžaduje přístup globálního administrátora k registraci aplikace podrobného plánu)

  1. Přejděte na Entra portal>Registrace aplikací> Vyberte svoji aplikaci Blueprint.
  2. Přejděte na Oprávnění API>Přidat oprávnění>Rozhraní API, které moje organizace používá> vyhledejte 9b975845-388f-4429-889e-eab1ef63949c.
  3. Vyberte Delegovaná oprávnění>, zaškrtněte Agent365.Observability.OtelWrite>Přidat oprávnění.
  4. Opakujte kroky 2–3, tentokrát vyberte Oprávnění aplikace> zkontrolujte Agent365.Observability.OtelWrite>Přidat oprávnění.
  5. Klikněte na Udělit souhlas správce a potvrďte.

Jak Agent365.Observability.OtelWrite (delegované), tak Agent365.Observability.OtelWrite (aplikace) by měly zobrazit stav Granted.

HTTP 403 Forbidden — Neshoda ID agenta

Příznaky: Export selže s HTTP 403 a serverovou zprávou podobnou 403 Forbidden při agent-ID-mismatch chybě při volání koncových bodů Agent 365 pro trasování.

Příčina: Tato chyba nastává, když při konfiguraci agenta použijete ID klienta blueprint místo ID klienta instance agenta, když nastavujete podrobnosti agenta. ID agenta v exportní URL neodpovídá identitě autorizované tokenem, proto trasovací endpoint požadavek odmítá.

Řešení

  • Ověřte, zda je ID klientu přidáno do seznamu povolených klientů Agent 365.
  • Nastavte údaje o agentovi pomocí ID klienta instance agenta instance klienta agenta (nikoli ID klienta blueprintu).
  • Zkontrolujte exportní URL, která se generuje – je zaznamenána, pokud zapnete logger. Ověřte, že ID agenta v URL odpovídá ID klienta instance agenta.
  • Pro povolení diagnostického protokolování v jednotlivých SDK viz Ověření lokálně.

Chyby HTTP 429 nebo 5xx – Přechodné chyby

Příznaky: Export selže s přechodným HTTP stavovým kódem, například 429 nebo 5xx.

Řešení

  • Tyto chyby jsou obvykle přechodné a samy se vyřeší. SDK pro Python a JavaScript automaticky opakují pokus při stavových kódech HTTP 408, 429 a 5xx až třikrát s exponenciální prodlevou. .NET SDK automaticky neopakuje pokusy.
  • Pokud chyby přetrvávají, zkontrolujte dashboard zdravotního stavu služby.
  • Zvažte snížení frekvence exportu zvýšením plánovaného zpoždění mezi dávkami nebo zvětšením maximální velikosti exportní dávky. Pro možnosti konfigurace pro jednotlivé platformy viz Agent365ExporterOptions tabulka v Konfigurace.

Exportní časový limit

Příznaky: Pokusy o export končí vypršením časového limitu.

Řešení

  • Zkontrolujte síťové připojení k pozorovacímu endpointu.
  • Výchozí nastavení časového limitu se liší podle platformy. Výchozí prodleva požadavku HTTP je 30 sekund. Některé sady SDK mají také samostatný celkový časový limit exportéru, který pokrývá celý exportní cyklus včetně opakovaných pokusů. Pro konkrétní vlastnosti a výchozí hodnoty pro jednotlivé platformy viz tabulku Agent365ExporterOptions v části Konfigurace.
  • Pokud dochází k vypršení časového limitu často, zvyšte příslušnou hodnotu časového limitu ve svých nastaveních exportéru.

Export uspěje, ale telemetrie se v Defenderu ani Purview nezobrazuje

Symptomy: Protokoly ukazují úspěšný export, ale telemetrie není viditelná v Microsoft Defender ani Microsoft Purview.

Řešení

  • Ověřte, že splňujete předpoklady pro zobrazení exportovaných protokolů. Pro Purview musí být audit zapnutý. U Microsoft Defender musíte nakonfigurovat pokročilé vyhledávání. Další informace naleznete v tématu Zobrazení exportovaných protokolů.
  • Telemetrie se může naplnit až po několika minutách od úspěšného exportu. Počkejte, až budou data k dispozici, než budete pokračovat v dalším zkoumání.

Více informací o testování pozorovatelnosti naleznete zde:

Související obsah

  • Last updated on