Veralteter Agent 365 Observability SDK

Important

Dieser Artikel dokumentiert das veraltete Agent 365 Observability SDK. Bestehende Integrationen funktionieren weiterhin, aber nutze dieses SDK nicht für neue Integrationen. Für neue Entwicklungen nutzen Sie die Microsoft OpenTelemetry Distro. Bevor Sie eine bestehende Integration aktualisieren, lesen Sie den Migrationsleitfaden für Ihre Sprache:

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

Für das zugrunde liegende Datenmodell, Identität und Authentifizierung, Scopes und Einwilligung sowie Grenzen, die für jeden Integrationspfad gelten, siehe Agent 365 Observability Concepts.

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.

Hauptvorteile

• 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 Observability 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 von TurnContext übernimmt, einschließlich der Token-Zwischenspeicherung für den Observability-Exporter.

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 von TurnContext übernimmt, einschließlich der Token-Zwischenspeicherung 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 das Gepäck automatisch aus dem TurnContext auffüllt und die Tokenzwischenspeicherung für den Observability-Exporter umfasst.

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

Configuration

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. In Agent 365 SDK 2.0 und später verwendet der Exporteur immer die Service-to-Service-Route (S2S) und authentifiziert sich mit der konfigurierten App-only-Authentifizierung token_resolver. Wenn du den Exporter ohne Resolver aktivierst, behält Python den Konsolenexporter als Fallback und sendet keine Telemetrie an Agent 365.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Return a validated app-only observability token for this agent and tenant.
    return "<app-only-observability-token>"

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

Der Token-Resolver ist vom Logging in der Konsole ausgeschlossen.

Sie können das Exporterverhalten anpassen, indem Sie eine Agent365ExporterOptions Instanz an exporter_options. 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	Default
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, unterdrückt Eingabemeldungen auf InvokeAgent Spans.	False

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

Property	Description	Default
use_s2s_endpoint	Veraltet und ignoriert. Agent 365 SDK 2.0 und später nutzen immer den S2S-Weg, selbst wenn dieser Wert False ist.	False (ignoriert)
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. In Agent 365 SDK 2.0 und später verwendet der Exporteur immer die S2S-Route und authentifiziert sich mit dem konfigurierten App-only-Token-Resolver. Wenn du den Agent 365 Exporter ohne Resolver aktivierst, schlägt die Konfiguration fehl.

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

// Define a token resolver that returns a validated app-only observability token.
const tokenResolver = (agentId, tenantId) => {
    // Your app-only 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. Mit dieser Option kannst du Batching und Timeouts steuern. Die Exportroute ändert sich nicht.

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.

Property	Description	Default
useS2SEndpoint	Veraltet und ignoriert. Agent 365 SDK 2.0 und später nutzen immer den S2S-Weg, selbst wenn dieser Wert false ist.	true (ignoriert)
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 Agent 365 SDK 2.0 und später verwendet der Exporteur immer die S2S-Route und authentifiziert sich mit dem konfigurierten App-only-Token-Resolver. Wenn du den Exporter ohne TokenResolver oder ContextualTokenResolveraktivierst, schlägt die Exporter-Konstruktion fehl.

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) =>
            {
                // Return a cached, validated app-only observability token for this agent and tenant.
                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.

Property	Description	Default
UseS2SEndpoint	Veraltet und wird ignoriert. Agent 365 SDK 2.0 und später nutzen immer den S2S-Weg, selbst wenn dieser Wert false ist.	false (ignoriert)
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 eine SpanProcessor , die alle nichtleeren Baggage-Einträge in neu gestartete Spans kopiert, ohne dass bestehende Attribute überschrieben werden.

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 Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdaten aus allen eingehenden TurnContext und umschließt die Anfrage in einem Gepäckbereich.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternativ können Sie 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 Konfiguration für asynchrone Antworten (ContinueConversation Async-Ereignisse), um das Überschreiben von Baggage zu vermeiden, das bereits durch die ursprüngliche Anforderung festgelegt wurde.

JavaScript

Registrieren Sie BaggageMiddleware auf dem Adapter. Es extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdaten aus allen eingehenden TurnContext und umschließt die Anfrage in einem Gepäckbereich.

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

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

Alternativ können Sie 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 Konfiguration für asynchrone Antworten (ContinueConversation Async-Ereignisse), um das Überschreiben von Baggage zu vermeiden, das bereits durch die ursprüngliche Anforderung festgelegt wurde.

.NET

Registrieren Sie BaggageTurnMiddleware auf dem Adapter. Es extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdaten aus allen eingehenden ITurnContext und umschließt die Anfrage in einem Gepäckbereich.

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

adapter.Use(new BaggageTurnMiddleware());

Die Middleware überspringt die Konfiguration für asynchrone Antworten (ContinueConversation Async-Ereignisse), um das Überschreiben von Baggage zu vermeiden, das bereits durch die ursprüngliche Anforderung festgelegt 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 in Agent 365 SDK 2.0 und höher verwenden, stellen Sie einen Token-Resolver bereit, der den finalen App-only-Observability-Token für die exportierende Agenteninstanz zurückgibt. Der Exporteur sendet immer Telemetrie an die S2S-Route und fällt nicht auf die delegierte Route zurück. Eine Agent-365-registrierte Agent-Instanz benötigt keine Agent365.Observability.OtelWrite-Berechtigung oder Admin-Einwilligung, um auf dieser Route zu exportieren.

Verwenden Sie den zweistufigen Federated Managed Identity (FMI)-Austausch, um das App-only-Token zu erhalten:

1. Holen Sie sich ein Blueprint-Token client_credentials für api://AzureADTokenExchange/.default mit fmi_path, gesetzt auf die Client-ID der Agent-Instanz.
2. Erhalten Sie ein Agent-Instanz-Token client_credentials für api://9b975845-388f-4429-889e-eab1ef63949c/.default. Übergeben Sie das Step-1-Token als client_assertion, und setzen Sie client_assertion_type auf urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Für die vollständige Authentifizierungseinrichtung siehe Agent 365-fähig mit S2S. Für vollständige Token-Service-Implementierungen siehe die Agent-365-Beispiele für Node.js, Python und .NET.

Ihr Resolver muss:

• Geben Sie ein App-only-Token für die exportierende Instanz und den Mandanten zurück. Gib niemals die Assertion des Zwischen-Blueprints, ein Blueprint-Token, ein Benutzertoken oder ein OBO-Token zurück.
• Validiere das Token, bevor du es zurückgibst. Akzeptieren idtyp=app Wenn idtyp fehlt, akzeptieren Sie nur ein Token mit einem nichtleeren roles-Claim oder einem nichtleeren oid-Claim, der sub entspricht. Lehne Token ab, die einen scp Claim oder einen anderen idtyp Wert haben, abgelaufene Token und Token, deren aud nicht 9b975845-388f-4429-889e-eab1ef63949c oder api://9b975845-388f-4429-889e-eab1ef63949c ist.
• Cache den Token und erneuere ihn, bevor er abläuft. Der Exporter ruft den Resolver für jeden Tenant und jede Agentenidentität in jedem Exportbatch einmal auf.

Note

Migration von SDK 1.x: SDK 2.0 entfernt den delegierten Token-Austausch für den Export der Observabilität. Ersetzen Sie den delegierten Token-Code in Ihrem Agenten durch einen reinen App-Resolver, wie in den folgenden Beispielen gezeigt. Agenten, die auf SDK 1.x bleiben und auf der delegierten Route exportieren, benötigen weiterhin die delegierte Agent365.Observability.OtelWrite Berechtigung und die Administratorzustimmung. Der a365 setup all Befehl konfiguriert diese Berechtigung nicht für Blueprint-Agenten. Informationen dazu finden Sie unter Berechtigung erteilen.

Python

Rufe AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, acquire_app_only_obs_token) von deinem token_resolver an. Der Cache übergibt den Observabilitätsbereich /.default an Ihren Abruf-Callback und gibt das zwischengespeicherte Token zurück.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import AgenticTokenCache

cache = AgenticTokenCache()

async def acquire_app_only_obs_token(
    agent_id: str,
    tenant_id: str,
    scopes: list[str],
) -> str:
    # Run the FMI exchange described earlier, validate the token, and return it.
    return "<app-only-observability-token>"

async def token_resolver(agent_id: str, tenant_id: str) -> str:
    return await cache.refresh_observability_token(
        agent_id, tenant_id, acquire_app_only_obs_token
    )

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

Python unterstützt außerdem einen synchronen Resolver, der ein Token aus einem threadsicheren Cache zurückgibt. Die Agent-365-Samples verwenden dieses Muster, das die Einschränkungen eines asynchronen Resolvers im Exporter-Thread umgeht.

Um von SDK 1.x zu migrieren, entferne den AGENT_APP.auth.exchange_token Aufruf, der den Observability Scope angefordert hat, und den AgenticTokenCache.register_observability Aufruf, der ein AgenticTokenStruct übergeben hat. In SDK 2.0, register_observability ist ein veralteter No-Op.

JavaScript

withTokenResolver mit AgenticTokenCacheInstance.RefreshObservabilityToken(agentId, tenantId, acquireAppOnlyObsToken) verwenden Der Acquisition-Callback empfängt (agentId, tenantId, scopes) und gibt das endgültige App-Only-Observability-Token zurück. Lies das zwischengespeicherte Token mit AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId).

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

async function acquireAppOnlyObsToken(
  agentId: string,
  tenantId: string,
  scopes: readonly string[]
): Promise<string> {
  // Run the FMI exchange described earlier, validate the token, and return it.
  return "<app-only-observability-token>";
}

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver(async (agentId, tenantId) => {
      await AgenticTokenCacheInstance.RefreshObservabilityToken(
        agentId, tenantId, acquireAppOnlyObsToken
      );
      return AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId);
    })
);

builder.start();

Um von SDK 1.x zu migrieren, entferne den agentApplication.authorization.exchangeToken Aufruf, der den Observability-Scope angefordert hat, und ersetze RefreshObservabilityToken(agentId, tenantId, context, authorization, scopes) durch die Resolver-Form im Beispiel. SDK 2.0 beseitigt die delegierte Überladung: TypeScript-Aufrufer erhalten einen Kompilierungsfehler, und untypierte Aufrufer erhalten eine einmalige Fehlermeldung im Protokoll und kein Token.

.NET

Verwenden Sie AddAgenticTracingExporter(), um IExporterTokenCache<ObservabilityTokenResolver> und Exporteroptionen zu registrieren, die Token aus dem Cache lesen.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Registrieren Sie in der Agentenanwendung einen reinen App-Resolver für den Agenten und den Tenant, indem Sie aufrufen RegisterObservability(agentId, tenantId, resolver, scopes). Die erste Registrierung für einen Makler und Mieter hat Vorrang.

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

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<ObservabilityTokenResolver> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<ObservabilityTokenResolver> agentTokenCache)
        : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var agentId = turnContext.Activity.Recipient.AgenticAppId;
        var tenantId = turnContext.Activity.Recipient.TenantId;

        _agentTokenCache.RegisterObservability(
            agentId,
            tenantId,
            AcquireAppOnlyObservabilityTokenAsync,
            EnvironmentUtils.GetObservabilityAuthenticationScope());

        using var baggageScope = new BaggageBuilder()
            .TenantId(tenantId)
            .AgentId(agentId)
            .Build();

        // Handle the message.
    }

    private static Task<string?> AcquireAppOnlyObservabilityTokenAsync(
        string agentId,
        string tenantId,
        string[] observabilityScopes)
    {
        // Run the FMI exchange described earlier, validate the token, and return it.
        return Task.FromResult<string?>("<app-only-observability-token>");
    }
}

Wenn du eine AgenticTokenCache Instanz direkt verwaltest, rufe RefreshObservabilityToken(agentId, tenantId, resolver) auf, um den Standard-Observability-Scope zu verwenden oder RefreshObservabilityToken(agentId, tenantId, resolver, scopes), um Scopes explizit zu übergeben.

Um von SDK 1.x zu migrieren, ersetzen Sie IExporterTokenCache<AgenticTokenStruct> und den RegisterObservability-Aufruf, der ein AgenticTokenStruct übergeben hat, durch den App-only-Resolver im Beispiel. ExchangeTurnTokenAsync nicht für den Export der Observabilität verwenden. In SDK 2.0 ist die AgenticTokenStruct Registrierungsüberladung veraltet und verursacht einen Kompilierungsfehler.

Automatische Instrumentierung

Die Auto-Instrumentierung überwacht automatisch agentenbasierte Frameworks (SDKs), bestehende Telemetriesignale für Traces und leitet sie an den Beobachtungsdienst Agent 365 weiter. Diese Funktion beseitigt die Notwendigkeit für Entwickler, Überwachungscode manuell zu schreiben, vereinfacht die Einrichtung und gewährleistet eine konsistente Leistungsverfolgung.

Important

Die automatische Instrumentierung füllt nur OTel-Standardattribute auf. Sie müssen Microsoft spezifische Attribute über BaggageBuilder hinzufügen. Um zu sehen, welche Attribute fehlen, gleichen Sie Ihre Konsolen-Span-Ausgabe mit den Store-Logs ab, um die Diff-Menge zu ermitteln.

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 den Einsatz eines Baggage-Builders. Setzen Sie die Agenten-ID und die Mandanten-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 den Einsatz eines Baggage Builders. Setzen Sie die Agenten-ID und die Mandanten-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 den Einsatz eines Baggage Builders. Setzen Sie die Agenten-ID und die Mandanten-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

Note

Die automatische Instrumentierung für das LangChain-Framework unterstützt auch LangGraph und Deep Agents. Die gleiche Erweiterung erfasst automatisch Telemetrie für Agents, die mit einem dieser Frameworks gebaut wurden.

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.

Agentenaufruf

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 Observability-Tracking bei der Werkzeugausführung Ihres Agenten 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 den Geltungsbereich mit den Details des Agents erstellen, die automatisch von der ScopeUtils.populateInferenceScopeFromTurnContext 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);

Output

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 Span, um abschließende Ausgabemeldungen aufzuzeichnen, nachdem der übergeordnete Bereich beendet wurde.

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 sich erfolgreich in das Observability-SDK integriert haben, prüfen Sie die von Ihrem Agenten generierten Konsolenlogs und die Logs des Observability-SDK.

Python

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Einstellung exportiert Span-Daten (Verfolgungsdaten) an die Konsole.

Um Exportfehler 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 Span-Daten (Verfolgungsdaten) an 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 Span-Daten (Verfolgungsdaten) an die Konsole.

Um Exportfehler zu untersuchen, konfigurieren Sie 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 Agententelemetrie in Microsoft Purview oder Microsoft Defender einzusehen, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

• 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

Important

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 Ihre Agentenaktivität > aus
• Sie sehen Sitzungen und Toolaufrufe.

Troubleshooting

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

Problem	Description
Observability-Daten werden nicht angezeigt	Es ist keine Telemetrie sichtbar, da das Exportieren nicht aktiviert ist, die Konfiguration falsch ist oder die Tokenauflösung fehlschlägt.
Fehlende Mandanten-ID oder Agent-ID – übersprungene Spanne	Spans werden vor dem Export verworfen, wenn Identitätsattribute, die für die Partitionierung erforderlich sind, fehlen.
Fehler bei der Tokenauflösung – Export übersprungen oder nicht autorisiert	Der Export schlägt fehl, wenn der Resolver kein Token zurückgibt oder auf eine Ausnahme stößt.
HTTP 401 nicht autorisiert	Die Authentifizierung ist syntaktisch erfolgreich, jedoch ist das Token für die Ingestion aufgrund von Berechtigungsumfang, Typ oder Ablaufdatum ungültig.
HTTP 403 Verboten	Der Zugang wird verweigert wegen Lizenzlücken bei Mandanten, einer fehlenden Agent 365-Registrierung oder fehlender Observability-Berechtigung, bei der eine solche erforderlich ist.
HTTP 403 Verboten – Agent-ID stimmt nicht überein	Die Anforderung wird abgelehnt, wenn die Agentidentität in der URL nicht mit der identität übereinstimmt, die durch das Token dargestellt wird.
HTTP 429- oder 5xx-Fehler – Vorübergehende Fehler	Vorübergehende Drosselung oder serverseitige Fehler unterbrechen den Export und können eine Anpassung der Wiederholungsparameter erforderlich machen.
Exporttimeout	Telemetriebatches überschreiten die konfigurierten Timeoutfenster aufgrund der Netzwerklatenz oder der Reaktionsfähigkeit des Endpunkts.
Der Export ist erfolgreich, die Telemetrie wird jedoch nicht in Defender oder purview angezeigt.	Die Erfassung wird abgeschlossen, die nachgelagerte Sichtbarkeit wird jedoch durch produktseitige Voraussetzungen verzögert oder blockiert.

Tip

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 läuft
• 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 deaktiviert, verwendet das SDK einen Konsolenexporteur, und die Telemetrie wird nicht an den Dienst gesendet. Konfigurationsdetails finden Sie unter "Konfiguration".

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

  Der Exporteur benötigt einen gültigen Token-Resolver, der für jede Exportanfrage ein app-only Observability-Token zurückgibt. Wenn der Resolver fehlt, kein Token zurückgibt oder einen Fehler auslöst, sendet der Export keine Anfrage. Stelle sicher, dass dein Code den Token-Resolver implementiert. Ausführliche Informationen finden Sie unter Token resolver.

• Überprüfen Sie auf Fehler in den Logs

  Aktivieren Sie ausführliche Protokollierung und verwenden Sie den az webapp log tail Befehl, um Protokolle nach Fehlern im Zusammenhang mit der Beobachtbarkeit 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 verwirft die Spans unbemerkt und exportiert sie nie. Einige SDKs protokollieren eine Anzahl übersprungener Bereiche oder eine Meldung wie "Keine Spanne mit gefundener Mandanten-/Agent-Identität". Andere legen sie ohne Protokollierung ab.

Auflösung:

• Vor dem Export partitioniert das SDK die Spans nach Mandanten- und Agentenidentität. Das System verwirft Bereiche, die entweder keine Mandanten-ID oder keine Agent-ID haben, und sendet sie nie an den Dienst.
• Stellen Sie sicher, dass BaggageBuilder mit der Mandanten-ID und der Agenten-ID eingerichtet ist, bevor Sie Spannweiten 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.
• Vergewissern Sie sich, dass die TurnContext aktivität über einen gültigen Empfänger mit Agentidentität verfügt, wenn Sie die Baggage-Middleware verwenden oder die Kontexthilfe aus dem Hostingintegrationspaket verwenden, um diese IDs auszufüllen.

Fehler bei der Tokenauflösung – Export übersprungen oder nicht autorisiert

Symptome: Der Token-Resolver gibt null zurück, gibt ein leeres Token zurück oder wirft einen Fehler. Der Export schlägt fehl, ohne eine Anfrage zu senden, und der Exporter greift nicht auf die delegierte Route zurück.

Auflösung:

• Stellen Sie einen Resolver bereit, der den finalen app-only Observability-Token für die exportierende Agenteninstanz und den Tenant zurückgibt.
• 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 das sprachspezifische Startverhalten. Bei Node.js schlägt die Konfiguration fehl, wenn der Agent 365-Exporter ohne Resolver aktiviert ist, .NET schlägt bei der Exporter-Konstruktion fehl, und Python fällt auf den Konsolen-Exporter zurück, wenn kein Resolver konfiguriert ist.
• Überprüfen Sie, ob Ihr Resolver das Token validiert, bevor er es zurückgibt. Es muss delegierte Token mit einem scp-Claim und Token, die für die falsche Zielgruppe ausgegeben wurden, ablehnen.

HTTP 401 nicht autorisiert

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

Auflösung:

• Überprüfen Sie, dass die Token-Zielgruppe 9b975845-388f-4429-889e-eab1ef63949c oder api://9b975845-388f-4429-889e-eab1ef63949cist.
• Überprüfen Sie, dass der Token-Resolver weder ein delegiertes Benutzertoken, ein Token mit einem scp Claim, ein Token für eine falsche Zielgruppe noch ein abgelaufenes Token zurückgibt.
• Bestätigen Sie, dass der Resolver das finale Agent-Instanz-Token zurückgibt, nicht die zwischenliegende Blueprint-Assertion.

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

• Die Agent-Instanz ist nicht registriert – Die S2S-Route akzeptiert ein App-only-Token ohne die Agent365.Observability.OtelWrite Rolle nur von einer Agent-365-registrierten Agent-Instanz. Ansonsten gibt es HTTP 403 insufficient_scopezurück. Für Blueprint-Agenten registriert a365 setup all die Agenteninstanz. Um eine fehlgeschlagene Registrierung erneut zu versuchen, führe a365 setup all --agent-registration-only aus. Allein das Erstellen einer Microsoft Entra-Identität registriert die Agenteninstanz nicht.

• Token ist nicht nur app-basiert – Überprüfen Sie, ob der Token keinen scp Claim enthält. Der S2S-Weg erfordert ein reines Anwendungstoken.

• Der unregistrierten Identität fehlt die App-Rolle – Unregistrierte Identitäten, einschließlich der Standard-App-Registrierungen, die benutzerdefinierte Engine-Agenten verwenden, benötigen die Agent365.Observability.OtelWrite App-Rolle. Um sie zu erteilen, siehe Berechtigung erteilen.

• SDK 1.x-Agent auf der delegierten Route — Die delegierte Route benötigt die delegierte Agent365.Observability.OtelWrite Berechtigung und die Admin-Einwilligung, die von a365 setup all für Blueprint-Agenten nicht konfiguriert wird. Aktualisieren Sie auf SDK 2.0 oder die Berechtigung erteilen.

• Die Agenten-ID stimmt nicht mit dem Token überein – siehe HTTP 403 Forbidden - Agent ID Mismatch.

HTTP 403 Verboten – Nichtübereinstimmung der Agent-ID

Symptome: Der Export schlägt mit HTTP 403 und einer Servernachricht fehl, die mit 403 Forbidden Fehlern beim Aufrufen von Agent 365-Ablaufverfolgungsendpunkten vergleichbar istagent-ID-mismatch.

Ursache: Dieser Fehler tritt auf, wenn Sie die Blueprint-Client-ID anstelle der Agentinstanz-Client-ID verwenden, wenn Sie die Agentdetails festlegen. Die Agent-ID in der Export-URL stimmt nicht mit der durch das Token autorisierten Identität überein, sodass der Traces-Endpunkt die Anfrage ablehnt.

Auflösung:

• Überprüfen Sie, ob die Mandanten-ID der Liste "Agent 365 zulässiger Mandanten" hinzugefügt wird.
• Legen Sie die Agentdetails mit der Client-ID der Agentinstanz fest (nicht die Blueprint-Client-ID).
• Überprüfen Sie die generierte Export-URL – es wird protokolliert, wenn Sie Ihren Logger aktivieren. Bestätigen Sie, dass die Agent-ID in der URL mit der Client-ID der Agentinstanz übereinstimmt.
• Informationen zum Aktivieren der Diagnoseprotokollierung pro SDK finden Sie unter "Lokal überprüfen".

HTTP 429- oder 5xx-Fehler – 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 wiederholen bei HTTP 408-, 429- und 5xx-Statuscodes automatisch bis zu dreimal mit exponentiellem Backoff. 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 auch über ein separates Gesamtexport-Timeout, das den gesamten Exportzyklus einschließlich Wiederholungen 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

Verwandte Inhalte

• Agent 365-Observability-Konzepte – Datenfluss, Identitätsmodelle, Authentifizierung, Bereiche und Grenzwerte, die für jeden Integrationspfad gelten.
• Referenz der Observability-Attribute für Agent 365 - Kanonisches Schema für Span-Attribute, dem jeder von Agent 365 erfasste Span entsprechen muss.
• Microsoft OpenTelemetry Distro – Das empfohlene unified SDK für neue Integrationen.