Wgląd SDK

Ważne

Aby włączyć obserwowalność w Agent 365, użyj Microsoft OpenTelemetry Distro. Ta dystrybucja udostępnia pojedynczy SDK obserwowalności w całym Microsoft, zasilający Agent 365, Microsoft Foundry, Azure Monitor i inne. Dotychczasowe podejście opisane w tym artykule nadal działa bez zmian łamiących zgodność. Aby uzyskać wskazówki dotyczące migracji dla poszczególnych języków, zobacz poniższe przewodniki:

• Przewodnik po migracji do języka Python
• Przewodnik migracji JavaScript/TypeScript
• Przewodnik migracji .NET W sprawie podstawowego modelu danych, tożsamości i uwierzytelniania, zakresów i zgód oraz limitów — które dotyczą każdej ścieżki integracji — zobacz Koncepcje obserwowalności Agent 365.

Notatka

Obserwacja jest jednym z poziomów przyrostowych w rozwoju Agent 365 i dotyczy wszystkich typów agentów.

Aby być częścią ekosystemu Agent 365, dodaj funkcjonalność obserwowalności Agent 365 do swojego agenta. Agent 365 Observability opiera się na OpenTelemetry (OTel) i zapewnia zunifikowaną strukturę do konsekwentnego i bezpiecznego przechwytywania telemetrii na wszystkich platformach agentów. Implementując ten wymagany komponent, umożliwiasz administratorom IT monitorowanie aktywności Twojego agenta w Centrum administracyjnym Microsoft oraz pozwalasz zespołom ds. bezpieczeństwa korzystać z Defendera i Purview do zapewnienia zgodności oraz wykrywania zagrożeń.

Główne korzyści

• Widoczność end-to-end: Rejestruj kompleksową telemetrię dla każdego wywołania agenta, w tym sesji, wywołań narzędzi i wyjątków, zapewniając pełne śledzenie na wszystkich platformach.
• Bezpieczeństwo i zgodność: Przekazuj zunifikowane logi audytowe do Defender i Purview, umożliwiając zaawansowane scenariusze bezpieczeństwa oraz raportowanie zgodności dla agenta.
• Międzyplatformowa elastyczność: Opieraj się na standardach OTel i wspieraj różnorodne środowiska uruchomieniowe oraz platformy, takie jak Copilot Studio, Foundry i przyszłe frameworki agentów.
• Efektywność operacyjna dla administratorów: Zapewnij scentralizowaną obserwowalność w centrum administracyjnym Microsoft 365, co pozwala skrócić czas rozwiązywania problemów i poprawić nadzór dzięki kontroli dostępu opartej na rolach dla zespołów IT zarządzających Twoim agentem.

Obsługiwane agenty

Następujące typy agentów obsługują funkcję obserwowalności Agent 365:

• Agenci obsługiwani przez Microsoft Agent 365: Użyj SDK obserwacji, aby instrumentować swojego agenta.
• Agenci niestandardowego silnika: Użyj SDK obserwacji do instrumentacji agenta.
• Agenty deklaratywne: Obserwowalność jest obsługiwana domyślnie. Nie jest wymagana implementacja SDK.

Instalacja

Użyj tych poleceń, aby zainstalować moduły obserwowalności dla języków obsługiwanych przez Agent 365.

Python

Zainstaluj podstawowe pakiety obserwowalności i środowiska uruchomieniowego. Każdy agent korzystający z Obserwowalności Agent 365 potrzebuje tych pakietów.

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

Jeśli Twój agent korzysta z pakietu Microsoft Agents Hosting, zainstaluj pakiet integracji z hostingiem. Zapewnia middleware, który automatycznie wypełnia atrybuty bagażu i zakresy z TurnContext, a także obejmuje buforowanie tokenów dla eksportera obserwowalności.

pip install microsoft-agents-a365-observability-hosting

Jeśli Twój agent korzysta z jednego z obsługiwanych struktur AI, zainstaluj odpowiednie rozszerzenie do automatycznej instrumentacji, aby automatycznie przechwytywać telemetry bez konieczności ręcznego instrumentowania. Szczegóły dotyczące konfiguracji znajdziesz w Auto-instrumentation.

# 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

JavaScript

Zainstaluj podstawowe pakiety obserwowalności i środowiska uruchomieniowego. Każdy agent korzystający z Obserwowalności Agent 365 potrzebuje tych pakietów.

npm install @microsoft/agents-a365-observability
npm install @microsoft/agents-a365-runtime

Jeśli Twój agent korzysta z pakietu @microsoft/agents-hosting, zainstaluj pakiet integracji hostingu. Zapewnia middleware, który automatycznie wypełnia atrybuty bagażu i zakresy z TurnContext, a także obejmuje buforowanie tokenów dla eksportera obserwowalności.

npm install @microsoft/agents-a365-observability-hosting

Jeśli Twój agent korzysta z jednego z obsługiwanych struktur AI, zainstaluj odpowiednie rozszerzenie do automatycznej instrumentacji, aby automatycznie przechwytywać telemetry bez konieczności ręcznego instrumentowania. Szczegóły dotyczące konfiguracji znajdziesz w Auto-instrumentation.

// For OpenAI Agents SDK
npm install @microsoft/agents-a365-observability-extensions-openai

// For LangChain
npm install @microsoft/agents-a365-observability-extensions-langchain

.NET

Zainstaluj podstawowy pakiet obserwowalności i pakiet środowiska uruchomieniowego. Wszystkie agenty korzystające z Obserwowalności Agent 365 potrzebują tego pakietu.

dotnet add package Microsoft.Agents.A365.Observability.Runtime

Jeśli Twój agent korzysta z pakietu Microsoft.Agents.A365.Observability.Hosting NuGet, zainstaluj pakiet integracji z hostingiem. Udostępnia middleware, które automatycznie wypełnia atrybuty bagażu z TurnContext oraz zawiera buforowanie tokenów dla eksportera obserwowalności.

dotnet add package Microsoft.Agents.A365.Observability.Hosting

Jeśli Twój agent korzysta z jednego z obsługiwanych struktur AI, zainstaluj odpowiednie rozszerzenie do automatycznej instrumentacji, aby automatycznie przechwytywać telemetry bez konieczności ręcznego instrumentowania. Szczegóły dotyczące konfiguracji znajdziesz w Auto-instrumentation.

// For Semantic Kernel
dotnet add package Microsoft.Agents.A365.Observability.Extensions.SemanticKernel

// For OpenAI
dotnet add package Microsoft.Agents.A365.Observability.Extensions.OpenAI

// For Agent Framework
dotnet add package Microsoft.Agents.A365.Observability.Extensions.AgentFramework

Konfiguracja

Użyj poniższych ustawień, aby włączyć i dostosować obserwowalność Agent 365 dla swojego agenta.

Python

Ustaw zmienną środowiskową ENABLE_A365_OBSERVABILITY_EXPORTER na wartość true dla obserwowalności. To ustawienie eksportuje logi do usługi i wymaga podania token_resolver. W przeciwnym razie używany jest eksporter konsolowy.

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

Mechanizm rozwiązywania tokenów jest wyłączony z logowania do konsoli.

Zachowanie eksportera można dostosować, przekazując instancję Agent365ExporterOptions do exporter_options. Gdy zostanie przekazany exporter_options, ma priorytet względem parametrów token_resolver i 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,
)

W poniższej tabeli opisano parametry, które należy uwzględnić dla configure().

Parametr	Podpis	Wartość domyślna
logger_name	Nazwa loggera w Pythonie używanego do debugowania i wypisywania logów na konsolę.	microsoft_agents_a365.observability.core
exporter_options	Instancja Agent365ExporterOptions, która umożliwia wspólną konfigurację rozwiązywacza tokenów i kategorii klastrów.	None
suppress_invoke_agent_input	Gdy True, tłumi komunikaty wejściowe na InvokeAgent objęciach.	False

W poniższej tabeli opisano parametry, które należy uwzględnić dla Agent365ExporterOptions.

Właściwość	Podpis	Wartość domyślna
use_s2s_endpoint	Gdy True jest ustawiony, używana jest ścieżka punktu końcowego S2S.	False
max_queue_size	Maksymalny rozmiar kolejki procesora wsadowego.	2048
scheduled_delay_ms	Opóźnienie w milisekundach między wsadami eksportowymi.	5000
exporter_timeout_ms	Limit czasu (w milisekundach) dla operacji eksportu.	30000
max_export_batch_size	Maksymalny rozmiar partii dla operacji eksportowych.	512

JavaScript

Ustaw zmienną środowiskową ENABLE_A365_OBSERVABILITY_EXPORTER na wartość true dla obserwowalności. To ustawienie eksportuje logi do usługi i wymaga skonfigurowania rozwiązywacza tokenów. W przeciwnym razie używany jest eksporter konsolowy.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';

// Define a token resolver to authenticate with the observability service for exporting logs
const tokenResolver = (agentId, tenantId) => {
    // Your token resolution logic here
    return "your-token";
};

// Advanced configuration with builder pattern
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Alternatywnie do użycia zmiennych środowiskowych, możesz skonfigurować obserwowalność programowo, korzystając z dostawcy konfiguracji poprzez metodę withConfigurationProvider. Jeśli stosujesz również indywidualne metody budujące (takie jak withExporterOptions lub withClusterCategory), te metody mają pierwszeństwo przed ustawieniami dostawcy konfiguracji.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { ObservabilityConfiguration } from '@microsoft/agents-a365-observability';

const configProvider = new ObservabilityConfiguration({
  isObservabilityExporterEnabled: () => true,
  // Set log levels as pipe-separated values (for example, 'info|warn|error')
  observabilityLogLevel: () => 'info|warn|error',
});

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withConfigurationProvider(configProvider)
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

Zachowanie eksportera można dostosować, przekazując instancję Agent365ExporterOptions do withExporterOptions. Ta opcja pozwala kontrolować grupowanie, czasy oczekiwania oraz tryb trasowania.

import {
  ObservabilityManager,
  Agent365ExporterOptions,
} from '@microsoft/agents-a365-observability';
import { ClusterCategory } from '@microsoft/agents-a365-runtime';

const exporterOptions = new Agent365ExporterOptions();
exporterOptions.maxQueueSize = 10;

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withClusterCategory(ClusterCategory.prod)
    .withExporterOptions(exporterOptions)
    .withTokenResolver(tokenResolver)
);

builder.start();

W poniższej tabeli opisano parametry, które należy uwzględnić dla Agent365ExporterOptions.

Właściwość	Podpis	Wartość domyślna
useS2SEndpoint	Gdy true jest ustawiony, używana jest ścieżka punktu końcowego S2S.	false
maxQueueSize	Maksymalny rozmiar kolejki procesora wsadowego.	2048
scheduledDelayMilliseconds	Opóźnienie w milisekundach między wsadami eksportowymi.	5000
exporterTimeoutMilliseconds	Limit czasu (w milisekundach) dla całej operacji eksportu.	90000
httpRequestTimeoutMilliseconds	Limit czasu w milisekundach dla każdego pojedynczego żądania HTTP do backendu.	30000
maxExportBatchSize	Maksymalny rozmiar partii dla operacji eksportowych.	512

Możesz także dostarczyć własny logger implementujący interfejs ILogger (info, warn, error, event). Przekaż logger do budowniczego za pomocą withCustomLogger.

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withCustomLogger({
      info: (message, ...args) => { /* your logging logic */ },
      warn: (message, ...args) => { /* your logging logic */ },
      error: (message, ...args) => { /* your logging logic */ },
      event: (eventName, success, durationMs, message, details) => { /* your logging logic */ }
    })
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

.NET

Ustaw EnableAgent365Exporter na true w appsettings.json.

W Program.cs dodaj Agent365ExporterOptions do kolekcji usług. Ta zmiana konfiguruje delegata, którego eksporter śladu używa do pobrania tokena.

Dodaj zależności związane z obserwowalnością, używając AddA365Tracing().

using Microsoft.Agents.A365.Observability.Runtime;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

Możesz dostosować zachowanie eksportera, przekazując delegata konfigurującego oraz typ eksportera do AddA365Tracing().

builder.AddA365Tracing(
    configure: tracingBuilder =>
    {
        // Use the builder to add extensions (e.g., WithSemanticKernel(), WithOpenAI())
    },
    agent365ExporterType: Agent365ExporterType.Agent365ExporterAsync
);

W poniższej tabeli opisano parametry, które należy uwzględnić dla Agent365ExporterOptions.

Właściwość	Podpis	Wartość domyślna
UseS2SEndpoint	Gdy true jest ustawiony, używana jest ścieżka punktu końcowego S2S.	false
MaxQueueSize	Maksymalny rozmiar kolejki procesora wsadowego.	2048
ScheduledDelayMilliseconds	Opóźnienie w milisekundach między wsadami eksportowymi.	5000
ExporterTimeoutMilliseconds	Limit czasu (w milisekundach) dla operacji eksportu.	30000
MaxExportBatchSize	Maksymalny rozmiar partii dla operacji eksportowych.	512

Atrybuty bagażu

Użyj BaggageBuilder, aby ustawić informacje kontekstowe, które przepływają przez wszystkie spany w żądaniu. SDK implementuje SpanProcessor, który kopiuje wszystkie niepuste wpisy bagażu do nowo rozpoczętych spanów, nie nadpisując istniejących atrybutów.

Python

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

Aby automatycznie uzupełnić BaggageBuilder danymi z TurnContext, użyj pomocnika populate z pakietu microsoft-agents-a365-observability-hosting. Ten Copilot automatycznie wyodrębnia szczegóły dzwoniącego, agenta, najemcy, kanału i rozmowy z aktywności.

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

JavaScript

import { BaggageBuilder } from '@microsoft/agents-a365-observability';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

Aby automatycznie uzupełnić BaggageBuilder danymi z TurnContext, użyj pomocnika fromTurnContext z pakietu @microsoft/agents-a365-observability-hosting. Ten Copilot automatycznie wyodrębnia szczegóły dzwoniącego, agenta, najemcy, kanału i rozmowy z aktywności.

import { BaggageBuilder } from '@microsoft/agents-a365-observability';
import { BaggageBuilderUtils } from '@microsoft/agents-a365-observability-hosting';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is auto-populated from the TurnContext activity
});

.NET

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

Aby automatycznie wypełnić BaggageBuilder danymi z ITurnContext, użyj metody rozszerzenia FromTurnContext z pakietu Microsoft.Agents.A365.Observability.Hosting. Ta metoda automatycznie wyodrębnia szczegóły dzwoniącego, agenta, najemcy, kanału i rozmowy z aktywności.

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

Oprogramowanie pośredniczące bagażu

Jeśli Twój agent korzysta z pakietu integracji hostingu, zarejestruj middleware baggage, aby automatycznie uzupełniać baggage dla każdego przychodzącego żądania. Ten krok eliminuje konieczność ręcznego wywoływania BaggageBuilder w każdym handlerze aktywności.

Python

Zarejestruj BaggageMiddleware w zestawie middleware adaptera. Automatycznie wyodrębnia dane dotyczące dzwoniącego, agenta, najemcy, kanału i rozmowy z każdego przychodzącego TurnContext oraz umieszcza żądanie w zakresie „baggage”.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternatywnie użyj ObservabilityHostingManager do skonfigurowania middleware bagażowego wraz z innymi funkcjami hostingowymi:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Middleware pomija ustawianie baggage dla asynchronicznych odpowiedzi (ContinueConversation zdarzeń), aby uniknąć nadpisania baggage ustawionego przez żądanie początkowe.

JavaScript

Zarejestruj BaggageMiddleware na adapterze. Automatycznie wyodrębnia dane dotyczące dzwoniącego, agenta, najemcy, kanału i rozmowy z każdego przychodzącego TurnContext oraz umieszcza żądanie w zakresie „baggage”.

import { BaggageMiddleware } from '@microsoft/agents-a365-observability-hosting';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

Alternatywnie użyj ObservabilityHostingManager do skonfigurowania middleware bagażowego wraz z innymi funkcjami hostingowymi:

import { ObservabilityHostingManager } from '@microsoft/agents-a365-observability-hosting';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

Middleware pomija ustawianie baggage dla asynchronicznych odpowiedzi (ContinueConversation zdarzeń), aby uniknąć nadpisania baggage ustawionego przez żądanie początkowe.

.NET

Zarejestruj BaggageTurnMiddleware na adapterze. Automatycznie wyodrębnia dane dotyczące dzwoniącego, agenta, najemcy, kanału i rozmowy z każdego przychodzącego ITurnContext oraz umieszcza żądanie w zakresie „baggage”.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

Middleware pomija ustawianie baggage dla asynchronicznych odpowiedzi (ContinueConversation zdarzeń), aby uniknąć nadpisania baggage ustawionego przez żądanie początkowe.

Jeśli potrzebujesz bagażu na poziomie HTTP (na przykład do ustawienia identyfikatorów tenant i agenta przed uruchomieniem pipeline'u Bot Framework), zarejestruj się ObservabilityBaggageMiddleware w pipeline ASP.NET Core, używając metody rozszerzenia UseObservabilityRequestContext . Musisz zapewnić funkcję resolvera, która wyodrębnia identyfikator tenanta i ID agenta z kontekstu HTTP.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

Mechanizm rozpoznawania tokenów

Gdy używasz eksportera Agent 365, musisz dostarczyć funkcję rozwiązywania tokenów, która zwraca token uwierzytelniający. Gdy używasz Agent 365 Observability SDK z frameworkiem Agent Hosting, możesz generować tokeny za pomocą aktywności TurnContext agenta from.

Python

W poniższym fragmencie kodu pokazano, jak wygenerować token przy użyciu microsoft_agents.hosting.core zestawu SDK. Token uwierzytelniający wygenerowany tutaj służy do eksportu spanów do usługi ingestującej A365. Agenci mogą samodzielnie generować token, na przykład używając Microsoft Authentication Library (MSAL), ale muszą upewnić się, że token ma zakres obserwowalności.

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

Dla agenta zbudowanego z CLI A365, który korzysta z zespołu AI oraz pakietu Microsoft Agent 365 Observability Hosting Library , używaj AgenticTokenCache do automatycznego zarządzania token cache. Zarejestruj token raz dla każdego agenta i tenanta podczas obsługi aktywności oraz przekaż cache.get_observability_token jako token_resolver w konfiguracji obserwowalności.

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

JavaScript

W poniższym fragmencie kodu pokazano, jak wygenerować token przy użyciu @microsoft/agents-hosting zestawu SDK. Token uwierzytelniający wygenerowany tutaj służy do eksportu spanów do usługi ingestującej A365. Agenci mogą samodzielnie generować token, na przykład używając Microsoft Authentication Library (MSAL), ale muszą upewnić się, że token ma zakres obserwowalności.

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

const storage = new MemoryStorage();

export const agentApplication = new AgentApplication<ApplicationTurnState>({
  authorization: {
    agentic: {}, // We have the type and scopes set in the .env file
  },
  storage,
});

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const aauAuthToken = await agentApplication.authorization.exchangeToken(context, 'agentic', {
      scopes: getObservabilityAuthenticationScope()
    });
    // cache this auth token and return via token resolver
  }
);

Dla agenta zbudowanego za pomocą A365 CLI, który korzysta z asystenta AI i pakietu @microsoft/agents-a365-observability-hosting, zastosuj AgenticTokenCacheInstance, aby automatycznie obsługiwać pamięć podręczną tokenów. Wywołaj RefreshObservabilityToken raz dla każdego agenta i tenanta podczas obsługi aktywności i przekaż AgenticTokenCacheInstance.getObservabilityToken jako tokenResolver w konfiguracji obserwowalności.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-hosting';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

.NET

W poniższym fragmencie kodu pokazano, jak wygenerować token przy użyciu Microsoft.Agents hostowania SDK. Użyk token uwierzytelniający wygenerowany tutaj służy do eksportu spanów do usługi ingestującej A365. Agenci mogą samodzielnie generować token, na przykład używając Microsoft Authentication Library (MSAL), ale muszą upewnić się, że token ma zakres obserwowalności.

Zapewnij rozwiązujący tokeny, rejestrując Agent365ExporterOptions się u TokenResolver Delegata. Delegat otrzymuje agentId oraz tenantId i zwraca token uwierzytelniający.

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Implement your token retrieval logic here
                return await GetTokenAsync(agentId, tenantId);
            }
        };
    });

Dla agenta zbudowanego za pomocą A365 CLI, który korzysta z AI jako współpracownika oraz pakietu NuGet Microsoft.Agents.A365.Observability.Hosting, użyj metody AddAgenticTracingExporter(), aby automatycznie obsługiwać buforowanie tokenów poprzez wstrzyknięcie zależności.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Zarejestruj token w aplikacji agenta.

using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App.UserAuth;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;
using System;
using System.Threading.Tasks;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct(
                    userAuthorization: UserAuthorization,
                    turnContext: turnContext,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

Auto-instrumentacja

Auto-instrumentacja automatycznie nasłuchuje sygnałów telemetrycznych generowanych przez struktury agentowe (SDK) dotyczących śladów i przekazuje je do usługi obserwacyjnej Agent 365. Ta funkcja eliminuje konieczność ręcznego pisania kodu monitorującego przez programistów, upraszcza proces konfiguracji i zapewnia spójne monitorowanie wydajności.

Ważne

Autoinstrumentacja uzupełnia tylko standardowe atrybuty OTel. Musisz dodać atrybuty specyficzne dla Microsoft za pomocą BaggageBuilder. Aby sprawdzić, które atrybuty są brakujące, porównaj wyjście span z konsoli z logami sklepu w celu identyfikacji różnic.

Wiele SDK i platform obsługuje autoinstrumentację:

Platforma	Obsługiwane SDK/struktury
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Notatka

Wsparcie autoinstrumentacji różni się w zależności od platformy i implementacji SDK.

Semantic Kernel

Autoinstrumentacja wymaga użycia "baggage builder". Ustaw identyfikator agenta i identyfikator tenanta, używając BaggageBuilder.

Python

Instalowanie pakietu.

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

Skonfiguruj obserwowalność.

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

JavaScript

Semantic Kernel nie jest obsługiwany przez JavaScript.

.NET

Dodaj zależności do kolekcji usług.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;

builder.AddA365Tracing(configure: config => config.WithSemanticKernel());

Ustaw AgentId i TenantId używając BaggageBuilder. Upewnij się, że identyfikator używany podczas tworzenia ChatCompletionAgent odpowiada identyfikatorowi agenta przekazywanemu do BaggageBuilder.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;
using Microsoft.Agents.A365.Observability.Runtime.Common;
public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      var chatCompletionAgent = new ChatCompletionAgent
      {
          // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. Should match above.
          Id = <your-agent-id>,
          ...
      };
    }
}

OpenAI

Autoinstrumentacja wymaga użycia "baggage builder". Ustaw identyfikator agenta i identyfikator tenanta, używając BaggageBuilder.

Python

Instalowanie pakietu.

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

Skonfiguruj obserwowalność.

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

JavaScript

Instalowanie pakietu.

npm install @microsoft/agents-a365-observability-extensions-openai

Skonfiguruj obserwowalność.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { OpenAIAgentsTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-openai';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

.NET

Dodaj zależności do kolekcji usług.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;

builder.AddA365Tracing(configure: config => config.WithOpenAI());

Ustaw AgentId i TenantId używając BaggageBuilder. Przy wywołaniach narzędzi rozpocznij śledzenie za pomocą Trace() na instancji ChatToolCall.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      // NOTE: This will be the agent and tenant ID with which the TokenResolver delegate will be invoked. 
      using var scope = chatToolCall.Trace(agentId: <your-agent-id>, <your-tenant-id>);
    }
}

Agent Framework

Autoinstrumentacja wymaga użycia "baggage builder". Ustaw identyfikator agenta i identyfikator tenanta, używając BaggageBuilder.

Python

Instalowanie pakietu.

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

Skonfiguruj obserwowalność.

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

JavaScript

Agent Framework nie obsługuje JavaScript.

.NET

Dodaj zależności do kolekcji usług.

using Microsoft.Agents.A365.Observability.Extensions.AgentFramework;

builder.AddA365Tracing(configure: config => config.WithAgentFramework());

Ustaw AgentId i TenantId używając BaggageBuilder.

using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
    }
}

LangChain Framework

Autoinstrumentacja wymaga zastosowania narzędzia do tworzenia bagażu (baggage builder). Ustaw identyfikator agenta i identyfikator tenanta, używając BaggageBuilder.

Python

Instalowanie pakietu.

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

Skonfiguruj obserwowalność.

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

JavaScript

Instalowanie pakietu.

npm install @microsoft/agents-a365-observability-extensions-langchain

Skonfiguruj obserwowalność.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { LangChainTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-langchain';
import * as LangChainCallbacks from '@langchain/core/callbacks/manager';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

sdk.start();

// Enable LangChain auto-instrumentation
LangChainTraceInstrumentor.instrument(LangChainCallbacks);

// Your LangChain code is now automatically traced

.NET

LangChain nie jest obsługiwany w .NET.

Instrumentacja ręczna

Użyj Agent 365 Observability SDK, aby zrozumieć wewnętrzne działanie agenta. SDK udostępnia zakresy, które można uruchomić: InvokeAgentScope, ExecuteToolScope, InferenceScope oraz OutputScope.

Wywołanie agenta

Użyj tego zakresu na początku procesu agenta. Korzystając z zakresu wywołania agenta, możesz przechwycić właściwości, takie jak aktualnie wywoływany agent, dane użytkownika agenta i inne.

Python

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(...)

JavaScript

import {
  InvokeAgentScope,
  InvokeAgentScopeDetails,
  AgentDetails,
  CallerDetails,
  UserDetails,
  Channel,
  Request,
  ServiceEndpoint,
} from '@microsoft/agents-a365-observability';

// Use the same agentDetails instance across all scopes in a request
const agentDetails: AgentDetails = {
  agentId: 'agent-456',
  agentName: 'Email Assistant',
  agentDescription: 'An AI agent powered by Azure OpenAI',
  agentAuid: 'auid-123',
  agentEmail: 'agent@contoso.com',
  agentBlueprintId: 'blueprint-789',
  tenantId: 'tenant-123',
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

// Use the same request instance across all scopes in a request
const request: Request = {
  content: 'Please help me organize my emails',
  sessionId: 'session-42',
  conversationId: 'conv-xyz',
  channel: { name: 'msteams' } as Channel,
};

// Optional: Caller details (human user, or agent-to-agent)
const callerDetails: CallerDetails = {
  userDetails: {
    userId: 'user-123',
    userEmail: 'jane.doe@contoso.com',
    userName: 'Jane Doe',
  } as UserDetails,
};

const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails);

try {
  await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);

    // Your agent invocation logic here
    const response = await invokeAgent(request.content);

    // Record output messages
    scope.recordOutputMessages(['I found 15 urgent emails', 'Here is your organized inbox']);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Jeśli Twój agent korzysta z pakietu @microsoft/agents-a365-observability-hosting, możesz użyć ScopeUtils.populateInvokeAgentScopeFromTurnContext do utworzenia zakresu z informacjami o agencie, dzwoniącym oraz o kanale, automatycznie pobieranymi z TurnContext.

import { InvokeAgentScopeDetails, AgentDetails, ServiceEndpoint } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const agentDetails: AgentDetails = { agentId: 'agent-456' };
const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

const scope = ScopeUtils.populateInvokeAgentScopeFromTurnContext(
  agentDetails,
  scopeDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    // Agent details, caller details, and channel are auto-populated from context
    const response = await invokeAgent(context.activity.text);
    scope.recordOutputMessages([response]);
  });
} finally {
  scope.dispose();
}

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

        var scopeDetails = new InvokeAgentScopeDetails(
            endpoint: new Uri("https://myagent.contoso.com")
        );

        var request = new Request(
            content: userInput,
            sessionId: "session-abc",
            channel: new Channel("msteams"),
            conversationId: "conv-xyz"
        );

        var callerDetails = new CallerDetails(
            userDetails: new UserDetails(
                userId: "user-123",
                userEmail: "jane.doe@contoso.com",
                userName: "Jane Doe"
            )
        );

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            request: request,
            scopeDetails: scopeDetails,
            agentDetails: agentDetails,
            callerDetails: callerDetails
        );

        // Record input messages
        scope.RecordInputMessages(new[] { userInput });

        // ... your agent logic here ...

        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        return new AgentResponse { Content = output };
    }
}

public class AgentResponse
{
    public string Content { get; set; }
}

Uruchamianie narzędzia

Poniższe przykłady pokazują, jak dodać śledzenie obserwowalności do wykonywania narzędzi przez agenta. To śledzenie rejestruje telemetrię na potrzeby monitorowania i audytu.

Python

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)

JavaScript

import { ExecuteToolScope, ToolCallDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com', limit: 10 }),
  toolCallId: 'tool-call-456',
  description: 'Search emails by criteria',
  toolType: 'function',
  endpoint: {
    host: 'tools.contoso.com',
    port: 8080,  // Will be recorded since not 443
    protocol: 'https'
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Execute the tool
    const result = await searchEmails(toolDetails.arguments);

    // Record the tool execution result
    scope.recordResponse(result);

    return result;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Jeśli Twój agent korzysta z pakietu @microsoft/agents-a365-observability-hosting, użyj ScopeUtils.populateExecuteToolScopeFromTurnContext do utworzenia zakresu z informacjami o agencie automatycznie pobieranymi z TurnContext.

import { ToolCallDetails } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com' }),
  toolCallId: 'tool-call-456',
  toolType: 'function',
};

const scope = ScopeUtils.populateExecuteToolScopeFromTurnContext(
  toolDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} finally {
  scope.dispose();
}

.NET

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

// ... your tool logic here ...

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

Wnioskowanie

Poniższe przykłady pokazują, jak zinstrumentować wywołania inferencji modeli AI z użyciem obserwowalności, aby przechwycić wykorzystanie tokenów, szczegóły modelu oraz metadane odpowiedzi.

Python

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)

JavaScript

import { InferenceScope, InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Summarize the following emails for me...']);

    // Call the LLM
    const response = await callLLM();

    // Record detailed telemetry with granular methods
    scope.recordOutputMessages(['Here is your email summary...']);
    scope.recordInputTokens(145);
    scope.recordOutputTokens(82);
    scope.recordFinishReasons(['stop']);

    return response.text;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Jeśli Twój agent korzysta z pakietu @microsoft/agents-a365-observability-hosting, możesz użyć ScopeUtils.populateInferenceScopeFromTurnContext do stworzenia zakresu, a szczegóły agenta zostaną automatycznie pobrane z TurnContext.

import { InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = ScopeUtils.populateInferenceScopeFromTurnContext(
  inferenceDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
  });
} finally {
  scope.dispose();
}

.NET

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

// ... your inference logic here ...

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

Dane wyjściowe

Używaj tego zakresu w scenariuszach asynchronicznych, gdy InvokeAgentScope, ExecuteToolScope lub InferenceScope nie są w stanie synchronicznie przechwycić danych wyjściowych. Rozpocznij OutputScope jako element podrzędny span, aby zarejestrować końcowe komunikaty wyjściowe po zakończeniu elementu nadrzędnego zakresu.

Python

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

JavaScript

import { OutputScope, OutputResponse, SpanDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
const parentContext = invokeScope.getSpanContext();

const response: OutputResponse = {
  messages: ['Here is your organized inbox with 15 urgent emails.'],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined, // userDetails
  { parentContext } as SpanDetails
);

// Output messages are recorded automatically from the response
scope.dispose();

.NET

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
var parentContext = invokeScope.GetActivityContext();

var response = new Response(new[] { "Here is your organized inbox with 15 urgent emails." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext)
);
// Output messages are recorded automatically from the response

Zweryfikuj lokalnie

Aby potwierdzić, że poprawnie zintegrowałeś się z SDK obserwowalności, przeanalizuj logi konsoli generowane przez Twojego agenta oraz logi z SDK obserwowalności.

Python

Ustaw zmienną środowiskową ENABLE_A365_OBSERVABILITY_EXPORTER na false. To ustawienie eksportuje span (ślady) do konsoli.

Aby zbadać błędy eksportu, włącz logowanie szczegółowe, ustawiając ENABLE_A365_OBSERVABILITY_EXPORTER na true oraz konfigurując logowanie debug podczas uruchamiania aplikacji:

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)

Kluczowe komunikaty logów:

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.

JavaScript

Ustaw zmienną środowiskową ENABLE_A365_OBSERVABILITY_EXPORTER na false. To ustawienie eksportuje span (ślady) do konsoli.

Aby zbadać błędy eksportu, ustaw zmienne środowiskowe w .env lub powłoce:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Sprawdź wyjście konsoli pod kątem komunikatów takich jak:

[INFO]  [Agent365Exporter] Exporting 245 spans
[INFO]  [Agent365Exporter] Partitioned into 3 identity groups (2 spans skipped)
[INFO]  [Agent365Exporter] Token resolved successfully via tokenResolver
[EVENT] export-group succeeded in 98ms {"tenantId":"...","agentId":"...","correlationId":"abc-123"}
[ERROR] [Agent365Exporter] Failed with status 401, correlation ID: abc-123
[WARN]  export-partition-span-missing-identity: 5 spans skipped due to missing tenant or agent ID

Opcjonalnie użyj własnego loggera, aby zapisywać zdarzenia eksportu do pliku:

import { setLogger, ExporterEventNames } from '@microsoft/agents-a365-observability';

setLogger({
  info: (msg, ...args) => myLogger.info(msg, ...args),
  warn: (msg, ...args) => myLogger.warn(msg, ...args),
  error: (msg, ...args) => myLogger.error(msg, ...args),
  event: (eventType: ExporterEventNames, isSuccess: boolean, durationMs: number,
          message?: string, details?: Record<string, string>) => {
    myLogger.info({ eventType, isSuccess, durationMs, message, ...details });
  }
});

.NET

Ustaw EnableAgent365Exporter na false w appsettings.json. To ustawienie eksportuje span (ślady) do konsoli.

Aby zbadać błędy eksportu, skonfiguruj szczegółowe logowanie w appsettings.json:

{
  "EnableAgent365Exporter": "True",
  "Logging": {
    "LogLevel": {
      "Microsoft.Agents.A365.Observability": "Debug"
    }
  }
}

Lub ustaw zmienną środowiskową:

EnableAgent365Exporter=True
A365_OBSERVABILITY_DOMAIN_OVERRIDE=https://your-test-endpoint.example.com
A365_OBSERVABILITY_SCOPE_OVERRIDE=https://api.powerplatform.com/.default

Kluczowe komunikaty logów:

info: Agent365ExporterCore: Obtained token for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: Sending {count} spans to {requestUri} for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: HTTP {statusCode} exporting spans. 'x-ms-correlation-id': '{correlationId}'.
error: Agent365Exporter: Exception exporting spans: {exception}
warn: Agent365ExporterCore: No token obtained for agent {agentId} tenant {tenantId}. Skipping export.

Notatka

Jeśli nie zarejestrujesz ILoggerFactory w DI, eksporter automatycznie przechodzi na konsolowy logger.

Przeglądanie wyeksportowanych logów

Aby wyświetlić telemetrię agentów w Microsoft Purview lub Microsoft Defender, upewnij się, że spełnione są następujące wymagania:

• Microsoft Purview: W organizacji musi być włączony audyt. Aby uzyskać instrukcje, zobacz Włącz lub wyłącz audyt.
• Microsoft Defender: Zaawansowane wyszukiwanie musi być skonfigurowane, aby uzyskać dostęp do CloudAppEventstabeli. Aby uzyskać więcej informacji, zobacz tabelę CloudAppEvents w schemacie zaawansowanego wyszukiwania.

Validate do publikacji w sklepie

Ważne

Aby pomyślnie przejść walidację sklepu, agent musi zaimplementować zakresy InvokeAgentScope, InferenceScope oraz ExecuteToolScope. Te trzy zakresy są wymagane do publikacji.

Przed publikacją zweryfikuj integrację obserwowalności agenta za pomocą dzienników konsoli, implementując wymagane zakresy invoke agent, execute tool, inference i output. Następnie porównaj logi swojego agenta z poniższymi listami atrybutów, aby upewnić się, że wszystkie wymagane atrybuty zostały uwzględnione. Zarejestruj atrybuty dla każdego zakresu lub za pomocą narzędzia baggage i według własnego uznania uwzględnij atrybuty opcjonalne.

Aby uzyskać więcej informacji na temat wymagań dotyczących publikowania w sklepie, zapoznaj się z wytycznymi dotyczącymi walidacji sklepu.

InvokeAgentScope atrybuty

Poniższa lista podsumowuje wymagane i opcjonalne atrybuty telemetryczne rejestrowane podczas uruchamiania 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"
    }

ExecuteToolScope atrybuty

Poniższa lista podsumowuje wymagane i opcjonalne atrybuty telemetryczne rejestrowane podczas uruchamiania 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"
    }

InferenceScope atrybuty

Poniższa lista podsumowuje wymagane i opcjonalne atrybuty telemetryczne rejestrowane podczas uruchamiania 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"
    }

OutputScope atrybuty

Poniższa lista podsumowuje wymagane i opcjonalne atrybuty telemetryczne rejestrowane podczas uruchamiania OutputScope. Ten zakres należy stosować w scenariuszach asynchronicznych, gdy element nadrzędny nie może synchronicznie zarejestrować danych wyjściowych.

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

Przetestuj agenta pod kątem obserwowalności

Po zaimplementowaniu obserwowalności w swoim agencie, przeprowadź testy, aby upewnić się, że prawidłowo gromadzi dane telemetryczne. Skorzystaj z przewodnika testowego, aby skonfigurować środowisko. Następnie skoncentruj się głównie na sekcji Wyświetlanie logów obserwowalności, aby zweryfikować, czy implementacja obserwowalności działa zgodnie z oczekiwaniami.

Weryfikacja:

• Przejdź do strony: https://admin.cloud.microsoft/#/agents/all
• Wybierz swojego agenta > Działanie
• Wyświetlane są sesje i wywołania narzędzi

Rozwiązywanie problemów

W tej sekcji opisano najczęstsze problemy związane z wdrażaniem i korzystaniem z obserwowalności.

Problem	Podpis
Dane telemetryczne nie pojawiają się	Telemetria nie jest widoczna, ponieważ eksportowanie nie jest włączone, konfiguracja jest nieprawidłowa lub rozwiązywanie tokena nie powiodło się.
Brakujący identyfikator najemcy lub agenta – span'y pominięte	Spany są pomijane przed eksportem, gdy brakuje atrybutów tożsamości wymaganych do partycjonowania.
Awaria pozyskiwania tokena – eksport pominięty lub nieautoryzowany	Żądania eksportu kończą się niepowodzeniem lub są pomijane, gdy resolver nie zwraca tokena lub napotyka wyjątek.
HTTP 401 Brak autoryzacji	Uwierzytelnianie przebiega prawidłowo, ale token jest nieważny do przyjęcia ze względu na zakres, typ lub wygaśnięcie.
HTTP 403 Zabronione	Odmówiono dostępu z powodu luk licencyjnych dzierżawy lub braku wymaganych uprawnień do obserwowalności.
HTTP 403 Forbidden — Niedopasowanie identyfikatorów agenta	Żądanie zostaje odrzucone, gdy tożsamość agenta w URL nie jest zgodna z tożsamością reprezentowaną przez token.
Błędy HTTP 429 lub 5xx – błędy przejściowe	Tymczasowe ograniczenie przepustowości lub awarie po stronie usługi przerywają eksport i mogą wymagać dostrojenia ponawiania.
Limit czasu eksportu	Pakiety telemetryczne przekraczają skonfigurowane limity czasu z powodu opóźnień sieciowych lub niskiej responsywności punktów końcowych.
Eksport się powiódł, ale telemetria nie pojawia się w Defender ani Purview	Proces zbierania danych zostaje zakończony, ale widoczność w kolejnych systemach jest opóźniona lub zablokowana przez wymagania wstępne produktu.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Dane telemetryczne nie pojawiają się

Objawy:

• Agent jest uruchomiony
• Brak telemetrii w centrum administracyjnym
• Nie widać aktywności agenta

Główna przyczyna:

• Obserwowalność nie jest włączona
• Błędy konfiguracji
• Problemy z rozwiązywaniem tokenów

Rozwiązania: Wykonaj poniższe kroki, aby rozwiązać problem:

• Sprawdź, czy eksporter obserwowalności jest włączony

  Musisz jawnie włączyć eksporter Agent 365. Gdy eksporter jest wyłączony, SDK przełącza się na eksporter konsolowy i telemetria nie jest wysyłana do usługi. Zobacz temat Konfiguracja, aby poznać więcej szczegółów.

• Sprawdź konfigurację mechanizmu rozstrzygania tokenów

  Eksporter wymaga prawidłowego mechanizmu rozstrzygania tokenów, który zwraca token typu Bearer dla każdego żądania eksportu. Jeśli resolver tokenów jest nieobecny lub zwraca null, eksport jest pomijany po cichu. Upewnij się, że twój kod poprawnie implementuje resolver tokenów. Aby uzyskać więcej informacji, zobacz Token resolver.

• Sprawdź błędy w logach

  Włącz szczegółowe logowanie i użyj az webapp log tail polecenia do przeszukiwania logów pod kątem błędów związanych z obserwowalnością. Szczegóły dotyczące włączania logowania na poszczególnych platformach znajdziesz w sekcji Walidacja lokalna.

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

• Zweryfikuj eksport telemetrii

  Potwierdź, że telemetria jest generowana i eksportowana zgodnie z oczekiwaniami.

  • Dodaj eksporter konsolowy i sprawdź, czy telemetria jest generowana lokalnie. Aby uzyskać szczegółowe informacje dotyczące korzystania z eksportera konsolowego i sprawdzania wyników, zobacz Walidacja lokalna.

Brak identyfikatora dzierżawy lub identyfikatora agenta — spany pominięte

Objawy: System bez powiadomienia odrzuca span(y) i nigdy ich nie eksportuje. Niektóre SDK rejestrują liczbę pominiętych zakresów lub komunikat typu "Brak rozłączeń z tożsamością najemcy/agenta znalezionym." Inni porzucają je bez logowania.

Rozwiązanie:

• Przed eksportem dystrybucja dzieli spany według tożsamości najemcy i agenta SDK. System odrzuca zakresy, które nie mają identyfikatora najemcy lub agenta i nigdy nie wysyła ich do usługi.
• Upewnij się, że BaggageBuilder jest skonfigurowany z identyfikatorem najemcy i agenta przed utworzeniem spanów. Te wartości są przekazywane przez kontekst OpenTelemetry i przypisywane do wszystkich spanów utworzonych w zakresie bagażu. Aby uzyskać informacje o API specyficznym dla platformy, zobacz Atrybuty bagażu.
• Upewnij się, że aktywność TurnContext ma prawidłowego odbiorcę z tożsamością agenta, jeśli używasz middleware do obsługi baggage lub pomocnika kontekstu z pakietu integracji hostingu do wypełnienia tych identyfikatorów.

Błąd rozpoznawania tokena — eksport pominięty lub nieautoryzowany

Objawy: Mechanizm rozpoznawania tokena zwraca null lub zgłasza błąd. W zależności od SDK eksport jest albo całkowicie pomijany, albo żądanie jest wysyłane bez nagłówka autoryzacji i kończy się błędem HTTP 401.

Rozwiązanie:

• Token resolver jest wymagany przy inicjalizacji. Jeśli go brakuje, eksporter zgłasza błąd podczas uruchamiania. Zweryfikuj, czy token resolver został skonfigurowany oraz że zwraca prawidłowy token typu Bearer.
• Upewnij się, że używane są właściwe identyfikatory dzierżawcy i agenta dla BaggageBuilder, ponieważ te wartości są przekazywane do rozwiązywacza tokenów.
• Dla agentów hostowanych w Azure sprawdź, czy Managed Identity posiada wymagane uprawnienia API do zakresu obserwowalności.

HTTP 401 Brak autoryzacji

Objawy: Eksport kończy się niepowodzeniem z błędem HTTP 401. Eksporter nie ponawia próby po tym błędzie.

Rozwiązanie:

• Sprawdź, czy audience tokena odpowiada zakresowi punktu końcowego obserwowalności.
• Sprawdź, czy resolver tokenów nie zwraca tokena użytkownika delegowanego, tokena dla niewłaściwej grupy odbiorców lub tokena wygasłego.

HTTP 403 Zabronione

Objawy: Eksport kończy się niepowodzeniem z błędem HTTP 403. Eksporter nie ponawia próby po tym błędzie.

Główna przyczyna: Błąd HTTP 403 może mieć różne przyczyny. Sprawdź następujące rozwiązania po kolei.

Rozwiązanie:

• Brakująca licencja — Zweryfikuj, czy Twój tenant ma przypisaną jedną z następujących licencji w Centrum administracyjnym platformy Microsoft 365:

  • Test - Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Brak Agent365.Observability.OtelWritewymaganego uprawnienia — jeśli ostatnio zaktualizowałeś pakiety obserwacyjności, musisz przyznać to uprawnienie. Zobacz ważną uwagę w następnej sekcji.

Ważne

Istniejący agenci aktualizujący do tych wersji pakietów muszą wykonać dodatkowy krok

Ten krok ma zastosowanie tylko podczas aktualizacji istniejącego agenta. Nowe instalacje agentów nie wymagają tego kroku. Jeśli aktualizujesz do poniższych wersji pakietu lub nowszych, musisz przyznać nowe Agent365.Observability.OtelWrite uprawnienia do swojej tożsamości (Zarządzana Tożsamość lub rejestracja aplikacji). Bez tego uprawnienia eksport telemetrii kończy się błędem HTTP 403.

Platforma	Wersja minimalna wymagająca tego kroku
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Przyznaj uprawnienia, wybierz jedną z następujących opcji.

Opcja A — Agent 365 CLI (wymaga uprawnień administratora globalnego; uruchom z katalogu projektu agenta, który zawiera a365.config.json, lub skorzystaj z --agent-name)

a365 setup permissions bot

Lub bez plików konfiguracyjnych:

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

To polecenie przyznaje wszystkie brakujące uprawnienia dla blueprintu, w tym zakresy obserwowalności.

Opcja B — Entra Portal (nie wymaga plików konfiguracyjnych; wymaga dostępu globalnego administratora do rejestracji aplikacji Blueprint)

1. Przejdź do Entra portal>Rejestracja aplikacji> i wybierz swoją aplikację Blueprint.
2. Przejdź do Uprawnienia API>Dodaj uprawnienie>API używane przez moją organizację> wyszukaj 9b975845-388f-4429-889e-eab1ef63949c.
3. Wybierz Delegowane uprawnienia> i zaznacz Agent365.Observability.OtelWrite>Dodaj uprawnienia.
4. Powtórz kroki 2–3, tym razem wybierz Uprawnienia aplikacji> zaznacz Agent365.Observability.OtelWrite>Dodaj uprawnienia.
5. Kliknij Udziel zgody administratora i potwierdź.

Zarówno Agent365.Observability.OtelWrite (Delegowane), jak i Agent365.Observability.OtelWrite (Aplikacyjne) powinny mieć status Granted.

HTTP 403 Forbidden — Niedopasowanie identyfikatorów agenta

Objawy: Eksport kończy się niepowodzeniem z HTTP 403 i komunikatem serwera podobnym do 403 Forbidden, z agent-ID-mismatch błędami podczas wywoływania punktów końcowych Śledzenia Agent 365.

Przyczyna źródłowa: Ten błąd występuje, gdy używasz identyfikatora klienta blueprint zamiast identyfikatora instancji agenta podczas ustawiania szczegółów agenta. ID agenta w URL eksportu nie zgadza się z tożsamością autoryzowaną przez token, więc punkt końcowy Śledzenia odrzuca żądanie.

Rozwiązanie:

• Zweryfikuj, czy identyfikator najemcy został dodany do listy dozwolonych najemców Agent 365.
• Ustaw szczegóły agenta za pomocą identyfikatora klienta instancji agenta (nie identyfikatora klienta blueprintu).
• Zweryfikuj wygenerowany adres eksportu – jest logowany, jeśli włączysz loggera. Potwierdź, że identyfikator agenta w URL odpowiada identyfikatorowi klienta instancji agenta.
• Aby włączyć logowanie diagnostyczne dla poszczególnych SDK, zobacz Sprawdź lokalnie.

Błędy HTTP 429 lub 5xx – błędy przejściowe

Objawy: Eksport kończy się niepowodzeniem z przejściowym kodem statusowym HTTP, takim jak 429 lub 5xx.

Rozwiązanie:

• Te błędy mają zwykle charakter przejściowy i ustępują bez interwencji. SDK dla Pythona i JavaScript automatycznie ponawiają próby na kodach statusu HTTP 408, 429 i 5xx do trzech razy, stosując wykładnicze opóźnienie. SDK .NET nie ponawia prób automatycznie.
• Jeśli błędy się utrzymają, sprawdź pulpit nawigacyjny statusu usługi.
• Rozważ ograniczenie częstotliwości eksportu poprzez zwiększenie zaplanowanego opóźnienia między partiami lub zwiększenie maksymalnej wielkości partii. Opcje konfiguracji dla poszczególnych platform można znaleźć w tabeli Agent365ExporterOptions w sekcji Konfiguracja.

Limit czasu eksportu

Objawy: próby eksportu kończą się przekroczeniem limitu czasu.

Rozwiązanie:

• Sprawdź łączność sieciową z punktem końcowym obserwowalności.
• Domyślne limity czasowe różnią się w zależności od platformy. Domyślny limit czasu prośby HTTP wynosi 30 sekund. Niektóre SDK mają też osobny ogólny limit czasu eksportera, który obejmuje cały cykl eksportu, włącznie z powtórkami. Aby uzyskać dokładne właściwości i domyślne ustawienia dla każdej platformy, zobacz tabelę Agent365ExporterOptions w Konfiguracji.
• Jeśli przekroczenia limitu czasu występują często, zwiększ odpowiednią wartość limitu czasu w opcjach eksportera.

Eksport się powiódł, ale telemetria nie pojawia się w Defender ani Purview

Objawy: Logi pokazują udany eksport, ale telemetria nie jest widoczna w Microsoft Defender ani Microsoft Purview

Rozwiązanie:

• Zweryfikuj, czy spełniasz warunki wstępne do przeglądania wyeksportowanych logów. W przypadku Purview, audyt musi być włączony. W Defenderze musisz skonfigurować zaawansowane polowanie. Aby uzyskać więcej informacji, zobacz listę Wyświetl eksportowane dzienniki.
• Telemetria może pojawić się dopiero po kilku minutach od udanego eksportu. Poczekaj, aż pojawią się dane, zanim przejdziesz do dalszej analizy.

Aby dowiedzieć się więcej o testowaniu obserwowalności, zobacz:

• Przewodnik testów – Wyświetl logi obserwowalności
• Konfiguracja obserwowalności

Powiązana zawartość

• Koncepcje obserwowalności Agent 365 - Przepływ danych, modele tożsamości, uwierzytelnianie, zakresy i limity dotyczące każdej ścieżki integracji.
• Referencyjna lista atrybutów obserwowalności Agent 365 – Kanoniczny schemat atrybutów span, do którego każdy span przesyłany do Agent 365 musi być zgodny.
• Microsoft OpenTelemetry Distro – Zalecane zunifikowane SDK do nowych integracji.