Agent-Observabilität

Von Bedeutung

Um die Observierbarkeit in Agent 365 zu ermöglichen, verwenden Sie die Microsoft OpenTelemetry Distro. Diese Verteilung bietet ein einzelnes Observability-SDK innerhalb von Microsoft, das Agent 365, Microsoft Foundry, Azure Monitor und weitere Dienste unterstützt. Der in diesem Artikel beschriebene bestehende Ansatz funktioniert weiterhin, ohne Änderungen zu unterbrechen. Anleitungen zur Migration nach Sprache finden Sie in den folgenden Leitfäden:

• Python Migrationshandbuch
• JavaScript/TypeScript-Migrationshandbuch
• .NET Migrationshandbuch

Note

Observability ist eine der inkrementellen Fähigkeitsstufen in der Entwicklung von Agent 365 und gilt für alle Agenttypen.

Um am Agent-365-Ökosystem teilzunehmen, fügen Sie Ihrem Agenten Agent 365 Observability-Funktionen hinzu. Agent 365 Observability baut auf OpenTelemetry (OTel) auf und bietet ein einheitliches Rahmenwerk, um Telemetrie konsistent und sicher über alle Agentenplattformen hinweg zu erfassen. Durch die Implementierung dieser erforderlichen Komponente ermöglichen Sie IT-Administratoren, die Aktivitäten Ihres Agenten im Microsoft Admin Center zu überwachen und Sicherheitsteams die Nutzung von Defender und Purview für Compliance und Bedrohungserkennung zu ermöglichen.

Die wichtigsten Vorteile

• End-to-End-Sichtbarkeit: Erfassen Sie umfassende Telemetrie für jede Agentenaufrufe, einschließlich Sitzungen, Tool-Calls und Ausnahmen, sodass Sie plattformübergreifend vollständig nachverfolgt werden.
• Sicherheits- und Compliance-Unterstützung: Geben Sie einheitliche Audit-Logs in Defender und Purview ein, wodurch fortgeschrittene Sicherheitsszenarien und Compliance-Berichte für Ihren Agenten ermöglicht werden.
• Plattformübergreifende Flexibilität: Bauen Sie auf OTel-Standards auf und unterstützen Sie verschiedene Laufzeiten und Plattformen wie Copilot Studio, Foundry und zukünftige Agent-Frameworks.
• Betriebliche Effizienz für Administratoren: Bieten Sie zentrale Observierbarkeit im Microsoft 365 Admin Center, reduzieren Sie die Zeit für Fehlersuche und verbessern Sie die Governance mit rollenbasierten Zugriffskontrollen für IT-Teams, die Ihren Agenten verwalten.

Unterstützte Agents

Die folgenden Agenttypen unterstützen die Beobachtbarkeit von Agent 365:

• Microsoft Agent 365-fähige Agents: Verwenden Sie das Observability SDK, um Ihren Agent zu instrumentieren.
• Benutzerdefinierte Engine-Agents: Verwenden Sie das Einblicks-SDK, um Ihren Agent zu instrumentieren.
• Deklarative Agenten: Die Beobachtbarkeit wird von Haus aus unterstützt. Es ist keine SDK-Implementierung erforderlich.

Installation

Verwenden Sie diese Befehle, um die Observability-Module für die von Agent 365 unterstützten Sprachen zu installieren.

Python

Installieren Sie die Kern-, Überwachbarkeits- und Laufzeitpakete. Alle Agents, die Agent 365 Observability verwenden, benötigen diese Pakete.

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

Wenn Ihr Agent das Hostingpaket Microsoft Agents Hosting verwendet, installieren Sie das Hostingintegrationspaket. Es stellt Middleware bereit, die automatisch „Baggage“ und „Scopes“ aus dem TurnContext befüllt, und umfasst Token-Zwischenspeichern für den Einblicks-Exporteurs.

pip install microsoft-agents-a365-observability-hosting

Wenn Ihr Agent eines der unterstützten KI-Frameworks verwendet, installieren Sie die entsprechende Erweiterung für die automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter "Automatische Instrumentierung".

# 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

Installieren Sie die Kern-, Überwachbarkeits- und Laufzeitpakete. Alle Agents, die Agent 365 Observability verwenden, benötigen diese Pakete.

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

Wenn Ihr Agent das @microsoft/agents-hosting-Paket verwendet, installieren Sie das Hostingintegrationspaket. Es stellt Middleware bereit, die automatisch „Baggage“ und „Scopes“ aus dem TurnContext befüllt, und umfasst Token-Caching für den Observability-Exporter.

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

Wenn Ihr Agent eines der unterstützten KI-Frameworks verwendet, installieren Sie die entsprechende Erweiterung für die automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter "Automatische Instrumentierung".

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

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

.NET

Installieren Sie das Beobachtbarkeits- und Laufzeit-Kernpaket. Alle Agents, die Agent 365 Observability verwenden, benötigen dieses Paket.

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

Wenn Ihr Agent das Microsoft.Agents.A365.Observability.Hosting NuGet-Paket verwendet, installieren Sie das Hosting-Integrationspaket. Es stellt Middleware bereit, die automatisch „Baggage“ und „Scopes“ aus dem TurnContext befüllt, und umfasst Token-Zwischenspeichern für den Einblicks-Exporteur.

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

Wenn Ihr Agent eines der unterstützten KI-Frameworks verwendet, installieren Sie die entsprechende Erweiterung für die automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter "Automatische Instrumentierung".

// 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

Konfiguration

Verwenden Sie die folgenden Einstellungen, um die Agent 365 Observability für Ihren Agenten zu aktivieren und anzupassen.

Python

Setze die ENABLE_A365_OBSERVABILITY_EXPORTER Umgebungsvariable auf true für Beobachtbarkeit. Diese Einstellung exportiert Protokolle in den Dienst und setzt voraus, dass token_resolver bereitgestellt wird. Ansonsten wird der Konsolen-Exporter verwendet.

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

Die Tokenlöserfunktion ist von der Protokollierung in der Konsole ausgeschlossen.

Sie können das Exporteurverhalten anpassen, indem Sie eine Agent365ExporterOptions-Instanz an exporter_options weitergeben. Wenn exporter_options bereitgestellt wird, hat es Vorrang vor den Parametern token_resolver und 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,
)

In der folgenden Tabelle werden die optionalen Parameter für configure() beschrieben.

Parameter	Description	Vorgabe
logger_name	Der Name des Python Loggers, der für das Debuggen und die Konsolenprotokollausgabe verwendet wird.	microsoft_agents_a365.observability.core
exporter_options	Eine Agent365ExporterOptions Instanz, die die Tokenlöser- und Clusterkategorie zusammen konfiguriert.	None
suppress_invoke_agent_input	Wenn True, werden Eingabemeldungen auf InvokeAgent-Spannen unterdrückt.	False

Die folgende Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Eigentum	Description	Vorgabe
use_s2s_endpoint	Wenn True, verwendet den Dienst-zu-Dienst-Endpunktpfad.	False
max_queue_size	Maximale Warteschlangengröße für den Batchprozessor.	2048
scheduled_delay_ms	Verzögerung in Millisekunden zwischen Exportbatches.	5000
exporter_timeout_ms	Timeout in Millisekunden für den Exportvorgang.	30000
max_export_batch_size	Maximale Batchgröße für Exportvorgänge.	512

JavaScript

Setze die ENABLE_A365_OBSERVABILITY_EXPORTER Umgebungsvariable auf true für Beobachtbarkeit. Diese Einstellung exportiert Protokolle in den Dienst und erfordert einen Tokenlöser, der bereitgestellt werden muss. Ansonsten wird der Konsolen-Exporter verwendet.

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

Als Alternative zu Umgebungsvariablen können Sie die Beobachtbarkeit programmgesteuert mithilfe eines Konfigurationsanbieters über die withConfigurationProvider-Methode konfigurieren. Wenn Sie auch einzelne Generatormethoden (z. B. withExporterOptions oder withClusterCategory) verwenden, haben die einzelnen Generatormethoden Vorrang vor Werten des Konfigurationsanbieters.

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

Sie können das Exporterverhalten anpassen, indem Sie eine Agent365ExporterOptions-Instanz an withExporterOptions weitergeben. Mit dieser Option können Sie Batchverarbeitung, Timeouts und den Routenmodus steuern.

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

Die folgende Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Eigentum	Description	Vorgabe
useS2SEndpoint	Wenn true, verwendet den Dienst-zu-Dienst-Endpunktpfad.	false
maxQueueSize	Maximale Warteschlangengröße für den Batchprozessor.	2048
scheduledDelayMilliseconds	Verzögerung in Millisekunden zwischen Exportbatches.	5000
exporterTimeoutMilliseconds	Timeout in Millisekunden für den gesamten Exportvorgang.	90000
httpRequestTimeoutMilliseconds	Timeout in Millisekunden für jede einzelne HTTP-Anforderung an das Back-End.	30000
maxExportBatchSize	Maximale Batchgröße für Exportvorgänge.	512

Du kannst auch einen benutzerdefinierten Logger bereitstellen, der die Schnittstelle ILogger implementiert (info, warn, error, event). Geben Sie es dem Konstrukteur weiter, indem Sie withCustomLogger verwenden.

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

Legen Sie EnableAgent365Exporter auf true in appsettings.json fest.

In Program.csAgent365ExporterOptions zur Dienstesammlung hinzufügen. Diese Änderung konfiguriert den Stellvertreter, den der Tracexporter zum Abrufen des Tokens verwendet.

Fügen Sie beobachtbarkeitsbezogene Abhängigkeiten hinzu, indem Sie verwenden 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();

Sie können das Exporterverhalten anpassen, indem Sie einen Konfigurations-Delegaten und einen Exporter-Typ an AddA365Tracing() übergeben.

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

Die folgende Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Eigentum	Description	Vorgabe
UseS2SEndpoint	Verwendet bei true den Dienst-zu-Dienst-Endpunktpfad.	false
MaxQueueSize	Maximale Warteschlangengröße für den Batchprozessor.	2048
ScheduledDelayMilliseconds	Verzögerung in Millisekunden zwischen Exportbatches.	5000
ExporterTimeoutMilliseconds	Timeout in Millisekunden für den Exportvorgang.	30000
MaxExportBatchSize	Maximale Batchgröße für Exportvorgänge.	512

Gepäckattribute

Verwenden Sie BaggageBuilder, um Kontextinformationen festzulegen, die über alle Spannen in einer Anforderung fließen. Das SDK implementiert einen SpanProcessor, der alle nicht leeren Baggage-Einträge in neu gestartete Abschnitte kopiert, ohne vorhandene Attribute zu überschreiben.

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

Verwenden Sie das BaggageBuilder-Hilfsprogramm im TurnContext-Paket, um das populate aus dem microsoft-agents-a365-observability-hosting automatisch auszufüllen. Dieses Tool extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kommunikationskanal- und Unterhaltungsdetails aus der Aktivität.

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

Verwenden Sie das BaggageBuilder-Hilfsprogramm im TurnContext-Paket, um das fromTurnContext aus dem @microsoft/agents-a365-observability-hosting automatisch auszufüllen. Dieses Tool extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kommunikationskanal- und Unterhaltungsdetails aus der Aktivität.

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.

Verwenden Sie zum automatischen Auffüllen des BaggageBuilder aus dem ITurnContext die Erweiterungsmethode FromTurnContext im Paket Microsoft.Agents.A365.Observability.Hosting. Diese Methode extrahiert automatisch Anrufer-, Agent-, Mandanten-, Kanal- und Unterhaltungsdetails aus der Aktivität.

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

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

Gepäck-Middleware

Wenn Ihr Agent das Hosting-Integrationspaket verwendet, registrieren Sie Gepäck-Middleware, um Gepäck für jede eingehende Anfrage automatisch aufzufüllen. Dieser Schritt entfernt die Notwendigkeit, manuell in jedem Aktivitätshandler aufzurufen BaggageBuilder .

Python

Registrieren Sie BaggageMiddleware auf dem Adapter-Middleware-Set. Es extrahiert automatisch Angaben zu Anrufer, Mitarbeiter, Mandant, Kanal und Gespräch aus jedem eingehenden TurnContext und bündelt die Anfrage in einem Baggage-Scope.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternativ können Sie mit ObservabilityHostingManager Baggage Middleware zusammen mit anderen Hosting-Features konfigurieren.

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Die Middleware überspringt die Einrichtung von Baggage bei asynchronen Antworten (ContinueConversation-Ereignissen), um zu vermeiden, dass Baggage überschrieben wird, das bereits von der ursprünglichen Anfrage gesetzt wurde.

JavaScript

Registrieren Sie BaggageMiddleware auf dem Adapter. Es extrahiert automatisch Angaben zu Anrufer, Mitarbeiter, Mandant, Kanal und Gespräch aus jedem eingehenden TurnContext und bündelt die Anfrage in einem Baggage-Scope.

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

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

Alternativ können Sie mit ObservabilityHostingManager Baggage Middleware zusammen mit anderen Hosting-Features konfigurieren.

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

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

Die Middleware überspringt die Einrichtung von Baggage bei asynchronen Antworten (ContinueConversation-Ereignissen), um zu vermeiden, dass Baggage überschrieben wird, das bereits von der ursprünglichen Anfrage gesetzt wurde.

.NET

Registrieren Sie BaggageTurnMiddleware auf dem Adapter. Es extrahiert automatisch Angaben zu Anrufer, Mitarbeiter, Mandant, Kanal und Gespräch aus jedem eingehenden ITurnContext und bündelt die Anfrage in einem Baggage-Scope.

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

adapter.Use(new BaggageTurnMiddleware());

Die Middleware überspringt die Einrichtung von Baggage bei asynchronen Antworten (ContinueConversation-Ereignissen), um zu vermeiden, dass Baggage überschrieben wird, das bereits von der ursprünglichen Anfrage gesetzt wurde.

Wenn Sie Gepäck auf HTTP-Ebene benötigen (z. B. um Mandanten- und Agent-IDs festzulegen, bevor die Bot Framework-Pipeline ausgeführt wird), registrieren Sie ObservabilityBaggageMiddleware in der ASP.NET Core Pipeline mithilfe der UseObservabilityRequestContext Erweiterungsmethode. Sie müssen eine Resolverfunktion bereitstellen, die die Mandanten-ID und die Agent-ID aus dem HTTP-Kontext extrahiert.

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

Tokenlöser

Wenn Sie den Agent 365-Exporter verwenden, müssen Sie eine Tokenlöserfunktion bereitstellen, die ein Authentifizierungstoken zurückgibt. Wenn Sie das Agent 365 Einblicks-SDK mit dem Agent Hosting Framework verwenden, können Sie Token mithilfe der TurnContext Agent-Aktivitäten generieren.

Python

Der folgende Codeausschnitt zeigt, wie ein Token mithilfe des microsoft_agents.hosting.core SDK generiert wird. Das hier generierte Authentifizierungstoken wird verwendet, um die Abschnitte in den A365-Erfassungsdienst zu exportieren. Agents können ein Token selbst generieren, z. B. mithilfe der Microsoft-Authentifizierungsbibliothek (MSAL), aber sie müssen sicherstellen, dass das Token über den Observability-Bereich verfügt.

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

Verwenden Sie bei einem Agenten, der mit dem A365 CLI erstellt wurde und der einen KI-basierten Teamkollegen sowie das Paket AgenticTokenCache verwendet, um die Token-Caching automatisch zu handhaben. Registrieren Sie das Token einmal pro Agent und Mandant während eines Aktivitätshandlers und übergeben Sie cache.get_observability_token als token_resolver in Ihrer Einblickskonfiguration.

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

Der folgende Codeausschnitt zeigt, wie ein Token mithilfe des @microsoft/agents-hosting SDK generiert wird. Das hier generierte Authentifizierungstoken wird verwendet, um die Abschnitte in den A365-Erfassungsdienst zu exportieren. Agents können ein Token selbst generieren, z. B. mithilfe der Microsoft-Authentifizierungsbibliothek (MSAL), aber sie müssen sicherstellen, dass das Token über den Observability-Bereich verfügt.

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

Verwenden Sie AgenticTokenCacheInstance, um für einen mit der A365 CLI erstellten Agent, der einen KI-Teamkollegen und das @microsoft/agents-a365-observability-hosting-Paket nutzt, die Tokenzwischenspeicherung automatisch zu verwalten. Rufen Sie RefreshObservabilityToken einmal pro Agent und Mandant während eines Aktivitätshandlers auf und übergeben Sie AgenticTokenCacheInstance.getObservabilityToken als tokenResolver in Ihrer Einblickskonfiguration.

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

Der folgende Codeausschnitt zeigt, wie Sie ein Token mithilfe des Microsoft.Agents Hosting-SDKs generieren. Verwenden Sie das generierte Authentifizierungstoken, um die Abschnitte in den A365-Erfassungsdienst zu exportieren. Agents können ein Token selbst generieren, z. B. mithilfe der Microsoft-Authentifizierungsbibliothek (MSAL), aber sie müssen sicherstellen, dass das Token über den Observability-Bereich verfügt.

Stellen Sie einen Tokenlöser bereit, indem Sie Agent365ExporterOptions mit einer TokenResolver-Stellvertretung registrieren. Der Delegierte empfängt agentId und tenantId und gibt das Authentifizierungstoken zurück.

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

Verwenden Sie für einen Agenten, der mit der A365 CLI erstellt wurde, der einen KI-Teamkollegen und das Microsoft.Agents.A365.Observability.Hosting NuGet-Paket verwendet, die AddAgenticTracingExporter() Methode, um das Token-Caching automatisch durch Dependency Injection zu verarbeiten.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Registrieren Sie das Token in der Agent-Anwendung.

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

Automatische Instrumentierung

Die automatische Instrumentierung lauscht automatisch auf in agentenbasierten Frameworks (SDKs) nach vorhandenen Telemetriesignalen für Ablaufverfolgungen und leitet sie an den Agent 365-Einblicksdienst weiter. Diese Funktion beseitigt die Notwendigkeit für Entwickler, Überwachungscode manuell zu schreiben, vereinfacht die Einrichtung und gewährleistet eine konsistente Leistungsverfolgung.

Mehrere SDKs und Plattformen unterstützen Autoinstrumentierung:

Plattform	Unterstützte SDKs / Frameworks
.NET	Semantischer Kernel, OpenAI, Agent Framework
Python	Semantischer Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI,LangChain

Note

Die Unterstützung für die automatische Instrumentierung variiert je nach Plattform und SDK-Implementierung.

Semantischer Kern

Die automatische Instrumentierung erfordert die Verwendung des BaggageBuilders. Setzen Sie die Agenten-ID und die Mieter-ID mit BaggageBuilder.

Python

Installiere das Paket.

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

Konfigurieren der Beobachtbarkeit

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

Semantischer Kernel wird mit JavaScript nicht unterstützt.

.NET

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

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

Setzen Sie AgentId und TenantId durch Verwendung von BaggageBuilder. Stellen Sie sicher, dass die ID, die Sie beim Erstellen eines ChatCompletionAgent verwenden, mit der Agenten-ID übereinstimmt, die Sie an BaggageBuilder weitergeben.

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

Die automatische Instrumentierung erfordert die Verwendung des BaggageBuilders. Setzen Sie die Agenten-ID und die Mieter-ID mit BaggageBuilder.

Python

Installiere das Paket.

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

Konfigurieren der Beobachtbarkeit

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

Installiere das Paket.

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

Konfigurieren der Beobachtbarkeit

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

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

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

Setzen Sie AgentId und TenantId durch Verwendung von BaggageBuilder. Für Toolaufrufe starten Sie einen Trace, indem Sie Trace() auf einer ChatToolCall-Instanz verwenden.

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

Agenten-Framework

Die automatische Instrumentierung erfordert die Verwendung des BaggageBuilders. Setzen Sie die Agenten-ID und die Mieter-ID mit BaggageBuilder.

Python

Installiere das Paket.

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

Konfigurieren der Beobachtbarkeit

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 wird mit JavaScript nicht unterstützt.

.NET

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

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

Setzen Sie AgentId und TenantId durch Verwendung von 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

Die automatische Instrumentierung erfordert die Verwendung von BaggageBuilder. Setzen Sie die Agenten-ID und die Mieter-ID mit BaggageBuilder.

Python

Installiere das Paket.

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

Konfigurieren der Beobachtbarkeit

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

Installiere das Paket.

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

Konfigurieren der Beobachtbarkeit

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 wird mit .NET nicht unterstützt.

Manuelle Instrumentierung

Verwenden Sie das Agent 365 Observability SDK, um die interne Funktionsweise des Agenten zu verstehen. Das SDK bietet Bereiche, die Sie starten können: InvokeAgentScope, , ExecuteToolScope, InferenceScope, und OutputScope.

Agent-Aufruf

Nutzen Sie diesen Umfang zu Beginn Ihres Maklerprozesses. Durch die Nutzung des Aufruf-Agenten-Umfangs können Sie Eigenschaften wie den aktuell aufgerufenen Agenten, Agentenbenutzerdaten und mehr erfassen.

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

Wenn Ihr Agent das @microsoft/agents-a365-observability-hosting Paket verwendet, können Sie mit ScopeUtils.populateInvokeAgentScopeFromTurnContext den Bereich mit Agentdetails, Anruferdetails und Kanalinformationen erstellen, die automatisch von der TurnContext abgeleitet werden.

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

Werkzeugausführung

Die folgenden Beispiele zeigen, wie Sie die Einblicksverfolgung bei der Toolausführung Ihres Agents implementieren können. Dieses Tracking erfasst Telemetrie zu Überwachungs- und Auditzwecken.

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

Wenn Ihr Agent das @microsoft/agents-a365-observability-hosting-Paket verwendet, verwenden Sie ScopeUtils.populateExecuteToolScopeFromTurnContext, um den Bereich mit den Agentendaten zu erstellen, die automatisch von TurnContext abgeleitet werden.

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.\"}");

Schlussfolgerung

Die folgenden Beispiele zeigen, wie Sie KI-Modellinferenzaufrufe mit Beobachtungsverfolgung zur Erfassung der Tokennutzung, Modelldetails und Antwortmetadaten instrumentieren.

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

Wenn Ihr Agent das @microsoft/agents-a365-observability-hosting-Paket verwendet, können Sie mit ScopeUtils.populateInferenceScopeFromTurnContext den Bereich erstellen, wobei die Agentendaten automatisch aus dem TurnContext abgeleitet werden.

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

Ausgabe

Verwenden Sie diesen Bereich für asynchrone Szenarien, in denen InvokeAgentScope, ExecuteToolScope oder InferenceScope Ausgabedaten nicht synchron erfassen können. Starten Sie OutputScope als untergeordneten Bereich, um die endgültigen Ausgabemeldungen aufzuzeichnen, nachdem der übergeordnete Bereich beendet ist.

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

Lokal validieren

Um zu überprüfen, ob Sie erfolgreich in das Observability SDK integriert sind, überprüfen Sie die Konsolenprotokolle, die von Ihrem Agent generiert wurden, und Protokolle aus dem Observability SDK.

Python

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in die Konsole.

Um Fehler beim Exportieren zu untersuchen, aktivieren Sie die ausführliche Protokollierung, indem Sie ENABLE_A365_OBSERVABILITY_EXPORTER auf true setzen und die Debug-Protokollierung beim Start Ihrer Anwendung konfigurieren:

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)

Schlüsselprotokollmeldungen:

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

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in die Konsole.

Um Exportfehler zu untersuchen, legen Sie Umgebungsvariablen in .env oder Shell fest:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Überprüfen Sie die Konsolenausgabe für Nachrichten wie:

[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

Optional können Sie einen benutzerdefinierten Logger verwenden, um Exportereignisse in eine Datei zu erfassen:

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

Legen Sie EnableAgent365Exporter auf false in appsettings.json fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in die Konsole.

Um Exportfehler zu untersuchen, konfigurieren Sie eine detaillierte Protokollierung in appsettings.json:

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

Oder legen Sie Umgebungsvariablen fest:

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

Schlüsselprotokollmeldungen:

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.

Note

Wenn Sie ein ILoggerFactory in DI nicht registrieren, greift der Exporter automatisch auf einen Konsolenlogger zurück.

Anzeigen exportierter Protokolle

Um die Agent-Telemetrie in Microsoft Purview oder Microsoft Defender anzuzeigen, stellen Sie sicher, dass die folgenden Anforderungen erfüllt sind:

• Microsoft Purview: Die Überwachung muss für Ihre Organisation aktiviert sein. Anweisungen finden Sie unter Aktivieren oder Deaktivieren der Überwachung.
• Microsoft Defender: Die erweiterte Suche muss für den Zugriff auf die Tabelle CloudAppEvents konfiguriert werden. Ausführliche Informationen finden Sie in der Tabelle "CloudAppEvents" im Schema für die erweiterte Suche.

Für die Veröffentlichung im Store validieren

Von Bedeutung

Für eine erfolgreiche Shop-Validierung muss Ihr Agent die InvokeAgentScope, InferenceScope und ExecuteToolScope Bereiche implementieren. Diese drei Bereiche sind für die Veröffentlichung erforderlich.

Verwenden Sie vor der Veröffentlichung Konsolenprotokolle, um Ihre Observability-Integration für den Agenten zu überprüfen, indem Sie die erforderlichen invoke agent, execute tool, inference und output Scopes implementieren. Vergleichen Sie dann die Logs Ihres Agenten mit den folgenden Attributlisten, um sicherzustellen, dass alle erforderlichen Attribute vorhanden sind. Erfassen Sie Attribute in jedem Scope oder über den Baggage-Builder und fügen Sie nach Belieben optionale Attribute hinzu.

Für weitere Informationen zu den Anforderungen an die Veröffentlichung im Store siehe die Store-Validierungsrichtlinien.

InvokeAgentScope-Attribute

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines InvokeAgentScope aufgezeichnet werden.

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

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines ExecuteToolScope aufgezeichnet werden.

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

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines InferenceScope aufgezeichnet werden.

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

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die beim Starten eines OutputScope aufgezeichnet werden. Verwenden Sie diesen Bereich für asynchrone Szenarien, in denen der übergeordnete Bereich ausgabedaten nicht synchron erfassen kann.

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

Testen Sie Ihren Agenten mit Observierbarkeit

Nachdem Sie die Observierbarkeit in Ihrem Agent implementiert haben, testen Sie ihn, um sicherzustellen, dass die Telemetrie ordnungsgemäß erfasst wird. Folgen Sie dem Testleitfaden, um Ihre Umgebung einzurichten. Konzentrieren Sie sich dann in erster Linie auf den Abschnitt " Observability-Protokolle anzeigen ", um zu überprüfen, ob die Observability-Implementierung erwartungsgemäß funktioniert.

Überprüfung:

• Navigieren Sie zu https://admin.cloud.microsoft/#/agents/all
• Wählen Sie die >-Aktivität Ihres Agents aus
• Sie sehen Sitzungen und Toolaufrufe.

Problembehandlung

Dieser Abschnitt beschreibt häufige Probleme bei der Implementierung und Anwendung von Observability.

Tipp

Der Agent 365 Troubleshooting Guide enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Teil des Entwicklungszyklus von Agent 365.

Observabilitätsdaten erscheinen nicht

Symptome:

• Agent wird ausgeführt
• Keine Telemetrie im Verwaltungszentrum
• Kann keine Agentenaktivität sehen

Grundursache:

• Observabilität ist nicht aktiviert
• Konfigurationsfehler
• Probleme des Token-Resolvers

Lösungen: Probieren Sie die folgenden Schritte aus, um das Problem zu lösen:

• Überprüfen, ob der Observability-Exporter aktiviert ist

  Sie müssen den Agent 365-Exporter explizit aktivieren. Wenn diese Option deaktiviert ist, greift das SDK auf einen Konsolenexporteur zurück, und es werden keine Telemetriedaten an den Dienst gesendet. Konfigurationsdetails finden Sie unter "Konfiguration".

• Überprüfen Sie die Token-Resolver-Konfiguration

  Der Exporter erfordert einen gültigen Tokenlöser, der ein Bearertoken für jede Exportanforderung zurückgibt. Wenn der Tokenlöser fehlt oder zurückgibt null, wird der Export im Hintergrund übersprungen. Stelle sicher, dass dein Code den Token-Resolver korrekt implementiert. Ausführliche Informationen finden Sie unter Token resolver.

• Überprüfen Sie auf Fehler in den Logs

  Aktivieren Sie die ausführliche Protokollierung und verwenden Sie den az webapp log tail-Befehl, um die Protokolle nach Fehlern im Zusammenhang mit dem Einblick zu durchsuchen. Ausführliche Informationen zum Aktivieren der Protokollierung pro Plattform finden Sie unter "Lokal überprüfen".

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

• Telemetrie-Export überprüfen

  Bestätigen Sie, dass Telemetrie wie erwartet generiert und exportiert wird.

  • Fügen Sie einen Konsolenexporteur hinzu, und überprüfen Sie, ob Telemetrie lokal generiert wird. Ausführliche Informationen zur Verwendung des Konsolenexporteurs und zur Überprüfung der Ausgabe finden Sie unter "Lokal überprüfen".

Fehlende Mandanten-ID oder Agent-ID – übersprungen

Symptome: Das System löscht die Spans unbemerkt und exportiert sie nie. Einige SDKs protokollieren die Anzahl der übersprungenen Spans oder geben eine Meldung wie „Keine Spans mit Mandanten-/Agenten-Identität gefunden“ aus. Andere verwerfen sie, ohne dies zu protokollieren.

Auflösung:

• Vor dem Export unterteilt das SDK die Spannen nach Mandanten und Agentenidentität. Das System verwirft Spans, denen entweder die Mandanten-ID oder die Agenten-ID fehlt, und sendet sie niemals an den Dienst.
• Stellen Sie sicher, dass BaggageBuilder mit der Mandanten-ID und der Agenten-ID konfiguriert ist, bevor Sie Spans erstellen. Diese Werte werden über den OpenTelemetry-Kontext verteilt und an alle Spans angefügt, die innerhalb des Baggage-Bereichs erstellt werden. Informationen zur plattformspezifischen API finden Sie unter Gepäckattribute.
• Stellen Sie sicher, dass die Aktivität TurnContext einen gültigen Empfänger mit Agenten-ID enthält, wenn Sie die Baggage-Middleware verwenden oder den Kontext-Helper aus dem Hosting-Integrationspaket nutzen, um diese IDs zu füllen.

Fehler bei der Token-Auflösung – Export übersprungen oder nicht autorisiert

Symptome: Der Tokenlöser gibt null zurück oder wirft einen Fehler. Je nach SDK wird der Export entweder vollständig übersprungen, oder die Anforderung wird ohne Autorisierungsheader gesendet und schlägt mit HTTP 401 fehl.

Auflösung:

• Der Tokenlöser ist bei der Initialisierung erforderlich. Wenn er fehlt, löst der Exporter beim Start einen Fehler aus. Stellen Sie sicher, dass ein Tokenlöser bereitgestellt wird, und gibt ein gültiges Bearertoken zurück.
• Stellen Sie sicher, dass die richtige Mandanten-ID und Agent-ID für BaggageBuilder verwendet werden, da diese Werte an den Token Resolver übergeben werden.
• Überprüfen Sie für in Azure gehostete Agents, ob die verwaltete Identität über die erforderliche API-Berechtigung für den Überwachungsbereich verfügt.

HTTP 401 nicht autorisiert

Symptome: Der Export schlägt mit HTTP 401 fehl. Der Exporter wiederholt diesen Fehler nicht.

Auflösung:

• Stellen Sie sicher, dass die Zielgruppe des Tokens mit dem Umfang des Observability-Endpunkts übereinstimmt.
• Überprüfen Sie, ob der Tokenlöser kein delegiertes Benutzertoken, kein Token für eine falsche Zielgruppe oder ein abgelaufenes Token zurückgibt.

HTTP 403 – Unzulässig

Symptome: Der Export schlägt mit HTTP 403 fehl. Der Exporter wiederholt diesen Fehler nicht.

Ursache: Ein HTTP 403-Fehler kann unterschiedliche Ursachen haben. Überprüfen Sie die folgenden Auflösungen in der angegebenen Reihenfolge.

Auflösung:

• Missing license – Vergewissern Sie sich, dass Ihrem Mandanten eine der folgenden Lizenzen in Microsoft 365 Admin Center:

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

• Fehlende Agent365.Observability.OtelWrite Berechtigung – Wenn Sie kürzlich ein Upgrade ihrer Observability-Pakete durchgeführt haben, müssen Sie diese Berechtigung erteilen. Weitere Informationen finden Sie unten in der wichtigen Notiz.

Von Bedeutung

Für vorhandene Agents, die auf diese Paketversionen aktualisiert werden, ist ein zusätzlicher Schritt erforderlich.

Dieser Schritt gilt nur, wenn Sie einen vorhandenen Agent aktualisieren. Für neue Agentinstallationen ist dieser Schritt nicht erforderlich. Wenn Sie ein Upgrade auf die folgenden Paketversionen oder neueren Versionen durchführen, müssen Sie Ihrer Identität (verwaltete Identität oder App-Registrierung) die neue Agent365.Observability.OtelWrite Berechtigung erteilen. Ohne diese Berechtigung schlägt der Telemetrieexport mit HTTP 403 fehl.

Plattform	Mindestversion, die diesen Schritt erfordert
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Erteilen Sie die Berechtigung mithilfe einer der folgenden Optionen.

Option A – Agent 365 CLI (erfordert a365.config.json und a365.generated.config.json in Ihrem Konfigurationsverzeichnis, einem globalen Administratorkonto und Agent 365 CLI v1.1.139-preview oder höher)

a365 setup admin --config-dir "<path-to-config-dir>"

Dieser Befehl gewährt alle fehlenden Berechtigungen, einschließlich der neuen Observability-Bereiche.

Option B – Entra-Portal (keine Konfigurationsdateien erforderlich; erfordert globalen Administratorzugriff auf die Blueprint-App-Registrierung)

1. Wechseln Sie zu Entra-Portal>App-Registrierungen> Wählen Sie Ihre Blueprint-App aus.
2. Wechseln Sie zu API-Berechtigungen>Eine Berechtigung hinzufügen>APIs, die meine Organisation verwendet> suchen nach 9b975845-388f-4429-889e-eab1ef63949c.
3. Wählen Sie "Delegierte Berechtigungen> " aus, um Agent365.Observability.OtelWrite>Berechtigungen hinzuzufügen.
4. Wiederholen Sie Schritt 2 bis 3. Dieses Mal wählen Sie "Anwendungsberechtigungen> " aus, um Agent365.Observability.OtelWrite>Berechtigungen hinzuzufügen.
5. Klicken Sie auf " Administratorzustimmung erteilen " und bestätigen Sie.

Sowohl Agent365.Observability.OtelWrite (Delegated) als auch Agent365.Observability.OtelWrite (Anwendung) sollten den Granted Status anzeigen.

HTTP 429 / 5xx – Vorübergehende Fehler

Symptome: Der Export schlägt mit einem vorübergehenden HTTP-Statuscode wie 429 oder 5xx fehl.

Auflösung:

• Diese Fehler sind in der Regel vorübergehend und allein behoben. Die Python- und JavaScript-SDKs führen bei den HTTP-Statuscodes 408, 429 und 5xx automatisch bis zu drei Wiederholungsversuche mit exponentiellem Backoff durch. Das .NET SDK führt keine automatischen Wiederholungen durch.
• Wenn Fehler weiterhin bestehen, überprüfen Sie das Dienststatusdashboard.
• Erwägen Sie, die Exporthäufigkeit zu verringern, indem Sie die geplante Verzögerung zwischen Batches erhöhen oder die maximale Exportbatchgröße erhöhen. Informationen zu Konfigurationsoptionen pro Plattform finden Sie in der Tabelle in "Agent365ExporterOptionsKonfiguration".

Export-Zeitüberschreitung

Symptome: Exportversuche laufen ab.

Auflösung:

• Überprüfen Sie die Netzwerkkonnektivität mit dem Observability-Endpunkt.
• Timeout-Standardeinstellungen variieren je nach Plattform. Das standardmäßige HTTP-Anforderungstimeout beträgt 30 Sekunden. Einige SDKs verfügen zudem über eine separate allgemeine Export-Zeitüberschreitung, die den gesamten Exportzyklus einschließlich der Wiederholungsversuche abdeckt. Die genauen Eigenschaften und Standardwerte pro Plattform finden Sie in der Tabelle in "Agent365ExporterOptionsKonfiguration".
• Wenn Timeouts häufig auftreten, erhöhen Sie den relevanten Timeoutwert in den Exporteroptionen.

Der Export ist erfolgreich, die Telemetrie wird jedoch nicht in Defender oder purview angezeigt.

Symptoms: Protokolle zeigen einen erfolgreichen Export an, die Telemetrie ist jedoch in Microsoft Defender oder Microsoft Purview nicht sichtbar.

Auflösung:

• Stellen Sie sicher, dass Sie die Voraussetzungen zum Anzeigen exportierter Protokolle erfüllen. Für Purview muss die Überwachung aktiviert sein. Für Defender müssen Sie die erweiterte Suche konfigurieren. Weitere Informationen finden Sie unter Anzeigen exportierter Protokolle.
• Telemetriedaten können nach einem erfolgreichen Export mehrere Minuten benötigen, um angezeigt zu werden. Warten Sie, bis die Daten angezeigt werden, bevor Sie weiter untersuchen.

Weitere Informationen zum Testen der Observierbarkeit finden Sie unter:

• Testanleitung – Observabilitätsprotokolle ansehen
• Observabilitätskonfiguration