Einblick SDK

Wichtig

Um Einblick in Agent 365 zu aktivieren, verwenden Sie die Microsoft OpenTelemetry Distro. Diese Verteilung bietet ein einziges Observability-SDK für Microsoft, das Agent 365, Microsoft Foundry, Azure Monitor und mehr unterstützt. Die bestehende Methode, die in diesem Artikel beschrieben wird, bleibt weiterhin funktionsfähig und verursacht keine Breaking Changes. Für Migrationsleitfäden nach Sprache siehe die folgenden Anleitungen:

• Anleitung zur Python-Migration
• JavaScript/TypeScript Migrationsleitfaden
• .NET-Migrationsleitfaden Für das zugrunde liegende Datenmodell, Identität und Authentifizierung, Scopes und Einwilligung sowie Limits – die für jeden Integrationspfad gelten – siehe Agent 365 Observability-Konzepte.

Anmerkung

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

Um am Agent 365-Ökosystem teilzunehmen, müssen Sie Agent 365 Einblicke-Funktionen zu Ihrem Agent hinzufügen. Der Agent 365 Einblicke baut auf OpenTelemetry (OTel) auf und bietet ein einheitliches Framework zum konsistenten und sicheren Erfassen von Telemetrie auf allen Agentplattformen. Durch die Implementierung dieser erforderlichen Komponente ermöglichen Sie IT-Admins, die Aktivitäten Ihres Agents im Microsoft Admin Center zu überwachen, und ermöglichen es Sicherheitsteams, Defender und Purview für die Einhaltung von Vorschriften und die Erkennung von Bedrohungen zu nutzen.

Wesentliche Vorteile

• End-to-End-Sichtbarkeit: Erfassen Sie umfassende Telemetrie für jeden Agent-Aufruf, einschließlich Sitzungen, Toolanrufe und Ausnahmen, sodass Sie plattformübergreifend vollständig nachverfolgt werden können.
• Sicherheit und Compliance-Enablement: Führen Sie einheitliche Überwachungsprotokolle in Defender und Purview ein, um erweiterte Sicherheitsszenarien und Compliance-Berichte für Ihren Agent zu ermöglichen.
• 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.
• Betriebseffizienz für Admins: Bereitstellen eines zentralen Einblicks in Microsoft 365 Admin Center, Reduzierung der Problembehandlungszeit und Verbesserung der Governance mit rollenbasierten Zugriffssteuerungen für IT-Teams, die Ihren Agent verwalten.

Unterstützte Agents

Die folgenden Agenttypen unterstützen den Einblick von Agent 365:

• Microsoft Agent 365-gestützte Agents: Verwenden Sie das Einblicks-SDK, um Ihren Agent zu instrumentieren.
• Benutzerdefinierte Engine-Agents: Verwenden Sie das Einblicks-SDK, um Ihren Agent zu instrumentieren.
• Deklarative Agents: Einblick wird standardmäßig unterstützt. Keine SDK-Implementierung erforderlich.

Installation

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

Python

Installieren Sie die grundlegenden Observabilitäts- und Laufzeitpakete. Alle Agents, die Agent 365 Einblick verwenden, benötigen diese Pakete.

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

Wenn Ihr Agent das Microsoft Agents Hosting-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-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 automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter Auto-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 grundlegenden Observabilitäts- und Laufzeitpakete. Alle Agents, die Agent 365 Einblick verwenden, benötigen diese Pakete.

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

Wenn Ihr Agent das Paket @microsoft/agents-hosting 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-Exporteurs.

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

Wenn Ihr Agent eines der unterstützten KI-Frameworks verwendet, installieren Sie die entsprechende Erweiterung für automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter Auto-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 Kern-Einblick- und Laufzeitpaket. Alle Agents, die Agent 365 Einblick 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 automatische Instrumentierung, um Telemetrie automatisch ohne manuellen Instrumentierungscode zu erfassen. Konfigurationsdetails finden Sie unter Auto-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 Einblick für Ihren Agent zu aktivieren und anzupassen.

Python

Setzen Sie die ENABLE_A365_OBSERVABILITY_EXPORTER-Umgebungsvariable auf true, um Einblick zu aktivieren. Diese Einstellung exportiert Logs an den Dienst und erfordert, 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 Exporterverhalten anpassen, indem Sie eine Agent365ExporterOptions-Instanz an exporter_options weitergeben. Wenn exporter_options bereitgestellt wird, hat er gegenüber den Parametern token_resolver und cluster_category Vorrang.

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

Die folgende Tabelle beschreibt die optionalen Parameter für configure().

Parameter	BESCHREIBUNG	Standard
logger_name	Name des Python-Loggers, der für Debugging und Konsolenausgabe verwendet wird.	microsoft_agents_a365.observability.core
exporter_options	Eine Agent365ExporterOptions-Instanz, die den Token Resolver und die Cluster-Kategorie gemeinsam konfiguriert.	None
suppress_invoke_agent_input	Wenn True, werden Eingabemeldungen auf InvokeAgent-Spannen unterdrückt.	False

In der folgenden Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Eigenschaften	BESCHREIBUNG	Standard
use_s2s_endpoint	Verwendet bei True den Dienst-zu-Dienst-Endpunktpfad.	False
max_queue_size	Maximale Größe der Warteschlange für den Batch-Prozessor.	2048
scheduled_delay_ms	Verzögerung in Millisekunden zwischen den Exportchargen.	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

Setzen Sie die ENABLE_A365_OBSERVABILITY_EXPORTER-Umgebungsvariable auf true, um Einblick zu aktivieren. Diese Einstellung exportiert Logs an den Service und erfordert die Bereitstellung eines Token Resolvers. 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();

Statt Umgebungsvariablen können Sie die Observabilität auch programmatisch mithilfe eines Konfigurationsproviders über die withConfigurationProvider-Methode konfigurieren. Wenn Sie auch individuelle Builder-Methoden (wie withExporterOptions oder withClusterCategory) verwenden, haben die individuellen Builder-Methoden Vorrang vor Werten des Konfigurationsproviders.

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

In der folgenden Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Eigenschaften	BESCHREIBUNG	Standard
useS2SEndpoint	Verwendet bei true den Dienst-zu-Dienst-Endpunktpfad.	false
maxQueueSize	Maximale Größe der Warteschlange für den Batch-Prozessor.	2048
scheduledDelayMilliseconds	Verzögerung in Millisekunden zwischen den Exportchargen.	5000
exporterTimeoutMilliseconds	Timeout in Millisekunden für den gesamten Exportvorgang.	90000
httpRequestTimeoutMilliseconds	Timeout in Millisekunden für jede einzelne HTTP-Anfrage an das Backend.	30000
maxExportBatchSize	Maximale Batchgröße für Exportvorgänge.	512

Sie können auch einen benutzerdefinierten Logger bereitstellen, der die Schnittstelle ILogger implementiert (info, warn, error, event). Geben Sie es mit withCustomLogger an den Ersteller weiter.

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.cs, hinzufügen Agent365ExporterOptions zur Serviceauflistung. Diese Änderung konfiguriert die Stellvertretung, die der Ablaufverfolgungsexporteur zum Abrufen des Tokens verwendet.

Einblickbezogene Abhängigkeiten hinzufügen mit 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 Verhalten des Exporters anpassen, indem Sie einen Konfigurationsdelegaten und einen Exporter-Typ an AddA365Tracing() übergeben.

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

In der folgenden Tabelle beschreibt die optionalen Eigenschaften für Agent365ExporterOptions.

Eigenschaften	BESCHREIBUNG	Standard
UseS2SEndpoint	Verwendet bei true den Dienst-zu-Dienst-Endpunktpfad.	false
MaxQueueSize	Maximale Größe der Warteschlange für den Batch-Prozessor.	2048
ScheduledDelayMilliseconds	Verzögerung in Millisekunden zwischen den Exportchargen.	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

Um BaggageBuilder automatisch aus TurnContext zu befüllen, verwenden Sie den populate Helfer im microsoft-agents-a365-observability-hosting Paket. Dieser Helfer extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdetails 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
});

Um BaggageBuilder automatisch aus TurnContext zu befüllen, verwenden Sie den fromTurnContext Helfer im @microsoft/agents-a365-observability-hosting Paket. Dieser Helfer extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdetails 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.

Um BaggageBuilder automatisch aus ITurnContext zu befüllen, verwenden Sie die FromTurnContext Erweiterungsmethode im Microsoft.Agents.A365.Observability.Hosting Paket. Diese Erweiterungsmethode extrahiert automatisch Anrufer-, Agenten-, Mandanten-, Kanal- und Gesprächsdetails 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();

Baggage-Middleware

Wenn Ihr Agent das Hosting-Integrationspaket verwendet, registrieren Sie die Baggage-Middleware, um Baggage für jede eingehende Anfrage automatisch zu setzen. Dieser Schritt macht es überflüssig, BaggageBuilder in jedem Aktivitätshandler manuell aufzurufen.

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 Baggage auf HTTP-Ebene benötigen (zum Beispiel, um Mandant- 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 Resolver-Funktion bereitstellen, die die Mandant-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 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 Sie mithilfe des microsoft_agents.hosting.core SDK ein Token generieren können. Das hier generierte Authentifizierungstoken wird verwendet, um die Abschnitte in den A365-Erfassungsdienst zu exportieren. Agenten können selbst ein Token generieren, zum Beispiel mithilfe der Microsoft Authentication Library (MSAL) (MSAL), müssen jedoch sicherstellen, dass der Token den Observabilitätsbereich erfüllt.

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

Bei einem mit der A365-CLI erstellten Agent, der einen KI-Teammate und das Paket Microsoft Agent 365 Observability Hosting Library verwendet, nutzen Sie AgenticTokenCache, um das Token-Caching automatisch zu verwalten. 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 Einblick-Konfiguration.

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 Sie mithilfe des @microsoft/agents-hosting SDK ein Token generieren können. Das hier generierte Authentifizierungstoken wird verwendet, um die Abschnitte in den A365-Erfassungsdienst zu exportieren. Agenten können selbst ein Token generieren, zum Beispiel mithilfe der Microsoft Authentication Library (MSAL) (MSAL), müssen jedoch sicherstellen, dass der Token den Observabilitätsbereich erfüllt.

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 Einblick-Konfiguration.

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 Codebeispiel zeigt, wie Sie ein Token mit dem Microsoft.Agents Hosting-SDK generieren. Verwenden Sie das generierte Authentifizierungstoken, um die Abschnitte in den A365-Erfassungsdienst zu exportieren. Agenten können selbst ein Token generieren, zum Beispiel mithilfe der Microsoft Authentication Library (MSAL) (MSAL), müssen jedoch sicherstellen, dass der Token den Observabilitätsbereich erfüllt.

Stellen Sie einen Tokenlöser bereit, indem Sie Agent365ExporterOptions mit einer TokenResolver-Stellvertretung registrieren. Der Delegierte erhält das agentId und das tenantId und gibt ein 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);
            }
        };
    });

Bei einem mit der A365-CLI erstellten Agenten, der einen KI-Teammate und das NuGet-Paket Microsoft.Agents.A365.Observability.Hosting verwendet, nutzen Sie die AddAgenticTracingExporter()-Methode, um das Token-Caching automatisch über die Abhängigkeitsinjektion zu handhaben.

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 agentische Frameworks (SDKs) vorhandene Telemetriesignale für Ablaufverfolgungen und leitet sie an den Agent 365-Einblick-Service weiter. Durch dieses Feature ist es für Entwickler nicht erforderlich, Überwachungscode manuell zu schreiben, das Setup wird vereinfacht und eine konsistente Leistungsnachverfolgung sichergestellt.

Wichtig

Auto-Instrumentierung setzt ausschließlich Standard-OTel-Attribute. 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 Differenzen zu ermitteln.

Mehrfache SDKs und Plattformen unterstützen Auto-Instrumentation:

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

Anmerkung

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

Semantischer Kernel

Die automatische Instrumentierung erfordert die Verwendung des BaggageBuilders. Legen Sie die Agent-ID und Mandanten-ID mithilfe von BaggageBuilder fest.

Python

Installieren des Pakets.

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

Konfigurieren des Einblicks

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

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

Legen Sie AgentId und TenantId mit Hilfe von BaggageBuilder fest. Stellen Sie sicher, dass die ID, die beim Erstellen einer ChatCompletionAgent verwendet wird, mit der Agent-ID übereinstimmt, die an BaggageBuilder weitergegeben wird.

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. Legen Sie die Agent-ID und Mandanten-ID mithilfe von BaggageBuilder fest.

Python

Installieren des Pakets.

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

Konfigurieren des Einblicks

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

Installieren des Pakets.

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

Konfigurieren des Einblicks

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

Legen Sie AgentId und TenantId mit Hilfe von BaggageBuilder fest. Starten Sie für Toolaufrufe eine Überwachung mithilfe von Trace() an einer ChatToolCall Instanz.

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

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

Agent Framework

Die automatische Instrumentierung erfordert die Verwendung des BaggageBuilders. Legen Sie die Agent-ID und Mandanten-ID mithilfe von BaggageBuilder fest.

Python

Installieren des Pakets.

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

Konfigurieren des Einblicks

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

Legen Sie AgentId und TenantId mit Hilfe von BaggageBuilder fest.

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. Legen Sie die Agent-ID und Mandanten-ID mithilfe von BaggageBuilder fest.

Python

Installieren des Pakets.

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

Konfigurieren des Einblicks

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

Installieren des Pakets.

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

Konfigurieren des Einblicks

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 Agent 365 Einblick-SDK, um die interne Arbeit des Agents zu verstehen. Das SDK stellt Umfänge bereit, die Sie starten können: InvokeAgentScope, ExecuteToolScope, InferenceScope und OutputScope.

Agent-Aufruf

Verwenden Sie diesen Umfang zu Beginn Ihres Agent-Prozesses. Mit dem Aufruf von Agent-Umfang können Sie Eigenschaften wie den aktuellen Agent, der aufgerufen wird, Agent-Benutzerdaten 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 ScopeUtils.populateInvokeAgentScopeFromTurnContext nutzen, um den Umfang mit Agentdetails, Anruferdetails und Kanalinformationen zu erstellen, die automatisch aus dem 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; }
}

Ausführung des Tools

Die folgenden Beispiele zeigen, wie Sie die Einblick-Verfolgung bei der Toolausführung Ihres Agents implementieren können. Diese Verfolgung 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, können Sie mit ScopeUtils.populateExecuteToolScopeFromTurnContext den Umfang erstellen, wobei die Agentdaten automatisch aus dem 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.\"}");

Rückschluss

Die folgenden Beispiele zeigen, wie Sie KI-Modellableitungsaufrufe mit Einblickverfolgung´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);

Istmeldung

Verwenden Sie diesen Umfang für asynchrone Szenarien, in denen InvokeAgentScope, ExecuteToolScope oder InferenceScope die 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 überprüfen

Um zu überprüfen, ob Sie das Einblick SDK erfolgreich integriert haben, untersuchen Sie die von Ihrem Agent generierten Konsolenprotokolle sowie die Protokolle des Einblick 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üssel-Protokollmeldungen:

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, setzen Sie Umgebungsvariablen in .env oder in der Shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Prüfen Sie die Konsolenausgabe auf Meldungen 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

Verwenden Sie ggf. einen benutzerdefinierten Logger, um Exportereignisse in eine Datei zu protokollieren.

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üssel-Protokollmeldungen:

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.

Anmerkung

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

Exportierte Protokolle anzeigen

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

• Microsoft Purview: Auditing muss für Ihre Organisation aktiviert sein. Weitere Informationen unter Überwachung aktivieren oder deaktivieren.
• Microsoft Defender: Erweitertes Hunting muss konfiguriert werden, um auf die CloudAppEvents-Tabelle zugreifen zu können. Weitere Informationen finden Sie in der CloudAppEvents-Tabelle im erweiterten Hunting-Schema.

Validierung für Store-Veröffentlichung

Wichtig

Damit die Validierung im Store erfolgreich ist, muss Ihr Agent die Umfänge InvokeAgentScope, InferenceScope und ExecuteToolScope implementieren. Diese drei Umfänge sind für die Veröffentlichung erforderlich.

Überprüfen Sie vor der Veröffentlichung mithilfe von Konsolenprotokollen die Funktionsfähigkeit Ihrer Einblick-Integration für den Agent, indem Sie die erforderlichen invoke agent, execute tool, inference, und output-Umfänge implementieren. Vergleichen Sie dann die Protokolle Ihres Agents mit den folgenden Attributlisten, um sicherzustellen, dass alle erforderlichen Attribute vorhanden sind. Erfassen Sie Attribute in jedem Umfang oder über den Baggage-Builder und fügen Sie optionale Attribute nach eigenem Ermessen hinzu.

Weitere Informationen zu den Anforderungen für die Veröffentlichung im Store finden Sie unter Store-Validierungsrichtlinien.

InvokeAgentScope-Attribute

Die folgende Liste fasst die erforderlichen und optionalen Telemetrieattribute zusammen, die aufgezeichnet werden, wenn Sie einen InvokeAgentScope starten.

"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 aufgezeichnet werden, wenn Sie einen ExecuteToolScope starten.

"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 aufgezeichnet werden, wenn Sie einen InferenceScope starten.

"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 aufgezeichnet werden, wenn Sie einen OutputScope starten. Verwenden Sie diesen Umfang in asynchronen Szenarien, in denen das übergeordnete Element 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 Ihres Agents mit Einblick

Testen Sie nach der Implementierung von Einblick in Ihrem Agent, um sicherzustellen, dass Telemetrie ordnungsgemäß erfasst wird. Folgen Sie der Testanleitung, um Ihre Umgebung einzurichten. Konzentrieren Sie sich anschließend vor allem auf den Abschnitt Einblick-Protokolle anzeigen, um zu überprüfen, ob Ihre Einblick-Implementierung wie erwartet funktioniert.

Überprüfung:

• Wechseln 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 Einblick.

Problem	Beschreibung des Dataflows
Einblicksdaten werden nicht angezeigt	Keine Telemetrie ist sichtbar, weil der Export nicht aktiviert ist, die Konfiguration falsch ist oder die Token-Auflösung fehlschlägt.
Fehlende Mandanten-ID oder Agent-ID – Spans übersprungen	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	Exportvorgänge schlagen fehl oder werden übersprungen, wenn der Resolver kein Token zurückgibt oder eine Ausnahme auftritt.
HTTP 401 – nicht autorisiert	Die Authentifizierung verläuft syntaktisch erfolgreich, aber das Token ist für die Ingestion aufgrund von Umfang, Typ oder Ablaufdatum ungültig.
HTTP 403 – verboten	Der Zugriff wird aufgrund von Lizenzlücken bei Mandanten oder fehlenden Einblick-Berechtigungen verweigert.
HTTP 403 verboten - Agent-ID stimmt nicht überein	Die Anfrage wird abgelehnt, wenn die Agentidentität in der URL nicht mit der durch das Token repräsentierten Identität übereinstimmt.
HTTP 429- oder 5xx-Fehler – Transiente Fehler	Vorübergehende Drosselung oder serverseitige Fehler unterbrechen den Export und können eine Anpassung der Wiederholungsparameter erforderlich machen.
Exportzeitüberschreitung	Telemetrie-Batches überschreiten die konfigurierten Timeout-Fenster aufgrund von Netzwerklatenz oder Reaktionsfähigkeit des Endpunkts.
Export war erfolgreich, aber Telemetriedaten werden weder in Defender noch in Purview angezeigt	Die Erfassung wird abgeschlossen, die nachgelagerte Sichtbarkeit wird jedoch durch produktseitige Voraussetzungen verzögert oder blockiert.

Trinkgeld

Die Agent 365 Troubleshooting-Anleitung enthält übergeordnete Empfehlungen zur Fehlerbehebung, Best Practices und Links zu Inhalten zur Fehlerbehebung für jeden Abschnitt des Entwicklungszyklus von Agent 365.

Einblicksdaten werden nicht angezeigt

Symptome:

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

Grundursache:

• Einblick ist nicht aktiviert
• Konfigurationsfehler
• Token Resolver-Probleme

Lösungen: Führen Sie die folgenden Schritte aus, um das Problem zu beheben:

• Überprüfen Sie, ob der Einblick-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. Details zur Konfiguration finden Sie unter Konfiguration.

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

  Der Exporter benötigt einen gültigen Token-Resolver, der für jede Exportanfrage ein Bearer-Token zurückgibt. Wenn der Token-Resolver fehlt oder null zurückgibt, wird der Export stillschweigend übersprungen. Stellen Sie sicher, dass Ihr Code den Token-Resolver korrekt implementiert. Weitere Informationen finden Sie unter Token-Resolver.

• Auf Fehler in den Protokollen prüfen

  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. Weitere Informationen zur Aktivierung der Protokollierung je Plattform finden Sie unter Lokal validieren.

  # 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 Konsolenexporter hinzu und prüfen Sie, ob die Telemetrie lokal generiert wird. Für Details zur Nutzung des Konsolenexporters und zur Validierung der Ausgabe siehe Lokal validieren.

Fehlende Mandanten-ID oder Agent-ID – Abschnitte ü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.

Lö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 Abschnitte angefügt, die innerhalb des Baggage-Bereichs erstellt werden. Weitere Informationen zur plattformspezifischen API finden Sie unter Baggage-Attribute.
• 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 Token-Resolver liefert null zurück oder wirft eine Ausnahme. Je nach SDK wird der Export entweder komplett übersprungen oder die Anfrage wird ohne Autorisierungsheader gesendet und schlägt mit HTTP 401 fehl.

Lösung:

• Der Token-Resolver ist bei der Initialisierung erforderlich. Fehlt er, löst der Exporter beim Start einen Fehler aus. Stellen Sie sicher, dass ein Token-Resolver bereitgestellt wird und ein gültiges Bearer-Token zurückgibt.
• Stellen Sie sicher, dass die richtigen Mandanten-ID und Agent-ID für BaggageBuilder verwendet werden, da diese Werte an den Token Resolver übergeben werden.
• Für Azure-gehostete Agenten stellen Sie sicher, dass die verwaltete Identität über die erforderliche API-Berechtigung für den Einblicke-Scope verfügt.

HTTP 401 – nicht autorisiert

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

Lösung:

• Stellen Sie sicher, dass die Zielgruppe des Tokens mit dem Bereich des Einblick-Endpunkts übereinstimmt.
• Überprüfen Sie, ob der Token-Resolver kein delegiertes Benutzertoken, ein 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.

Grundursache: Ein HTTP-403-Fehler kann verschiedene Ursachen haben. Überprüfen Sie die folgenden Lösungen in der angegebenen Reihenfolge.

Lösung:

• Fehlende Lizenz – Überprüfen Sie, ob Ihrem Mandanten eine der folgenden Lizenzen im Microsoft 365 Admin Center zugewiesen ist:

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

• Fehlende Agent365.Observability.OtelWriteBerechtigung — Wenn Sie Ihre Einblick-Pakete kürzlich aktualisiert haben, müssen Sie diese Berechtigung zuweisen. Beachten Sie den wichtigen Hinweis im nächsten Abschnitt.

Wichtig

Bestehende Agents, die auf diese Paketversionen aktualisiert werden, müssen einen zusätzlichen Schritt durchführen

Dieser Schritt gilt nur, wenn Sie einen bestehenden Agent aufrüsten. Neue Agentinstallationen erfordern diesen Schritt nicht. Wenn Sie auf die folgenden oder neueren Paketversionen aktualisieren, müssen Sie Ihrer Identität (Managed Identity oder App-Registrierung) die neue Agent365.Observability.OtelWrite Berechtigung zuweisen. Ohne diese Berechtigung schlägt der Telemetrie-Export 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 ein Konto einer global administrierenden Person; aufgeführt vom Agentprojektverzeichnis, das a365.config.json enthält oder verwenden Sie --agent-name)

a365 setup permissions bot

Oder ohne Konfigurationsdatei:

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

Dieser Befehl gewährt alle fehlenden Berechtigungen für den Blueprint, einschließlich der Einblick-Bereiche.

Option B — Entra Portal (keine Konfigurationsdateien erforderlich; erfordert globalen Administrator-Zugriff auf die Blueprint-App-Registrierung)

1. Gehen Sie zu Entra-Portal>App-Registrierungen> und wählen Sie Blueprint-App.
2. Navigieren Sie zu API-Berechtigungen>,Berechtigung hinzufügen>APIs, die von meiner Organisation verwendet werden>, suchen Sie nach 9b975845-388f-4429-889e-eab1ef63949c.
3. Wählen Sie Delegierte Berechtigungen> aus, setzen Sie ein Häkchen bei Agent365.Observability.OtelWrite>Berechtigungen hinzufügen.
4. Wiederholen Sie Schritte 2–3, wählen Sie diesmal Anwendungsberechtigungen> aus, setzen Sie ein Häkchen bei Agent365.Observability.OtelWrite>Berechtigungen hinzufügen.
5. Klicken Sie auf Administratoreinwilligung gewähren gewähren und bestätigen.

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

HTTP 403 Forbidden — Agent-ID stimmt nicht überein

Symptome: Der Export schlägt mit HTTP 403 und einer Servernachricht fehl, die ähnlich ist wie 403 Forbidden bei agent-ID-mismatch Fehlern beim Aufruf der Agent 365 Ablauf-Endpunkte.

Hauptursache: Dieser Fehler tritt auf, wenn Sie die Blueprint-Client-ID anstelle der Agent-Instanz-Client-ID bei der Einstellung der Agentendetails verwenden. Die Agenten-ID in der Export-URL stimmt nicht mit der vom Token autorisierten Identität überein, sodass der Ablauf-Endpunkt die Anfrage ablehnt.

Lösung:

• Überprüfen Sie, ob die Mandanten-ID zur Liste der für die Trace-Erfassung zugelassenen Mandanten in Agent 365 hinzugefügt wurde.
• Geben Sie die Agentendetails mit der Agent-Instanz-Client-ID an (nicht die Blueprint-Client-ID).
• Überprüfen Sie die generierte Export-URL - sie wird protokolliert, wenn Sie Ihren Logger aktivieren. Überprüfen Sie, ob die Agent-ID in der URL mit der Client-ID der Agent-Instanz übereinstimmt.
• Um die diagnostische Protokollierung für jedes SDK zu aktivieren, siehe Lokal validieren.

HTTP 429- oder 5xx-Fehler – Transiente Fehler

Symptome: Der Export scheitert mit einem vorübergehenden HTTP-Statuscode wie 429 oder 5xx.

Lösung:

• Diese Fehler sind in der Regel vorübergehend und beheben sich von allein. 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 versucht es nicht automatisch erneut.
• Sollten die Fehler weiterhin auftreten, überprüfen Sie das Service-Health-Dashboard.
• Erwägen Sie, die Exportfrequenz zu reduzieren, indem Sie die geplante Verzögerung zwischen den Batches erhöhen oder die maximale Export-Batchgröße vergrößern. Für Konfigurationsoptionen pro Plattform siehe die Agent365ExporterOptions Tabelle in Konfiguration.

Exportzeitüberschreitung

Symptome: Exportversuche laufen ab.

Lösung:

• Überprüfen Sie die Netzwerkverbindung zum Einblick-Endpunkt.
• Die Standardeinstellungen für Timeouts variieren je nach Plattform. Die Standard-HTTP-Anforderung 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. Für die genauen Eigenschaften und Standardwerte je Plattform siehe die Agent365ExporterOptions Tabelle in Konfiguration.
• Wenn Timeouts häufig auftreten, erhöhen Sie den relevanten Timeout-Wert in Ihren Exportoptionen.

Export war erfolgreich, aber Telemetriedaten werden weder in Defender noch in Purview angezeigt

Symptome: Protokolle zeigen einen erfolgreichen Export, aber Telemetrie ist in Microsoft Defender oder Microsoft Purview nicht sichtbar.

Lösung:

• Stellen Sie sicher, dass Sie die Voraussetzungen für die Anzeige exportierter Protokolle erfüllen. Für Purview muss die Audit-Funktion aktiviert sein. Für Defender müssen Sie Advanced Hunting konfigurieren. Weitere Informationen finden Sie unter Exportierte Protokolle anzeigen.
• Nach einem erfolgreichen Export kann es mehrere Minuten dauern, bis die Telemetrie angezeigt wird. Warten Sie, bis die Daten verfügbar sind, bevor Sie weitere Untersuchungen durchführen.

Weitere Informationen zum Testen von Einblick finden Sie unter:

• Testleitfaden – Einblick-Protokolle anzeigen
• Konfigurieren des Einblicks

Zugehöriger Inhalt

• Agent 365 Einblickkonzepte – Datenfluss, Identitätsmodelle, Authentifizierung, Umfang und Grenzwerte, die für jeden Integrationspfad gelten.
• Referenz des Einblick-Attributs für Agent 365 – kanonisches Schema für Bereichsattribute, dem jeder von Agent 365 erfasste Bereich entsprechen muss.
• Microsoft OpenTelemetry Distro – Das empfohlene einheitliche SDK für neue Integrationen.