Agent-Beobachtbarkeit

Wichtig

Sie müssen Teil des vorschauprogramms Frontier sein, um early access zu Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.

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 aktivieren Sie IT-Administratoren, die Aktivitäten Ihres Agents im Microsoft Admin Center zu überwachen und Sicherheitsteams die Verwendung von Defender und Purview für die Compliance- und Bedrohungserkennung zu ermöglichen.

Wesentliche Vorteile

End-to-End-Sichtbarkeit: Erfassen Sie umfassende Telemetrie für jede Agentenaufrufe, einschließlich Sitzungen, Tool-Calls und Ausnahmen, sodass Sie plattformübergreifend vollständig nachverfolgt werden.
Security and compliance enablement: Senden Sie einheitliche Prüfprotokolle an Defender und Purview, und ermöglichen Sie erweiterte Sicherheits-Szenarien und Compliance-Berichterstattung für Ihren Agenten.
Cross-Platform-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.
Operationaleffizienz für Administratoren: Stellen Sie zentrale Observability in Microsoft 365 Admin Center bereit, reduzieren Sie die Problembehandlungszeit und verbessern Sie die Governance mit rollenbasierten Zugriffssteuerungen für IT-Teams, die Ihren Agent 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.

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

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

Wenn Ihr Agent das Hostingpaket Microsoft Agents Hosting verwendet, installieren Sie das Hostingintegrationspaket. Es stellt Middleware bereit, die automatisch „Baggage“ und „Scopes“ aus dem TurnContext befüllt, und umfasst Token-Caching 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

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

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

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

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

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

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

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

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

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

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

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

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

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

Konfiguration

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

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

from microsoft_agents_a365.observability.core import configure

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

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

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

Sie können das Exporterverhalten anpassen, indem Sie eine Agent365ExporterOptions-Instanz an exporter_options weitergeben. Wenn exporter_options bereitgestellt wird, hat es Vorrang vor den Parametern token_resolver und cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

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

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

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

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

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

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

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

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

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

builder.start();

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

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

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

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

builder.start();

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

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

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

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

builder.start();

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

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

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

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

builder.start();

Legen Sie EnableAgent365Exporter auf true in appsettings.json fest.

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

Fügen Sie beobachtbarkeitsbezogene Abhängigkeiten hinzu, indem Sie verwenden AddA365Tracing().

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

var builder = WebApplication.CreateBuilder(args);

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

builder.AddA365Tracing();

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

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

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

Eigentum	Beschreibung	Vorgabe
`UseS2SEndpoint`	Wenn `true`, verwendet den Dienst-zu-Dienst-Endpunktpfad.	`false`
`MaxQueueSize`	Maximale Warteschlangengröße für den Batchprozessor.	`2048`
`ScheduledDelayMilliseconds`	Verzögerung in Millisekunden zwischen Exportbatches.	`5000`
`ExporterTimeoutMilliseconds`	Timeout in Millisekunden für den 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 Gepäckeinträge in neu gestartete Abschnitte kopiert, ohne vorhandene Attribute zu überschreiben.

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

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

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 .

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.

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

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

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

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

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

Tokenlöser

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

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

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

agents_sdk_config = load_configuration_from_env(environ)

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

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

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

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

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

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 @microsoft/agents-a365-observability-hosting, um für einen mit der A365 CLI erstellten Agenten, der einen KI-Teamkollegen und das AgenticTokenCacheInstance-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 Observability-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()
    );
  }
);

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

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

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

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

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

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Registrieren Sie das Token in der Agent-Anwendung.

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

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

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

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

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

Automatische Instrumentierung

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

Mehrere SDKs und Plattformen unterstützen Autoinstrumentierung:

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

Anmerkung

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

Semantischer Kern

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

Installieren des Pakets.

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

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

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

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

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

OpenAI

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

Installieren des Pakets.

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

Installieren des Pakets.

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

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

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

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

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

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

Agenten-Framework

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

Installieren des Pakets.

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

Abhängigkeiten zur Serviceauflistung hinzufügen.

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

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

Setzen Sie AgentId und TenantId durch Verwendung von BaggageBuilder.

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

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

LangChain-Framework

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

Installieren des Pakets.

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

Installieren des Pakets.

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

Manuelle Instrumentierung

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

Agent-Aufruf

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

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

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

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

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

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

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

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

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

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

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

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

        return new AgentResponse { Content = output };
    }
}

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

Werkzeugausführung

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

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)

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

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.

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)

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

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 Bereich, um die endgültigen Ausgabemeldungen aufzuzeichnen, nachdem der übergeordnete Bereich beendet ist.

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

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

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

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

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

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

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

Lokal validieren

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

Legen Sie die Umgebungsvariable ENABLE_A365_OBSERVABILITY_EXPORTER auf false fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in 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.

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

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

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

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

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

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

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

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

Legen Sie EnableAgent365Exporter auf false in appsettings.json fest. Diese Einstellung exportiert Bereiche (Ablaufverfolgungen) in 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.

Anmerkung

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

Anzeigen exportierter Protokolle

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

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

Für die Veröffentlichung im Store validieren

Wichtig

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

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

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

`InvokeAgentScope` Attribute

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

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

`ExecuteToolScope` Attribute

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

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

`InferenceScope` Attribute

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

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

`OutputScope` Attribute

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

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

Testen Sie Ihren Agenten mit Observierbarkeit

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

Überprüfung:

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

Problembehandlung

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

Tipp

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

Observabilitätsdaten erscheinen nicht

Symptome:

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

Grundursache:

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

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

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

Sie müssen den Agent 365-Exporter explizit aktivieren. Wenn 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 Exporter erfordert einen gültigen Tokenlöser, der ein Bearertoken für jede Exportanforderung zurückgibt. Wenn der Tokenlöser fehlt oder zurückgibt null, wird der Export im Hintergrund übersprungen. Stelle sicher, dass dein Code den Token-Resolver korrekt implementiert. Ausführliche Informationen finden Sie unter Token resolver.
Überprüfen Sie auf Fehler in den Logs

Aktivieren Sie 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.

Lö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 Tokenlöser gibt null zurück oder wirft einen Fehler. Je nach SDK wird der Export entweder vollständig übersprungen, oder die Anforderung wird ohne Autorisierungsheader gesendet und schlägt mit HTTP 401 fehl.

Lösung:

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

HTTP 401 nicht autorisiert

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

Lösung:

Überprüfen Sie, ob die Token-Zielgruppe mit dem Observability-Endpunkt-Scope übereinstimmt.
Überprüfen Sie, ob der Tokenlöser kein delegiertes Benutzertoken, kein Token für eine falsche Zielgruppe oder ein abgelaufenes Token zurückgibt.

HTTP 403 – Unzulässig

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

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

Lösung:

Missing license – Vergewissern Sie sich, dass Ihrem Mandanten eine der folgenden Lizenzen in Microsoft 365 Admin Center:
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
Fehlende Agent365.Observability.OtelWrite Berechtigung – Wenn Sie kürzlich ein Upgrade ihrer Observability-Pakete durchgeführt haben, müssen Sie diese Berechtigung erteilen. Weitere Informationen finden Sie unten in der wichtigen Notiz.

Wichtig

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

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

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

Erteilen Sie die Berechtigung mithilfe einer der folgenden Optionen.

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

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

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

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

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

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

HTTP 429 / 5xx – Vorübergehende Fehler

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

Lö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.

Lö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.

Lö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:

Feedback

War diese Seite hilfreich?

Last updated on 2026-04-27

Agent-Beobachtbarkeit

Wesentliche Vorteile

Unterstützte Agents

Installation

Konfiguration

Gepäckattribute

Gepäck-Middleware

Tokenlöser

Automatische Instrumentierung

Semantischer Kern

OpenAI

Agenten-Framework

LangChain-Framework

Manuelle Instrumentierung

Agent-Aufruf

Werkzeugausführung

Schlussfolgerung

Output

Lokal validieren

Anzeigen exportierter Protokolle

Für die Veröffentlichung im Store validieren

InvokeAgentScope Attribute

ExecuteToolScope Attribute

InferenceScope Attribute

OutputScope Attribute

Testen Sie Ihren Agenten mit Observierbarkeit

Problembehandlung

Observabilitätsdaten erscheinen nicht

Fehlende Mandanten-ID oder Agent-ID – übersprungen

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

HTTP 401 nicht autorisiert

HTTP 403 – Unzulässig

HTTP 429 / 5xx – Vorübergehende Fehler

Export-Zeitüberschreitung

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

Feedback

Zusätzliche Ressourcen

`InvokeAgentScope` Attribute

`ExecuteToolScope` Attribute

`InferenceScope` Attribute

`OutputScope` Attribute