Waarneembaarheid-SDK

Belangrijk

Om waarneembaarheid in Agent 365 in te schakelen, gebruikt u de Microsoft OpenTelemetry Distro. Deze distributie biedt één enkele waarneembaar-SDK binnen Microsoft, die Agent 365, Microsoft Foundry, Azure Monitor en meer ondersteunt. De bestaande aanpak die in dit artikel wordt beschreven blijft werken zonder belangrijke wijzigingen. Zie voor migratierichtlijnen per taal de volgende gidsen:

Handleiding voor Python-migratie
JavaScript/TypeScript-migratiegids
.NET-migratiegids Zie voor het onderliggende datamodel, de identiteit en de verificatie, bereiken en toestemming, en limieten – die op elk integratiepad van toepassing zijn – Agent 365-waarneembaarheidsconcepten.

Notitie

Waarneembaarheid is een van de incrementele capaciteitsniveaus in Aan de slag met Agent 365-ontwikkeling en is van toepassing op alle agenttypes.

Als u wilt deelnemen aan het ecosysteem van Agent 365, voegt u Agent 365-waarneembaarheidsmogelijkheden toe aan uw agent. De Agent 365-waarneembaarheid bouwt voort op OpenTelemetry (OTel) en biedt een geïntegreerd kader voor het consistent en veilig vastleggen van telemetrie op alle agentplatforms. Door dit vereiste onderdeel te implementeren, kunnen IT-beheerders de activiteit van uw agent in het Microsoft-beheercentrum bewaken en beveiligingsteams toestaan Defender en Purview te gebruiken, voor naleving en detectie van bedreigingen.

Belangrijkste voordelen

End-to-end zichtbaarheid: leg uitgebreide telemetrie vast voor elke aanroep van agenten, inclusief sessies, hulpprogramma-aanroepen en uitzonderingen, zodat u volledig traceerbaar bent op verschillende platforms.
Beveiligings- en nalevingsinschakeling: voer geïntegreerde auditlogboeken in Defender en Purview in, waardoor geavanceerde beveiligingsscenario's en nalevingsrapportage voor uw agent mogelijk zijn.
Platformoverschrijdende flexibiliteit: bouw op OTel-standaarden en ondersteun diverse runtimes en platforms zoals Copilot Studio, Foundry en toekomstige agentkaders.
Operationele efficiëntie voor beheerders: gecentraliseerde waarneembaarheid bieden in Microsoft 365-beheercentrum, het verminderen van de tijd voor probleemoplossing en het verbeteren van governance met op rollen gebaseerde toegangsbeheer, voor IT-teams die uw agent beheren.

Ondersteunde agents

De volgende agenttypes ondersteunen Agent 365-waarneembaarheid:

Agents met Microsoft Agent 365-ondersteuning: gebruik de waarneembaarheids-SDK om uw agent te instrumenteren.
Aangepaste engineagenten: gebruik de waarneembaarheids-SDK om uw agent te instrumenteren.
Declaratieve agenten: waarneembaarheid wordt standaard ondersteund. Er is geen SDK-implementatie vereist.

Installatie

Gebruik deze opdrachten om de waarneembaarheidsmodules te installeren voor de talen die worden ondersteund door Agent 365.

Installeer de kernwaarneembaarheids- en runtimepakketten. Alle agenten die Agent 365-waarneembaarheid gebruiken, hebben deze pakketten nodig.

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

Als uw agent het Microsoft Agents Hosting-pakket gebruikt, installeer dan het hosting-integratiepakket. Het biedt middleware die automatisch bagage en bereiken aanvult vanuit de TurnContext, en bevat een tokencache voor de waarneembaarheidsexporter.

pip install microsoft-agents-a365-observability-hosting

Als uw agent een van de ondersteunde AI-kaders gebruikt, installeer dan de bijbehorende auto-instrumentatie-extensie om automatisch telemetrie vast te leggen zonder handmatige instrumentatiecode. Zie voor configuratiedetails Automatische instrumentatie.

# 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

Installeer de kernwaarneembaarheids- en runtimepakketten. Alle agenten die Agent 365-waarneembaarheid gebruiken, hebben deze pakketten nodig.

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

Als uw agent het @microsoft/agents-hosting-pakket gebruikt, installeer dan het hostingintegratiepakket. Het biedt middleware die automatisch bagage en bereiken aanvult vanuit de TurnContext, en bevat een tokencache voor de waarneembaarheidsexporter.

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

Installeer het kernwaarneembaarheids- en runtimepakket. Alle agenten die Agent 365-waarneembaarheid gebruiken, hebben dit pakket nodig.

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

Als uw agent het Microsoft.Agents.A365.Observability.Hosting NuGet-pakket gebruikt, installeer dan het hostingintegratiepakket. Het biedt middleware die automatisch bagage uit de TurnContext aanvult en omvat tokencaching voor de waarneembaarheidsexporter.

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

Configuratie

Gebruik de volgende instellingen om Agent 365-waarneembaarheid voor uw agent in te schakelen en aan te passen.

Stel de omgevingsvariabele ENABLE_A365_OBSERVABILITY_EXPORTER in op true voor waarneembaarheid. Deze instelling exporteert logboeken naar de service en vereist dat er een token_resolver moet worden opgegeven. Anders wordt de console-exporter gebruikt.

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

De tokenresolver is uitgesloten van logboekregistratie naar de console.

U kunt het gedrag van de exporter aanpassen door een Agent365ExporterOptions-exemplaar door te geven aan exporter_options. Wanneer exporter_options is opgegeven, heeft deze voorrang boven de parameters token_resolver en 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 de volgende tabel wordt beschreven welke optionele parameters u moet gebruiken voor configure().

Parameter	Omschrijving	Standaard
`logger_name`	Naam van de Python-logger die wordt gebruikt voor debugging en console-loguitvoer.	`microsoft_agents_a365.observability.core`
`exporter_options`	Een `Agent365ExporterOptions`-instantie die zowel de tokenomzetter als de clustercategorie samen configureert.	`None`
`suppress_invoke_agent_input`	Wanneer `True` invoerberichten onderdrukt op `InvokeAgent`-spans.	`False`

In de volgende tabel wordt beschreven welke optionele eigenschappen u moet gebruiken voor Agent365ExporterOptions.

Eigenschap	Omschrijving	Standaard
`use_s2s_endpoint`	Wanneer dit `True` is, gebruikt het het eindpuntpad van de service-to-service.	`False`
`max_queue_size`	Maximale wachtrijgrootte voor de batchprocessor.	`2048`
`scheduled_delay_ms`	Vertraging in milliseconden tussen exportbatches.	`5000`
`exporter_timeout_ms`	Time-out in milliseconden voor de exportbewerking.	`30000`
`max_export_batch_size`	Maximale batchgrootte voor exportbewerkingen.	`512`

Stel de omgevingsvariabele ENABLE_A365_OBSERVABILITY_EXPORTER in op true voor waarneembaarheid. Deze instelling exporteert logboeken naar de service en vereist dat er een tokenresolver wordt opgegeven. Anders wordt de console-exporter gebruikt.

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 alternatief voor omgevingsvariabelen kunt u waarneembaarheid programmatisch configureren met behulp van een configuratieprovider via de withConfigurationProvider-methode. Als u ook individuele builder-methoden gebruikt (zoals withExporterOptions of withClusterCategory), krijgen deze methoden voorrang op waarden uit de configuratieprovider.

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

U kunt het gedrag van de exporter aanpassen door een Agent365ExporterOptions-exemplaar door te geven aan withExporterOptions. Met deze optie kunt u batching, time-outs en de routemodus beheren.

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 de volgende tabel wordt beschreven welke optionele eigenschappen u moet gebruiken voor Agent365ExporterOptions.

Eigenschap	Omschrijving	Standaard
`useS2SEndpoint`	Wanneer dit `true` is, gebruikt het het eindpuntpad van de service-to-service.	`false`
`maxQueueSize`	Maximale wachtrijgrootte voor de batchprocessor.	`2048`
`scheduledDelayMilliseconds`	Vertraging in milliseconden tussen exportbatches.	`5000`
`exporterTimeoutMilliseconds`	Time-out in milliseconden voor de volledige exportbewerking.	`90000`
`httpRequestTimeoutMilliseconds`	Time-out in milliseconden voor elke individuele HTTP-aanvraag naar de back-end.	`30000`
`maxExportBatchSize`	Maximale batchgrootte voor exportbewerkingen.	`512`

U kunt ook een aangepaste logger leveren die de ILogger-interface implementeert (info, warn, error, event). Geef het door aan de builder door withCustomLogger te gebruiken.

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

Stel EnableAgent365Exporter in op true Aan appsettings.json.

Voeg in Program.csAgent365ExporterOptions toe aan de serviceverzameling. Met deze wijziging configureert u de gedelegeerde, die de traceringsexporteur gebruikt om het token op te halen.

Voeg waarneembaarheidsgerelateerde afhankelijkheden toe met behulp van 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();

U kunt het gedrag van de exporter aanpassen door een configure delegate- en exporter-type mee te geven aan AddA365Tracing().

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

In de volgende tabel wordt beschreven welke optionele eigenschappen u moet gebruiken voor Agent365ExporterOptions.

Eigenschap	Omschrijving	Standaard
`UseS2SEndpoint`	Wanneer dit `true` is, gebruikt het het eindpuntpad van de service-to-service.	`false`
`MaxQueueSize`	Maximale wachtrijgrootte voor de batchprocessor.	`2048`
`ScheduledDelayMilliseconds`	Vertraging in milliseconden tussen exportbatches.	`5000`
`ExporterTimeoutMilliseconds`	Time-out in milliseconden voor de exportbewerking.	`30000`
`MaxExportBatchSize`	Maximale batchgrootte voor exportbewerkingen.	`512`

Bagagekenmerken

Gebruik BaggageBuilder om contextuele informatie in te stellen, die door alle spans in een aanvraag loopt. De SDK implementeert een SpanProcessor die alle niet-lege bagageposten naar nieuw gestarte spans kopieert, zonder bestaande kenmerken te overschrijven.

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

Gebruik de populate helper in het microsoft-agents-a365-observability-hosting-pakket om de BaggageBuilder automatisch in te vullen vanuit de TurnContext. Deze helper haalt automatisch de details van beller, agent, tenant, kanaal en gesprek uit de activiteit.

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

Gebruik de fromTurnContext helper in het @microsoft/agents-a365-observability-hosting-pakket om de BaggageBuilder automatisch in te vullen vanuit de TurnContext. Deze helper haalt automatisch de details van beller, agent, tenant, kanaal en gesprek uit de activiteit.

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.

Gebruik de extensiemethode FromTurnContext in het pakket Microsoft.Agents.A365.Observability.Hosting om de BaggageBuilder automatisch te vullen op basis van de ITurnContext. Deze methode haalt automatisch details van beller, agent, tenant, kanaal en gesprek uit de activiteit.

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

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

Bagage-middleware

Wanneer uw agent het hostingintegratiepakket gebruikt, registreert u bagage-middleware om bagage automatisch in te vullen voor iedere binnenkomende aanvraag. Deze stap zorgt dat het niet langer nodig is om BaggageBuilder handmatig aan te roepen in elke activiteitenhandler.

Registreer BaggageMiddleware op de adapter-middlewareset. Dit haalt automatisch details van beller, agent, tenant, kanaal en gesprek uit iedere binnenkomende TurnContext en verpakt de aanvraag in een bagagebereik.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Gebruik ObservabilityHostingManager om bagage-middleware te configureren samen met andere hostingfuncties:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

De middleware slaat het instellen van bagage over voor asynchrone antwoorden (ContinueConversation-gebeurtenissen) om te voorkomen dat bagage die door het oorspronkelijke verzoek is ingesteld, wordt overschreven.

Registreer BaggageMiddleware in de adapter. Dit haalt automatisch details van beller, agent, tenant, kanaal en gesprek uit iedere binnenkomende TurnContext en verpakt de aanvraag in een bagagebereik.

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

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

Gebruik ObservabilityHostingManager om bagage-middleware te configureren samen met andere hostingfuncties:

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

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

Registreer BaggageTurnMiddleware in de adapter. Dit haalt automatisch details van beller, agent, tenant, kanaal en gesprek uit iedere binnenkomende ITurnContext en verpakt de aanvraag in een bagagebereik.

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

adapter.Use(new BaggageTurnMiddleware());

Als u bagage op HTTP-niveau nodig hebt (bijvoorbeeld om tenant- en agent-id's in te stellen voordat de Bot Framework-pijplijn wordt uitgevoerd), registreer dan ObservabilityBaggageMiddleware in de ASP.NET Core-pijplijn met behulp van de extensiemethode UseObservabilityRequestContext. U moet een omzetterfunctie opgeven die de tenant-id en agent-id uit de HTTP-context haalt.

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

Tokenomzetter

Wanneer u de Agent 365-exporter gebruikt, moet u een tokenomzettingsfunctie opgeven, die een verificatietoken retourneert. Wanneer u de Agent 365-waarneembaarheids-SDK gebruikt met het Agent Hosting Framework, kunt u tokens genereren met behulp van TurnContext vanuit agentactiviteiten.

In het volgende fragment ziet u hoe u een token genereert met behulp van de microsoft_agents.hosting.core SDK. Het hier gegenereerde verificatietoken wordt gebruikt om de spans naar de A365-opnameservice te exporteren. Agenten kunnen zelf een token genereren, bijvoorbeeld door Microsoft Authentication Library (MSAL) te gebruiken, maar ze moeten ervoor zorgen dat het token het waarneembaarheidsbereik heeft.

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

Gebruik voor een agent die is gebouwd met de A365 CLI en gebruikmaakt van een AI-teamlid en het Microsoft Agent 365 Observability Hosting Library-pakket, AgenticTokenCache om tokencaching automatisch te verwerken. Registreer het token één keer per agent en tenant tijdens een activiteithandler en geef cache.get_observability_token op als token_resolver in uw waarneembaarheidsconfiguratie.

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

In het volgende fragment ziet u hoe u een token genereert met behulp van de @microsoft/agents-hosting SDK. Het hier gegenereerde verificatietoken wordt gebruikt om de spans naar de A365-opnameservice te exporteren. Agenten kunnen zelf een token genereren, bijvoorbeeld door Microsoft Authentication Library (MSAL) te gebruiken, maar ze moeten ervoor zorgen dat het token het waarneembaarheidsbereik heeft.

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

Gebruik voor een agent die is gebouwd met de A365 CLI en een AI-teamlid en het @microsoft/agents-a365-observability-hosting-pakket gebruikt, AgenticTokenCacheInstance om tokencaching automatisch te verwerken. Roep RefreshObservabilityToken eenmaal per agent en tenant tijdens een activiteithandler aan en geef AgenticTokenCacheInstance.getObservabilityToken door als tokenResolver in uw waarneembaarheidsconfiguratie.

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

Het volgende codefragment laat zien hoe u een token kunt genereren met behulp van de Microsoft.Agents hosting-SDK. Gebruik het door u gegenereerde verificatietoken om de spans naar de A365-opnameservice te exporteren. Agenten kunnen zelf een token genereren, bijvoorbeeld door Microsoft Authentication Library (MSAL) te gebruiken, maar ze moeten ervoor zorgen dat het token het waarneembaarheidsbereik heeft.

Voorzie in een tokenresolver door Agent365ExporterOptions te registreren met een TokenResolver Delegate. De delegate ontvangt de agentId en tenantId en retourneert een verificatietoken.

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

Als uw agent is gebouwd met de A365 CLI en gebruikmaakt van een AI-teamlid en het Microsoft.Agents.A365.Observability.Hosting NuGet-pakket, gebruik dan de AddAgenticTracingExporter()-methode om het cachen van tokens automatisch te verwerken via dependency injection.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Registreer het token in de agenttoepassing.

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 instrumentatie

Automatische instrumentatie luistert automatisch naar bestaande telemetriesignalen voor traceringen van agentische frameworks (SDK's) en stuurt deze door naar de Agent 365-waarneembaarheidsservice. Door deze functie hoeven ontwikkelaars bewakingscode niet handmatig te schrijven, wat de installatie vereenvoudigt en zorgt voor consistente prestatietracering.

Belangrijk

Auto-instrumentatie vult alleen standaard OTel-kenmerken in. U moet Microsoft-specifieke kenmerken toevoegen via BaggageBuilder. Om te zien welke kenmerken ontbreken, valideert u de output van uw console span met de store-logs van de diff-set.

Automatische instrumentatie wordt ondersteund voor meerdere SDK's en platforms:

Platform	Ondersteunde SDK's/frameworks
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Notitie

Ondersteuning voor automatische instrumentatie verschilt per platform en SDK-implementatie.

Semantic Kernel

Voor automatische instrumentatie is het gebruik van een bagagebouwer vereist. Stel de agent-id en tenant-id in met behulp van BaggageBuilder.

Installeer het pakket.

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

Configureer de waarneembaarheid.

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

Voeg afhankelijkheden toe aan de serviceverzameling.

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

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

Stel AgentId en TenantId in met behulp van BaggageBuilder. Zorg ervoor dat de id die u gebruikt bij het maken van een ChatCompletionAgent, overeenkomt met de agent-id die u doorgeeft aan BaggageBuilder.

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

OpenAI

Voor automatische instrumentatie is het gebruik van een bagagebouwer vereist. Stel de agent-id en tenant-id in met behulp van BaggageBuilder.

Installeer het pakket.

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

Configureer de waarneembaarheid.

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

Installeer het pakket.

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

Configureer de waarneembaarheid.

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

Voeg afhankelijkheden toe aan de serviceverzameling.

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

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

Stel AgentId en TenantId in met behulp van BaggageBuilder. Voor aanroepen van hulpprogramma's start u een tracering met behulp van Trace() op een ChatToolCall-exemplaar.

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

Voor automatische instrumentatie is het gebruik van een bagagebouwer vereist. Stel de agent-id en tenant-id in met behulp van BaggageBuilder.

Installeer het pakket.

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

Configureer de waarneembaarheid.

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

Voeg afhankelijkheden toe aan de serviceverzameling.

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

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

Stel AgentId en TenantId in met behulp van 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

Voor automatische instrumentatie is het gebruik van een bagagebouwer vereist. Stel de agent-id en tenant-id in met behulp van BaggageBuilder.

Installeer het pakket.

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

Configureer de waarneembaarheid.

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

Installeer het pakket.

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

Configureer de waarneembaarheid.

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

Handmatige instrumentatie

Gebruik de Agent 365-waarneembaarheids-SDK om inzicht te krijgen in de interne werking van de agent. De SDK biedt bereiken die u kunt starten: InvokeAgentScope, ExecuteToolScope, InferenceScope en OutputScope.

Agentaanroepen

Gebruik dit bereik aan het begin van het agentproces. Door het aanroepagentbereik te gebruiken kunt u eigenschappen vastleggen, zoals de huidige agent die wordt aangeroepen, agentgebruikersgegevens en meer.

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

Als uw agent het @microsoft/agents-a365-observability-hosting-pakket gebruikt, kunt u met ScopeUtils.populateInvokeAgentScopeFromTurnContext een bereik maken met agent-, beller- en kanaalgegevens die automatisch uit TurnContext worden gehaald.

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

Uitvoering van hulpprogramma

De volgende voorbeelden laten zien hoe u waarneembaarheidstracering toevoegt aan de tooluitvoering van uw agent. Deze tracering legt telemetrie vast voor monitoring- en auditdoeleinden.

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

Als uw agent het @microsoft/agents-a365-observability-hosting-pakket gebruikt, gebruik dan ScopeUtils.populateExecuteToolScopeFromTurnContext om een bereik te creëren met agentdetails die automatisch worden afgeleid van TurnContext.

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

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

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

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

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

Deductie

In de volgende voorbeelden ziet u hoe u aanroepen van AI-modeldeductie kunt instrumenteren met tracering van waarneembaarheid om tokengebruik, modeldetails en metagegevens van responsen vast te leggen.

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

Als uw agent het @microsoft/agents-a365-observability-hosting-pakket gebruikt, kunt u ScopeUtils.populateInferenceScopeFromTurnContext gebruiken om automatisch een bereik te maken met agentdetails die zijn afgeleid van de TurnContext.

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

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

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

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

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

Uitvoer

Gebruik dit bereik voor asynchrone scenario's waarin InvokeAgentScope, ExecuteToolScope of InferenceScope niet synchroon uitvoergegevens kunnen vastleggen. Start OutputScope als een onderliggende span om de laatste uitvoerberichten vast te leggen nadat het bovenliggende bereik is voltooid.

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

Lokaal valideren

Om te verifiëren dat u succesvol hebt geïntegreerd met de waarneembaarheids-SDK, bekijkt u de consolelogboeken die door uw agent zijn gegenereerd en de logboeken van de waarneembaarheids-SDK.

Stel de omgevingsvariabele ENABLE_A365_OBSERVABILITY_EXPORTER in op false. Deze instelling exporteert spans (traceringen) naar de console.

Om exportfouten te onderzoeken, schakelt u uitgebreide logboekregistratie in door de omgevingsvariabele ENABLE_A365_OBSERVABILITY_EXPORTER op true te zetten en debug logging te configureren bij het opstarten van uw toepassing:

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)

Belangrijke logberichten:

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.

Stel de omgevingsvariabele ENABLE_A365_OBSERVABILITY_EXPORTER in op false. Deze instelling exporteert spans (traceringen) naar de console.

Om exportfouten te onderzoeken, stelt u omgevingsvariabelen in .env in of in de shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Bekijk de output van de console voor berichten zoals:

[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

Gebruik eventueel een aangepaste logger om exportgebeurtenissen in een bestand vast te leggen:

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

Stel EnableAgent365Exporter in op false Aan appsettings.json. Deze instelling exporteert spans (traceringen) naar de console.

Om exportfouten te onderzoeken, stelt u uitgebreide logboekregistratie in appsettings.json in:

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

Of stel omgevingsvariabelen in:

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

Belangrijke logberichten:

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.

Notitie

Als u geen ILoggerFactory in DI registreert, valt de exporter automatisch terug op een console-logger.

Geëxporteerde logs bekijken

Als u agenttelemetrie in Microsoft Purview of Microsoft Defender wilt bekijken, zorg er dan voor dat aan de volgende vereisten wordt voldaan:

Microsoft Purview: auditing moet ingeschakeld zijn voor uw organisatie. Ga voor instructies naar Auditing in- of uitschakelen.
Microsoft Defender: geavanceerde opsporing moet worden geconfigureerd om toegang te krijgen tot de CloudAppEvents-tabel. Ga voor details naar de CloudAppEvents-tabel in het geavanceerde opsporingsschema.

Valideren voor publicatie in het archief

Belangrijk

Voor succesvolle archiefvalidatie moet uw agent de bereiken InvokeAgentScope, InferenceScope en ExecuteToolScope implementeren. Deze drie bereiken zijn vereist voor publicatie.

Valideer vóór publicatie met consolelogboeken uw waarneembaarheidsintegratie voor de agent door de vereiste bereiken invoke agent, execute tool, inference en output te implementeren. Vergelijk vervolgens de logboeken van uw agent met de onderstaande kenmerklijsten om te controleren of alle vereiste kenmerken aanwezig zijn. Registreer attributen per bereik of via de bagage-builder en voeg optionele kenmerken toe naar eigen inzicht.

Zie voor meer informatie over de vereisten voor publicatie in het archief Archiefvalidatierichtlijnen.

`InvokeAgentScope`-kenmerken

De volgende lijst bevat de vereiste en optionele telemetriekenmerken die worden vastgelegd wanneer u een InvokeAgentScope start.

"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`-kenmerken

De volgende lijst bevat de vereiste en optionele telemetriekenmerken die worden vastgelegd wanneer u een ExecuteToolScope start.

"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`-kenmerken

De volgende lijst bevat de vereiste en optionele telemetriekenmerken die worden vastgelegd wanneer u een InferenceScope start.

"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`-kenmerken

De volgende lijst bevat de vereiste en optionele telemetriekenmerken die worden vastgelegd wanneer u een OutputScope start. Gebruik dit bereik scope voor asynchrone scenario's waarin het bovenliggende bereik de uitvoergegevens niet synchroon kan registreren.

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

Uw agent testen met waarneembaarheid

Nadat u waarneembaarheid in uw agent hebt geïmplementeerd, test u deze om te controleren dat telemetrie correct wordt vastgelegd. Volg de testgids om uw omgeving in te stellen. Richt u vervolgens voornamelijk op de sectie Waarneembaarheidslogboeken weergeven om te controleren of uw waarneembaarheidsimplementatie werkt zoals verwacht.

Verificatie:

Ga naar https://admin.cloud.microsoft/#/agents/all
Selecteer uw agent > Activiteit
U ziet sessies en toolaanroepen

Probleemoplossing

Deze sectie beschrijft veelvoorkomende problemen bij het implementeren en gebruiken van waarneembaarheid.

Probleem	Omschrijving
Waarneembaarheidsgegevens zijn niet zichtbaar	Er is geen telemetrie zichtbaar omdat exporteren niet is ingeschakeld, de configuratie onjuist is, of de tokenomzetting mislukt.
Ontbrekende tenant-id of agent-id - spans overgeslagen	Spans worden overgeslagen vóór export wanneer identiteitskenmerken die nodig zijn voor partitionering, ontbreken.
Tokenresolutiefout - export overgeslagen of ongeautoriseerd	Exportverzoeken mislukken of worden overgeslagen wanneer de omzetter geen token teruggeeft of een uitzondering tegenkomt.
HTTP 401 Niet-geautoriseerd	Verificatie slaagt syntactisch, maar het token is ongeldig voor opname vanwege bereik, type of vervaldatum.
HTTP 403 Verboden	Toegang wordt geweigerd vanwege ontbrekende tenantlicenties of waarneembaarheidsrechten.
HTTP 403 Verboden - Agent-id komt niet overeen	Het verzoek wordt afgewezen wanneer de agentidentiteit in de URL niet overeenkomt met de identiteit die door het token wordt weergegeven.
HTTP 429 of 5xx-fouten - tijdelijke fouten	Tijdelijke throttling of storingen aan de serverzijde onderbreken de export en kunnen een aanpassing van de instellingen voor opnieuw proberen vereisen.
Exporttime-out	Telemetriebatches overschrijden de geconfigureerde time-outvensters door netwerklatentie of een trage respons van het eindpunt.
Export slaagt, maar telemetrie verschijnt niet in Defender of Purview	De gegevensopname is voltooid, maar de zichtbaarheid verderop in het proces wordt vertraagd of geblokkeerd door productvereisten.

Fooi

De Gids voor probleemoplossing in Agent 365 bevat aanbevelingen voor probleemoplossing op hoog niveau, best practices en links naar relevante probleemoplossingsinformatie voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

Waarneembaarheidsgegevens zijn niet zichtbaar

Symptomen:

Agent wordt uitgevoerd
Geen telemetrie in het beheercentrum
Kan de activiteit van de agent niet zien

Hoofdoorzaak:

Waarneembaarheid is niet ingeschakeld
Configuratiefouten
Problemen met tokenomzetter

Oplossingen: probeer de volgende stappen uit om het probleem op te lossen:

Controleer of de waarneembaarheidsexporter is ingeschakeld

U moet de Agent 365-exporter expliciet inschakelen. Wanneer deze is uitgeschakeld, schakelt de SDK over op de console-exporter en wordt telemetrie niet naar de service verzonden. Zie Configuratie voor configuratiedetails.
Controleer de configuratie van de tokenomzetter

De exporter vereist een geldige tokenomzetter die voor elk exportverzoek een Bearer-token oplevert. Als de tokenomzetter ontbreekt of null teruggeeft, wordt de export stilzwijgend overgeslagen. Zorg ervoor dat uw code de tokenresolver correct implementeert. Zie voor meer informatie Tokenomzetter.
Controleren op fouten in logboeken

Schakel uitgebreide logboekregistratie in en gebruik de az webapp log tail-opdracht om logboeken te doorzoeken op fouten met betrekking tot waarneembaarheid. Zie voor details over hoe u logboekregistratie per platform kunt inschakelen Lokaal valideren.
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
Telemetrie-export verifiëren

Bevestig dat telemetrie wordt gegenereerd en geëxporteerd zoals verwacht.
- Voeg een console-exporter toe en controleer of telemetrie lokaal wordt gegenereerd. Zie voor details over het gebruik van de console-exporter en het valideren van de uitvoer Lokaal valideren.

Ontbrekende tenant-id of agent-id; spans overgeslagen

Symptomen: het systeem verwijdert spans zonder melding en exporteert ze nooit. Sommige SDK's loggen een aantal overgeslagen spans of een bericht zoals "Geen spans met tenant/agent-identiteit gevonden." Andere laten ze weg zonder logboekregistratie.

Oplossing:

Voor het exporteren partitioneert de SDK spans op basis van tenant-id en agent-id. Het systeem verwijdert spans die geen tenant-id of agent-id hebben en stuurt ze nooit naar de service.
Zorg ervoor dat BaggageBuilder is ingesteld met de tenant-id en agent-id voordat u spans aanmaakt. Deze waarden worden doorgegeven via de OpenTelemetry-context en worden gekoppeld aan alle spans die binnen het bagage-bereik worden gecreëerd. Zie Bagagekenmerken voor de platformspecifieke API.
Bevestig dat de TurnContext-activiteit een geldige ontvanger met agentidentiteit heeft als u de bagage-middleware of de beurtcontexthelper uit het hostingintegratiepakket gebruikt om die id's toe te wijzen.

Tokenresolutiefout: export overgeslagen of ongeautoriseerd

Symptomen: de tokenomzetter geeft null weer of geeft een foutmelding. Afhankelijk van de SDK wordt de export ofwel volledig overgeslagen of wordt het verzoek zonder autorisatieheader verzonden en mislukt het met HTTP 401.

Oplossing:

De tokenresolver is vereist bij initialisatie. Als deze ontbreekt, geeft de exporter bij het opstarten een foutmelding. Controleer of er een tokenomzetter aanwezig is en een geldige Bearer-token retourneert.
Zorg ervoor dat de juiste tenant-id en agent-id worden gebruikt voor BaggageBuilder, want deze waarden worden doorgegeven aan de tokenomzetter.
Voor door Azure gehoste agents controleert u of de Beheerde identiteit de vereiste API-toestemming heeft voor het waarneembaarheidsbereik.

HTTP 401 Niet-geautoriseerd

Symptomen: exporteren met HTTP 401 mislukt. De exporter herhaalt de export niet na deze fout.

Oplossing:

Controleer of de tokendoelgroep overeenkomt met het bereik van het waarneembaarheidseindpunt.
Controleer of de tokenomzetter geen token van een gemachtigde gebruiker, een token voor een verkeerde doelgroep of een verlopen token teruggeeft.

HTTP 403 Verboden

Symptomen: exporteren met HTTP 403 mislukt. De exporter herhaalt de export niet na deze fout.

Hoofdoorzaak: een HTTP 403-fout kan verschillende oorzaken hebben. Bekijk de volgende oplossingen op volgorde.

Oplossing:

Ontbrekende licentie: controleer of uw tenant een van de volgende licenties toegewezen heeft gekregen in het Microsoft 365-beheercentrum:
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
Ontbrekende Agent365.Observability.OtelWrite-machtiging: als u onlangs uw waarneembaarheidspakketten hebt geüpgraded, moet u deze machtiging verlenen. Zie de belangrijke opmerking in de volgende sectie.

Belangrijk

Bestaande agents die upgraden naar deze pakketversies moeten een extra stap uitvoeren

Deze stap geldt alleen als u een bestaande agent upgradet. Bij nieuwe agentinstallaties is deze stap niet nodig. Als u een bestaande agent bijwerkt naar de volgende pakketversies of nieuwere, moet u de nieuwe Agent365.Observability.OtelWrite-machtiging aan uw identiteit (Managed Identity of app-registratie) verlenen. Zonder deze machtiging mislukt de telemetrie-export met HTTP 403.

Platform	Minimale versie die deze stap vereist
.NET	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

Verleen de machtiging met behulp van een van de volgende opties.

Optie A — Agent 365 CLI (vereist een Global Administrator-account; voer uit vanuit de agentprojectmap waar a365.config.json staat, of gebruik --agent-name)

a365 setup permissions bot

Of zonder configuratiebestand:

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

Deze opdracht kent alle ontbrekende machtigingen toe op de blauwdruk, inclusief de waarneembaarheidsbereiken.

Optie B — Entra Portal (geen configuratiebestanden nodig; vereist Global Administrator-toegang tot de blauwdrukappregistratie)

Ga naar Entra portal>App-registraties> selecteer uw Blueprint-app.
Ga naar API-machtigingen>Machtiging toevoegen>API's die door mijn organisatie worden gebruikt> zoek naar 9b975845-388f-4429-889e-eab1ef63949c.
Selecteer Gedelegeerde machtigingen>, controleer Agent365.Observability.OtelWrite>Machtigingen toevoegen.
Herhaal stap 2–3, selecteer deze keer Toepassingsmachtigingen> en vink Agent365.Observability.OtelWrite>Machtigingen toevoegen aan.
Klik op Beheerderstoestemming verlenen en bevestig.

Zowel Agent365.Observability.OtelWrite (Gedelegeerd) als Agent365.Observability.OtelWrite (Toepassing) moeten de status Granted tonen.

HTTP 403 Verboden - Agent-id komt niet overeen

Symptomen: export mislukt met HTTP 403 en een serverbericht vergelijkbaar met 403 Forbidden, met agent-ID-mismatch-fouten bij het aanroepen van eindpunten van Agent 365 traceringen.

Hoofdoorzaak: deze fout treedt op als u de client-id van de blauwdruk gebruikt in plaats van de client-id van het agentexemplaar tijdens het instellen van de agentdetails. De agent-ID in de export-URL komt niet overeen met de door het token geverifieerde identiteit, waardoor het traceringeneindpunt het verzoek afwijst.

Oplossing:

Controleer of de tenant-id is opgenomen in de door Agent 365 toegestane tenantlijst.
Stel de agentgegevens in met de client-id van het agentexamplaar (niet de client-id van de blauwdruk).
Controleer de gegenereerde export-URL, deze wordt geregistreerd als u uw registratie inschakelt. Bevestig dat de agent-id in de URL overeenkomt met de client-id van de agentinstantie.
Zie als u diagnostische logboekregistratie per SDK wilt inschakelen Lokaal valideren.

HTTP 429 of 5xx-fouten - tijdelijke fouten

Symptomen: exporteren mislukt door een tijdelijke HTTP-statuscode zoals 429 of 5xx.

Oplossing:

Deze fouten zijn meestal tijdelijk en lossen vanzelf op. De Python- en JavaScript-SDK's voeren automatisch een nieuwe poging uit op HTTP 408-, 429- en 5xx-statuscodes, maximaal drie keer met exponentiële backoff. De .NET-SDK probeert het niet automatisch opnieuw.
Als er fouten blijven optreden, controleert u het servicestatusdashboard van de service.
Overweeg om de exportfrequentie te verlagen door de geplande vertraging tussen batches te verhogen of de maximale exportbatchgrootte te vergroten. Zie voor configuratieopties per platform de tabel Agent365ExporterOptions in Configuratie.

Exporttime-out

Symptomen: exportpogingen lopen vast door time-out.

Oplossing:

Controleer de netwerkconnectiviteit naar het waarneembaarheidseindpunt.
Standaardtime-outs verschillen per platform. De standaardtime-out voor HTTP-verzoeken is 30 seconden. Sommige SDK's hebben ook een aparte, algemene exporter-time-out die de volledige exportcyclus, inclusief herhalingen, omvat. Zie de tabel Agent365ExporterOptions in Configuratie voor de exacte eigenschappen en standaardwaarden per platform.
Als time-outs vaak voorkomen, verhoog dan de relevante time-outwaarde in uw exporteropties.

Export slaagt, maar telemetrie verschijnt niet in Defender of Purview

Symptomen: Logboeken tonen een succesvolle export, maar telemetrie is niet zichtbaar in Microsoft Defender of Microsoft Purview.

Oplossing:

Controleer of u aan de vereisten voldoet om geëxporteerde logboeken te bekijken. Voor Purview moet auditing ingeschakeld zijn. Voor Defender moet u geavanceerde opsporing configureren. Zie voor meer informatie Geëxporteerde logboeken weergeven.
Telemetrie kan enkele minuten duren voordat dit zichtbaar wordt na een succesvolle export. Wacht tot de gegevens verschijnen voordat u verder onderzoek doet.

Zie voor meer informatie over het testen van waarneembaarheid:

Agent 365-waarneembaarheidsconcepten: datastroom, identiteitsmodellen, verificatie, bereiken en limieten die voor elk integratiepad gelden.
Kenmerkreferentie voor Agent 365-waarneembaarheid: kenmerkschema voor kanonieke span waaraan elke door Agent 365 ingevoerde span moet voldoen.
Microsoft OpenTelemetry Distro – De aanbevolen geharmoniseerde SDK voor nieuwe integraties.

Feedback

Is deze pagina nuttig?

Last updated on 2026-07-30

Waarneembaarheid-SDK

Belangrijkste voordelen

Ondersteunde agents

Installatie

Configuratie

Bagagekenmerken

Bagage-middleware

Tokenomzetter

Automatische instrumentatie

Semantic Kernel

OpenAI

Agent Framework

LangChain Framework

Handmatige instrumentatie

Agentaanroepen

Uitvoering van hulpprogramma

Deductie

Uitvoer

Lokaal valideren

Geëxporteerde logs bekijken

Valideren voor publicatie in het archief

InvokeAgentScope-kenmerken

ExecuteToolScope-kenmerken

InferenceScope-kenmerken

OutputScope-kenmerken

Uw agent testen met waarneembaarheid

Probleemoplossing

Waarneembaarheidsgegevens zijn niet zichtbaar

Ontbrekende tenant-id of agent-id; spans overgeslagen

Tokenresolutiefout: export overgeslagen of ongeautoriseerd

HTTP 401 Niet-geautoriseerd

HTTP 403 Verboden

HTTP 403 Verboden - Agent-id komt niet overeen

HTTP 429 of 5xx-fouten - tijdelijke fouten

Exporttime-out

Export slaagt, maar telemetrie verschijnt niet in Defender of Purview

Gerelateerde inhoud

Feedback

Aanvullende resources

`InvokeAgentScope`-kenmerken

`ExecuteToolScope`-kenmerken

`InferenceScope`-kenmerken

`OutputScope`-kenmerken