Näkyvyyden SDK

Tärkeää

Ota havaittavuus käyttöön Agent 365:ssä Microsoft OpenTelemetry Distron avulla. Tämä jakelu tarjoaa yhden havaittavuuden SDK:n Microsoftin laajuisesti. Se tukee esimerkiksi Agent 365:tä, Microsoft Foundryä ja Azure Monitoria. Tässä artikkelissa kuvataan nykyinen lähestymistapa, joka toimii edelleen ilman yhteensopivuusongelmia. Seuraavissa oppaissa on lisätietoja siirroista kielen mukaan:

Python-siirron opas
JavaScript/TypeScript-siirto-opas
.NET-siirto-opas Lisätietoja taustalla olevasta tietomallista, käyttäjätiedoista ja todennuksesta, laajuudesta ja suostumuksesta sekä jokaista integrointipolkua koskevista rajoituksista on kohdassa Agent 365:n havaittavuuden käsitteet.

Muistiinpano

Havaittavuus on yksi lisäävistä ominaisuustasoista Agent 365:n kehitystyön aloittaminen -kohdassa. Se koskee kaikkia agenttityyppejä.

Jos haluat osallistua Agent 365 -ekosysteemiin, lisää Agent 365:n havaittavuusominaisuudet agenttiin. Agent 365:n havaittavuus perustuu OpenTelemetryyn (OTel) ja tarjoaa yhtenäisen kehyksen telemetrian keräämiseksi johdonmukaisesti ja turvallisesti agentin kaikissa ympäristöissä. Kun tämä pakollinen komponentti toteutetaan, IT-järjestelmänvalvojat voivat seurata agentin aktiviteettia Microsoft-hallintakeskuksessa ja suojaustiimit voivat käyttää Defender- ja Purview-ratkaisuja vaatimustenmukaisuutta ja uhkien havaitsemista varten.

Avainedut

Kokonaisvaltainen näkyvyys: Tallenna kattava telemetria jokaiselle agentin kutsulle, mukaan lukien istunnot, työkalukutsut ja poikkeukset, jolloin eri ympäristöissä on tarjolla täysi jäljitettävyys.
Suojauksen ja vaatimustenmukaisuuden varmistaminen: Toimita yhtenäiset auditointilokit Defenderiin ja Purviewiin, jolloin kehittyneet suojausskenaariot ja vaatimustenmukaisuusraportit voidaan ottaa käyttöön agentille.
Joustavuus eri ympäristöissä: Hyödynnä OTel-standardeja ja tue erilaisia suorituspalveluita ja ympäristöjä, kuten Copilot Studio, Foundry ja tulevaisuuden agenttikehykset.
Toiminnan tehokkuus järjestelmänvalvojia varten: Tarjoa keskitettyä havaittavuutta Microsoft 365 -hallintakeskuksessa. Se nopeuttaa vianmääritystä ja tehostaa agentteja hallitsevien IT-tiimien hallintoa roolipohjaisten käyttöoikeuksien avulla.

Tuetut agentit

Seuraavat agenttityypit tukevat Agent 365 -havaittavuutta:

Microsoft Agent 365:ttä käyttävät agentit: Käytä havaittavuuden SDK:ta agentin ottamisessa käyttöön.
Mukautetun moduulin agentit: Käytä havaittavuuden SDK:ta agentin ottamisessa käyttöön.
Deklaratiiviset agentit: Havaittavuutta tuetaan oletusarvoisesti. SDK-toteutusta ei tarvita.

Asentaminen

Käytä näitä komentoja havaittavuusmoduulien asentamisessa Agent 365:n tukemille kielille.

Asenna ydinhavaittavuus ja suorituksenaikaiset paketit. Kaikki agentit, jotka käyttävät Agent 365:n havaittavuutta, tarvitsevat nämä paketit.

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

Jos agentti käyttää Microsoftin agenttien isännöinti -pakettia, asenna isännöinnin integrointipaketti. Se sisältää väliohjelmiston, joka täyttää automaattisesti baggage-ominaisuudet ja laajuudet kohteesta TurnContext ja lisää tunnuksen välimuistiin tallennuksen havainnoitavuuden vientitoiminnolle.

pip install microsoft-agents-a365-observability-hosting

Jos agentti käyttää jotakin tuetuista AI-kehyksistä, asenna vastaava automaattinen instrumentointilaajennus, jotta telemetriatiedot kerätään ilman manuaalista instrumentointikoodia. Lisätietoja määritystiedoista on kohdassa Automaattinen instrumentointi.

# 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

Asenna ydinhavaittavuus ja suorituksenaikaiset paketit. Kaikki agentit, jotka käyttävät Agent 365:n havaittavuutta, tarvitsevat nämä paketit.

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

Jos agentti käyttää @microsoft/agents-hosting-, asenna isännöinnin integrointipaketti. Se sisältää väliohjelmiston, joka täyttää automaattisesti baggage-ominaisuudet ja laajuudet kohteesta TurnContext ja lisää tunnuksen välimuistiin tallennuksen havainnoitavuuden vientitoiminnolle.

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

Asenna ydinhavaittavuus ja suorituksenaikainen paketti. Kaikki Agent 365:n havaittavuutta käyttävät agentit tarvitsevat tämän paketin.

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

Jos agentti käyttää Microsoft.Agents.A365.Observability.Hosting NuGet-pakettia, asenna isännöinnin integrointipaketti. Se sisältää väliohjelmiston, joka automaattisesti täyttää baggage-ominaisuudet kohteesta TurnContext ja lisää tunnuksen välimuistiin tallennuksen havaittavuuden vientitoiminnolle.

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

Määritys

Käytä seuraavia asetuksia, jos haluat ottaa käyttöön ja mukauttaa Agent 365:n havaittavuuden agentille.

Määritä ENABLE_A365_OBSERVABILITY_EXPORTER-ympäristömuuttuja kohteelle true havaittavuutta varten. Tämä asetus vie lokit palveluun ja vaatii, että token_resolver annetaan. Muussa tapauksessa käytetään konsolin vientitoimintoa.

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

Tunnuksen ratkaisija ei sisälly konsolin lokiinkirjaukseen.

Voit mukauttaa vientitoiminnon toimintaa välittämällä Agent365ExporterOptions-instanssin parametrina kohteelle exporter_options. Kun exporter_options on annettu, se ohittaa token_resolver- ja cluster_category-parametrit.

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

Alla olevassa taulukossa kuvataan kohteen configure() valinnaiset parametrit.

Parametri	Description	Oletus
`logger_name`	Python-lokitoiminnon nimi, jota käytetään virheenkorjauksessa ja konsolin lokin tuloksessa.	`microsoft_agents_a365.observability.core`
`exporter_options`	`Agent365ExporterOptions`-instanssi, joka määrittää tunnuksen ratkaisijan ja klusterin luokan yhdessä.	`None`
`suppress_invoke_agent_input`	Kun `True`, syöteviestit estetään `InvokeAgent`-aikaväleillä.	`False`

Alla olevassa taulukossa kuvataan kohteen Agent365ExporterOptions valinnaiset ominaisuudet.

Ominaisuus	Description	Oletus
`use_s2s_endpoint`	Kun `True` on käytössä, käytetään service-to-service-päätepisteen polkua.	`False`
`max_queue_size`	Eräkäsittelijän jonon maksimikoko.	`2048`
`scheduled_delay_ms`	Viive millisekunneissa vientierien välillä.	`5000`
`exporter_timeout_ms`	Vientitoiminnon aikakatkaisuaika (ms).	`30000`
`max_export_batch_size`	Suurin eräkoko vientitoiminnoille.	`512`

Määritä ENABLE_A365_OBSERVABILITY_EXPORTER-ympäristömuuttuja kohteelle true havaittavuutta varten. Tämä asetus vie lokit palveluun ja edellyttää, että tunnuksen ratkaisija on määritetty. Muussa tapauksessa käytetään konsolin vientitoimintoa.

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

Vaihtoehtona ympäristömuuttujille havaittavuuden voi määrittää ohjelmallisesti käyttämällä määrityksen tarjoajaa withConfigurationProvider-menetelmän kautta. Jos käytät myös yksittäisiä luontitoimintomenetelmiä (kuten withExporterOptions tai withClusterCategory), yksittäiset luontitoimintomenetelmät ovat ensisijaisia määrityksen tarjoajaan nähden.

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

Voit mukauttaa vientitoiminnon toimintaa välittämällä Agent365ExporterOptions-instanssin parametrina kohteelle withExporterOptions. Tämä vaihtoehto mahdollistaa eräkäsittelyn, aikakatkaisujen ja reittitilan hallinnan.

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

Alla olevassa taulukossa kuvataan kohteen Agent365ExporterOptions valinnaiset ominaisuudet.

Ominaisuus	Description	Oletus
`useS2SEndpoint`	Kun `true` on käytössä, käytetään service-to-service-päätepisteen polkua.	`false`
`maxQueueSize`	Eräkäsittelijän jonon maksimikoko.	`2048`
`scheduledDelayMilliseconds`	Viive millisekunneissa vientierien välillä.	`5000`
`exporterTimeoutMilliseconds`	Vientioperaation aikakatkaisu millisekunneissa.	`90000`
`httpRequestTimeoutMilliseconds`	Aikakatkaisu millisekunneissa jokaiselle yksittäiselle HTTP-pyynnölle taustajärjestelmään.	`30000`
`maxExportBatchSize`	Suurin eräkoko vientitoiminnoille.	`512`

Voit myös määrittää mukautetun lokitoiminnon, joka toteuttaa ILogger-liittymän (info, warn, error, event). Anna se luontitoiminnolle käyttämällä kohdetta withCustomLogger.

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

Määritä kohteen EnableAgent365Exporter arvoksi true kohteessa appsettings.json.

Lisää kohteessa Agent365ExporterOptions palvelukokoelmaan Program.cs. Tämä muutos määrittää sen edustajan, jota jäljityksen vientitoiminto käyttää tunnuksen noutamisessa.

Lisää havaittavuuteen liittyvät riippuvuudet käyttämällä kohdetta 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();

Voit mukauttaa vientitoiminnon toimintaa välittämällä määritä edustaja- ja vientitoiminto-tyypin kohteelle AddA365Tracing().

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

Alla olevassa taulukossa kuvataan kohteen Agent365ExporterOptions valinnaiset ominaisuudet.

Ominaisuus	Description	Oletus
`UseS2SEndpoint`	Kun `true` on käytössä, käytetään service-to-service-päätepisteen polkua.	`false`
`MaxQueueSize`	Eräkäsittelijän jonon maksimikoko.	`2048`
`ScheduledDelayMilliseconds`	Viive millisekunneissa vientierien välillä.	`5000`
`ExporterTimeoutMilliseconds`	Vientitoiminnon aikakatkaisuaika (ms).	`30000`
`MaxExportBatchSize`	Suurin eräkoko vientitoiminnoille.	`512`

Baggage-tietojen määritteet

Käytä BaggageBuilder asettaaksesi kontekstuaalista tietoa, joka välittyy kaikkiin pyynnön spanien läpi. SDK toteuttaa SpanProcessor -toiminnon, joka kopioi kaikki ei-tyhjät baggage-merkinnät uusiin spaneihin ilman olemassa olevien attribuuttien ylikirjoittamista.

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

Täyttääksesi BaggageBuilder automaattisesti TurnContext perusteella, käytä populate-aputoimintoa microsoft-agents-a365-observability-hosting-paketissa. Tämä apufunktio poimii automaattisesti kutsujan, agentin, vuokraajan, kanavan ja keskustelun tiedot aktiviteetista.

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

Täyttääksesi BaggageBuilder automaattisesti TurnContext perusteella, käytä fromTurnContext-aputoimintoa @microsoft/agents-a365-observability-hosting-paketissa. Tämä apufunktio poimii automaattisesti kutsujan, agentin, vuokraajan, kanavan ja keskustelun tiedot aktiviteetista.

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.

Täyttääksesi BaggageBuilder automaattisesti ITurnContext perusteella, käytä FromTurnContext-laajennusmenetelmää Microsoft.Agents.A365.Observability.Hosting-paketissa. Tämä menetelmä poimii automaattisesti soittajan, agentin, vuokralaisen, kanavan ja keskustelun tiedot toiminnasta.

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

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

Baggage-väliohjelmisto

Jos agenttisi käyttää hosting-integraatiopakettia, rekisteröi baggage-väliohjelmisto, jotta baggage täytetään automaattisesti jokaiselle saapuvalle pyynnölle. Tämä vaihe poistaa tarpeen kutsua BaggageBuilder manuaalisesti jokaisessa aktiviteetin käsittelijässä.

Rekisteröi BaggageMiddleware sovittimen väliohjelmistosarjaan. Se poimii automaattisesti soittajan, agentin, vuokraajan, kanavan ja keskustelun tiedot jokaisesta saapuvasta TurnContext-pyynnöstä ja käärii pyynnön baggage-kontekstiin.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Vaihtoehtoisesti voidaan käyttää kohdetta ObservabilityHostingManager baggage-väliohjelmiston ja muiden hosting-ominaisuuksien määritykseen:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Middleware ohittaa baggage-määrityksen asynkronisille vastauksille (ContinueConversation tapahtumille) välttääkseen baggage-tietojen ylikirjoittamisen, jotka alkuperäinen pyyntö on jo asettanut.

Rekisteröi BaggageMiddleware sovittimeen. Se poimii automaattisesti soittajan, agentin, vuokraajan, kanavan ja keskustelun tiedot jokaisesta saapuvasta TurnContext-pyynnöstä ja käärii pyynnön baggage-kontekstiin.

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

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

Vaihtoehtoisesti voidaan käyttää kohdetta ObservabilityHostingManager baggage-väliohjelmiston ja muiden hosting-ominaisuuksien määritykseen:

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

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

Rekisteröi BaggageTurnMiddleware sovittimeen. Se poimii automaattisesti soittajan, agentin, vuokraajan, kanavan ja keskustelun tiedot jokaisesta saapuvasta ITurnContext-pyynnöstä ja käärii pyynnön baggage-kontekstiin.

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

adapter.Use(new BaggageTurnMiddleware());

Jos tarvitset HTTP-tason baggagea (esimerkiksi vuokraaja- ja agentti-ID:n asettamiseen ennen Bot Framework -putkea), rekisteröi ObservabilityBaggageMiddleware ASP.NET Core -putkeen käyttämällä UseObservabilityRequestContext -laajennusmenetelmää. Sinun tulee määrittää resolver-funktio, joka erottelee vuokraaja-ID:n ja agentti-ID:n HTTP-kontekstista.

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

Tunnuksen ratkaisija

Kun käytät Agent 365 -vientitoimintoa, määritä tunnuksen ratkaisijafunktio, joka palauttaa todennuksen tunnuksen. Kun käytät Agent 365 Observability SDK:ta agentti Hosting -kehysrakenteen kanssa, voit luoda tunnuksia käyttämällä TurnContext agenttitoiminnoista.

Seuraavassa esimerkissä näytetään, miten tunnus luodaan microsoft_agents.hosting.core SDK:n avulla. Tässä luotua todennustunnusta käytetään aikavälien viemisessä A365:n vastaanottopalveluun. Agentit voivat luoda tunnisteen itse, esimerkiksi käyttämällä Microsoft Authentication Library (MSAL) -ratkaisua. On kuitenkin varmistettava, että tunnuksessa on havaittavuuden laajuus.

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

Agentille, joka on rakennettu A365 CLI:llä ja käyttää tekoälytiimikaveria sekä Microsoft Agent 365:n havaittavuuden isännöintikirjasto -pakettia, käytetään kohdetta AgenticTokenCache tunnuksen välimuistiin tallentamisen käsittelyssä automaattisesti. Rekisteröi tunnus kerran agenttia ja vuokraajaa kohden aktiviteetin käsittelijän aikana ja välitä cache.get_observability_token kohteena token_resolver havaittavuuden määritykseen.

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

Seuraavassa esimerkissä näytetään, miten tunnus luodaan @microsoft/agents-hosting SDK:n avulla. Tässä luotua todennustunnusta käytetään aikavälien viemisessä A365:n vastaanottopalveluun. Agentit voivat luoda tunnisteen itse, esimerkiksi käyttämällä Microsoft Authentication Library (MSAL) -ratkaisua. On kuitenkin varmistettava, että tunnuksessa on havaittavuuden laajuus.

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

Jos agentti on rakennettu A365 CLI:llä, joka käyttää tekoälytyökaveria sekä @microsoft/agents-a365-observability-hosting -pakettia, käytä kohdetta AgenticTokenCacheInstance tunnuksen välimuistiin tallentamisen automaattisessa käsittelyssä. Call kohdetta RefreshObservabilityToken kerran agenttia ja vuokraajaa kohden aktiviteetin käsittelijän aikana ja välitä AgenticTokenCacheInstance.getObservabilityToken kohteena tokenResolver havaittavuuden määritykseen.

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

Seuraava koodikatkelma osoittaa, miten tunnus voidaan luoda käyttämällä Microsoft.Agents isännöinti-SDK:ta. Käytä luotua todennustunnusta, jos haluat viedä aikavälit A365:n vastaanottopalveluun. Agentit voivat luoda tunnisteen itse, esimerkiksi käyttämällä Microsoft Authentication Library (MSAL) -ratkaisua. On kuitenkin varmistettava, että tunnuksessa on havaittavuuden laajuus.

Anna tunnuksen ratkaisija rekisteröimällä Agent365ExporterOptionsTokenResolver-edustajaan. Edustaja vastaanottaa kohteet agentId ja tenantId ja palauttaa todennustunnuksen.

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

Jos agentti on luotu A365 CLI:lla, joka käyttää tekoälytyötoveria ja Microsoft.Agents.A365.Observability.Hosting NuGet package-pakettia, käytä AddAgenticTracingExporter()-menetelmää tunnuksen välimuistiin tallentamisen käsittelemisessä automaattisesti riippuvuuden lisäyksen aikana.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Rekisteröi tunnus agenttisovelluksessa.

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

Automaattinen instrumentointi

Automaattinen instrumentointi kuuntelee agenttikehysten (SDK) olemassa olevia telemetriasignaaleja jäljityksiä varten ja välittää ne Agent 365:n havaittavuuspalveluun. Tämän ominaisuuden ansiosta kehittäjien ei tarvitse kirjoittaa valvontakoodia käsin. Se myös yksinkertaistaa määrityksiä ja varmistaa johdonmukaisen suorituskyvyn seurannan.

Tärkeää

Automaattinen instrumentointi täyttää vain OTel:n vakiomääritteet. Sinun täytyy lisätä Microsoft-kohtaiset attribuutit BaggageBuilder kautta. Jos haluat nähdä, mitkä määritteet puuttuvat, tarkista konsolin aikavälin tulos tallennettujen lokien perusteella eri joukoissa.

Useat SDK:t ja ympäristöt tukevat automaattista instrumentointia seuraavasti:

Ympäristö	Tuetut SDK:t / kehykset
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Muistiinpano

Automaattisen instrumentoinnin tuki vaihtelee ympäristön ja SDK-toteutuksen mukaan.

Semantic Kernel

Automaattinen instrumentointi vaatii baggage-luontitoiminnon käyttöä. Määritä agentin tunnus ja vuokraajan tunnus käyttämällä kohdetta BaggageBuilder.

Asenna paketti.

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

Määritä havaittavuus.

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

Lisää riippuvuudet palvelukokoelmaan.

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

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

Määritä AgentId ja TenantId käyttämällä kohdetta BaggageBuilder. Varmista, että tunnus, jota käytetään kohteen ChatCompletionAgent luomisessa, on sama kuin agentin tunnus, joka välitetään kohteelle 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

Automaattinen instrumentointi vaatii baggage-luontitoiminnon käyttöä. Määritä agentin tunnus ja vuokraajan tunnus käyttämällä kohdetta BaggageBuilder.

Asenna paketti.

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

Määritä havaittavuus.

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

Asenna paketti.

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

Määritä havaittavuus.

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

Lisää riippuvuudet palvelukokoelmaan.

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

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

Määritä AgentId ja TenantId käyttämällä kohdetta BaggageBuilder. Aloita työkalukutsujen jäljitys käyttämällä kohdetta Trace()ChatToolCall-instanssissa.

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

Automaattinen instrumentointi vaatii baggage-luontitoiminnon käyttöä. Määritä agentin tunnus ja vuokraajan tunnus käyttämällä kohdetta BaggageBuilder.

Asenna paketti.

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

Määritä havaittavuus.

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

Lisää riippuvuudet palvelukokoelmaan.

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

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

Määritä AgentId ja TenantId käyttämällä kohdetta 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

Automaattinen instrumentointi edellyttää baggage-luontitoiminnon käyttämistä. Määritä agentin tunnus ja vuokraajan tunnus käyttämällä kohdetta BaggageBuilder.

Asenna paketti.

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

Määritä havaittavuus.

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

Asenna paketti.

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

Määritä havaittavuus.

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

Manuaalinen instrumentointi

Käytä Agent 365:n havaittavuuden SDK:ta saadaksesi lisätietoja agentin sisäisestä toiminnasta. SDK tarjoaa laajuuksia, jotka voi käynnistää: InvokeAgentScope, ExecuteToolScope, InferenceScope ja OutputScope.

Agentin kutsuminen

Käytä tätä laajuutta agenttiprosessin alussa. Käyttämällä käynnistä agentti -laajuutta voit tallentaa ominaisuuksia, kuten nykyisen käynnistettävän agentin ja agentin käyttäjätiedot.

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

Jos agentti käyttää @microsoft/agents-a365-observability-hosting -pakettia, voit käyttää kohdetta ScopeUtils.populateInvokeAgentScopeFromTurnContext laajuuden luomiseen. Tällöin agentin, soittajan ja kanavan tiedot johdetaan automaattisesti kohteesta TurnContext.

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

Työkalun suoritus

Seuraavat esimerkit osoittavat, miten havaittavuuden seuranta lisätään agentin työkalun suoritukseen. Tämä seuranta kerää telemetriatietoja valvonta- ja auditointitarkoituksiin.

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

Jos agentti käyttää @microsoft/agents-a365-observability-hosting -pakettia, käytä kohdetta ScopeUtils.populateExecuteToolScopeFromTurnContext luodaksesi laajuuden, jossa agentin tiedot johdetaan automaattisesti kohteesta 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.\"}");

Päättely

Seuraavat esimerkit osoittavat, miten tekoälymallin liittymäkutsut instrumentoidaan havaittavuuden jäljityksellä tunnusten käytön, mallitietojen ja vastauksen metatietojen tallentamiseksi.

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

Jos agentti käyttää @microsoft/agents-a365-observability-hosting -pakettia, voit käyttää kohdetta ScopeUtils.populateInferenceScopeFromTurnContext luodaksesi laajennuksen agentin tiedolla, jotka on automaattisesti johdettu kohteesta 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);

Tulos

Käytä tätä laajuutta asynkronisissa skenaarioissa, joissa InvokeAgentScope, ExecuteToolScope tai InferenceScope ei pysty tallentamaan tulostietoja synkronisesti. Käynnistä OutputScope aliaikavälinä, jotta voit tallentaa lopulliset tulosviestit pääelementin laajuuden päätyttyä.

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

Validoi paikallisesti

Varmista, että integrointi havaittavuuden SDK:n kanssa onnistui, tarkastelemalla agentin tuottamia konsolilokeja ja havaittavuus-SDK:n lokitietoja.

Määritä ympäristömuuttujan ENABLE_A365_OBSERVABILITY_EXPORTER arvoksi false. Tämä asetus vie aikavälit (jäljet) konsoliin.

Jos haluat tutkia viennin virheitä, ota käyttöön yksityiskohtainen lokiinkirjaus asettamalla kohdan ENABLE_A365_OBSERVABILITY_EXPORTER arvoksi true ja määrittämällä virheenkorjauksen lokiinkirjaus sovelluksen käynnistyksessä seuraavasti:

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)

Keskeiset lokiviestit:

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.

Määritä ympäristömuuttujan ENABLE_A365_OBSERVABILITY_EXPORTER arvoksi false. Tämä asetus vie aikavälit (jäljet) konsoliin.

Jos haluat tutkia viennin virheitä, määritä ympäristömuuttujat kohdassa .env tai liittymässä seuraavasti:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Tarkista konsolin tulos viestien varalta, kuten:

[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

Käytä tarvittaessa mukautettua lokitoimintoa vientitapahtumien tallentamiseksi tiedostoon seuraavasti:

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

Määritä kohteen EnableAgent365Exporter arvoksi false kohteessa appsettings.json. Tämä asetus vie aikavälit (jäljet) konsoliin.

Jos haluat tutkia viennin virheitä, määritä yksityiskohtainen lokiinkirjaus kohdassa appsettings.json:

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

Vaihtoehtoisesti voit määrittää ympäristömuuttujat seuraavasti:

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

Keskeiset lokiviestit:

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.

Muistiinpano

Jos et rekisteröi kohdetta ILoggerFactory DI:ssä, vientitoiminto siirtyy käyttämään konsolin lokitoimintoa automaattisesti.

Vietyjen lokien tarkasteleminen

Jotta voit tarkastella agentin telemetriaa Microsoft Purviewissa tai Microsoft Defenderissä, varmista että seuraavat vaatimukset täyttyvät:

Microsoft Purview: Auditointi on otettava käyttöön organisaatiossasi. Katso ohjeet kohdasta Seurannan ottaminen käyttöön tai poistaminen käytöstä.
Microsoft Defender: Edistynyt metsästys täytyy konfiguroida, jotta tauluun CloudAppEvents pääsee käsiksi. Katso tiedot kohdasta CloudAppEvents-taulukko edistyneen metsästyksen skeemassa.

Myymälän julkaisun vahvistaminen

Tärkeää

Jotta myymälän vahvistaminen onnistuu, agentin on otettava käyttöön laajuudet InvokeAgentScope, InferenceScope ja ExecuteToolScope. Nämä kolme laajuutta ovat välttämättömiä julkaisussa.

Käytä ennen julkaisua konsolin lokeja vahvistaaksesi havaittavuuden integroinnin agentin kanssa toteuttamalla vaaditut laajuudet invoke agent, execute tool, inference ja output. Vertaa agentin lokeja seuraaviin määriteluetteloihin varmistaaksesi, että kaikki vaaditut määritteet löytyvät. Tallenna määritteet jokaisessa laajuudessa tai käyttämällä baggage-luontitoimintoa. Lisää valinnaiset määritteet oman harkintasi mukaan.

Lisätietoja myymälän julkaisuvaatimuksista on kohdassa Myymälän vahvistuksen ohjeet.

`InvokeAgentScope`-määritteet

Seuraavassa luettelossa on yhteenveto pakollisista ja valinnaisista telemetriamääritteistä, jotka tallennetaan, kun InvokeAgentScope käynnistetään.

"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`-määritteet

Seuraavassa luettelossa on yhteenveto pakollisista ja valinnaisista telemetriamääritteistä, jotka tallennetaan, kun ExecuteToolScope käynnistetään.

"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`-määritteet

Seuraavassa luettelossa on yhteenveto pakollisista ja valinnaisista telemetriamääritteistä, jotka tallennetaan, kun InferenceScope käynnistetään.

"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`-määritteet

Seuraavassa luettelossa on yhteenveto pakollisista ja valinnaisista telemetriamääritteistä, jotka tallennetaan, kun OutputScope käynnistetään. Käytä tätä laajuutta asynkronisissa skenaarioissa, kun pääelementin laajuus ei voi tallentaa tulostietoja synkronisesti.

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

Havainnointeja sisältävien agenttien testaus

Kun olet ottanut käyttöön havaittavuuden agentissa, testaa sitä varmistaaksesi, että se tallentaa telemetrian oikein. Määritä ympäristö testausoppaan tietojen avulla. Keskity sen jälkeen ensisijaisesti Havaittavuuslokien tarkastelu -osaan varmistaaksesi, että havaittavuuden toteutus toimii odotetusti.

Vahvistus:

Siirry osoitteeseen https://admin.cloud.microsoft/#/agents/all
Valitse agentti > Aktiviteetti
Näet istuntoja ja työkalukutsuja

Vianmääritys

Tässä osassa kuvataan yleisiä ongelmia havaittavuuden toteuttamisessa ja käytössä.

Ongelma	Description
Havainnointidata ei näy	Telemetriaa ei näy, koska vienti ei ole käytössä, määritys on virheellinen tai tunnuksen resoluutio epäonnistuu.
Puuttuva vuokraaja-ID tai agentti-ID – spanit ohitetaan	Aikavälit pudotetaan ennen vientiä, kun osiointiin vaaditut käyttäjätietojen määritteet puuttuvat.
Token-resoluutiovirhe – vienti jätetty väliin tai ei valtuutusta	Vientipyynnöt epäonnistuvat tai ne ohitetaan, kun tunnuksen ratkaisija ei palauta tunnusta tai se löytää poikkeukseen.
HTTP 401 Ei sallittu	Tunnistautuminen onnistuu syntaktisesti, mutta tunnus on virheellinen käyttöä varten laajuuden, tyypin tai vanhentumisen vuoksi.
HTTP 403 Käyttö estetty	Pääsy evätään vuokraajan käyttöoikeuden tai havaittavuuden oikeuksien puuttumisen vuoksi.
HTTP 403 Estetty – agentti-ID ei vastaa	Pyyntö hylätään, mikäli URL-osoitteen agentin käyttäjätiedot eivät vastaa tunnuksen esittämiä käyttäjätietoja.
HTTP 429- tai 5xx-virheet – tilapäiset virheet	Tilapäiset rajoitukset tai virheet palvelussa keskeyttävät viennin ja saattavat edellyttää uudelleenyrittämisen asetusten säätämistä.
Viennin aikakatkaisu	Telemetriaerät ylittävät määritetyt aikakatkaisuikkunat verkon viiveen tai päätepisteen reagoinnin vuoksi.
Vienti onnistuu, mutta telemetriaa ei näy Defenderissä tai Purviewissa	Käsittely on valmis, mutta näkyvyys tulevissa toiminnoissa viivästyy tai estyy tuotteen edellytysten vuoksi.

Vinkki

Agent 365:n vianmääritysopas sisältää yleisluontoisia vianmääritykseen liittyviä suosituksia, parhaita käytäntöjä sekä linkkejä vianmääritykseen liittyvään sisältöön Agent 365:n kehityksen elinkaaren kaikissa vaiheissa.

Havainnointidata ei näy

Oireet:

Agentti on käynnissä
Telemetria puuttuu hallintokeskuksesta
Agentin toimintaa ei näy

Juurisyy:

Havaittavuutta ei ole otettu käyttöön
Määritysvirheet
Token resolverin ongelmat

Ratkaisut: Kokeile seuraavia vaiheita ongelman ratkaisemiseksi:

Varmista, että havaittavuuden vientitoiminto on käytössä

Agent 365 exportteri täytyy ottaa käyttöön erikseen. Kun se on poistettu käytöstä, SDK siirtyy käyttämään konsolin vientitoimintoa, eikä telemetriaa lähetetä palveluun. Lisätietoja määrityksen tiedoista on kohdassa Määritys.
Tarkista token-ratkaisijan konfiguraatio

Exportteri vaatii kelvollisen token-ratkaisijan, joka palauttaa Bearer-tokenin jokaista vientipyyntöä kohden. Jos token-ratkaisijaa ei ole tai se palauttaa null, vienti jätetään huomiotta ilman ilmoitusta. Varmista, että koodi implementoi tunnuksen ratkaisijan oikein. Lisätietoja on kohdassa Tunnuksen ratkaisija.
Tarkista lokin virheet

Ota käyttöön yksityiskohtainen lokiinkirjaus ja käytä az webapp log tail komentoa etsiäksesi lokeista havaittavuuteen liittyviä virheitä. Lisätietoja lokiinkirjauksen käyttöönotosta ympäristöä kohti on kohdassa Paikallinen vahvistaminen.
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
Varmista telemetrian vienti

Varmista, että telemetria on luotu ja viety odotetulla tavalla.
- Lisää konsolin vientitoiminto ja tarkista, että telemetriaa luodaan paikallisesti. Lisätietoja konsolin vientitoiminnon käytöstä ja tuloksen vahvistuksesta on kohdassa Paikallinen vahvistaminen.

Puuttuva vuokraaja-ID tai agentti-ID — spanit sivuutetaan

Oireet: Järjestelmä pudottaa huomaamattomasti spanit eikä koskaan vie niitä. Jotkin SDK:t kirjaavat lokiin ohitettujen aikavälien määrän tai viestin, kuten Aikavälejä, joilla on vuokraajan tai agentin käyttäjätiedot, ei löytynyt. Muut pudottavat ne ilman lokiinkirjausta.

Ratkaisu:

Ennen vientiä SDK jakaa spanit vuokraajan ja agentin käyttäjätietojen mukaan. Järjestelmä pudottaa aikavälit, joilta puuttuu joko vuokraajan tai agentin tunnus, eikä koskaan lähetä niitä palveluun.
Varmista, että BaggageBuilder on asetettu vuokralaisen ja agentin tunnuksella ennen spanien luomista. Nämä arvot siirtyvät OpenTelemetry-kontekstin mukana ja liitetään kaikkiin baggage-kontekstin sisällä luotuihin span-objekteihin. Katso alustakohtaista API:a kohdasta Baggage attributes.
Varmista, että kohteen TurnContext aktiviteetilla on kelvollinen vastaanottaja agentin käyttäjätiedoilla, jos käytät baggage-väliohjelmistoa tai käännät kontekstin avustajan isännöinnin integrointipaketista näiden tunnusten täyttämiseksi.

Token-resoluutiovirhe — vienti ohitettu tai valtuuttamaton

Oireet: Token resolver palauttaa null tai heittää virheen. SDK:n mukaan vienti joko ohitetaan kokonaan tai pyyntö lähetetään ilman valtuutusotsikkoa, ja se epäonnistuu HTTP 401 -virheen kanssa.

Ratkaisu:

Tunnuksen ratkaisija tarvitaan alustuksen yhteydessä. Jos se puuttuu, exportteri antaa virheilmoituksen käynnistyksessä. Varmista, että token-ratkaisija on käytössä ja palauttaa kelvollisen Bearer-tokenin.
Varmista, että kohteessa BaggageBuilder käytetään oikeaa vuokraajan ja agentin tunnusta, koska nämä arvot välitetään tunnuksen ratkaisijalle.
Azure-isännöidyille agenteille varmista, että Managed Identityllä on tarvittavat API-oikeudet havaittavuuden vastuualuetta varten.

HTTP 401 Ei sallittu

Oireet: Vienti epäonnistuu HTTP 401 -virheen vuoksi. Vientiohjelma ei tee uudelleenyritystä tämän virheen sattuessa.

Ratkaisu:

Varmista, että tokenin audience vastaa observability endpointin scopea.
Tarkista, ettei token resolver palauta edustajakäyttäjä-tokenia, väärälle audience-arvolle tarkoitettua tokenia tai vanhentunutta tokenia.

HTTP 403 Käyttö estetty

Oireet: Vienti epäonnistuu HTTP 403 -virheen vuoksi. Vientiohjelma ei tee uudelleenyritystä tämän virheen sattuessa.

Juurisyy: HTTP 403 -virhe voi johtua useista eri syistä. Tarkista seuraavat ratkaisut järjestyksessä.

Ratkaisu:

Puuttuva lisenssi — Varmista, että vuokraajallasi on jokin seuraavista lisensseistä määritettynä Microsoft 365 -hallintakeskuksessa:
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
Puuttuva kohteen Agent365.Observability.OtelWrite oikeus – Jos olet äskettäin päivittänyt havaittavuuspaketit, tämä oikeus on myönnettävä. Katso tärkeä huomautus seuraavasta osasta.

Tärkeää

Nykyisten agenttien päivitys näihin pakettiversioihin vaatii ylimääräisen vaiheen

Tämä vaihe vaaditaan vain, kun päivität olemassa olevaa agenttia. Uusien agenttien asennukset eivät vaadi tätä vaihetta. Jos päivität seuraaviin tai uudempiin pakettiversioihin, uusi kohteen Agent365.Observability.OtelWrite oikeus on myönnettävä käyttäjätiedoille (hallitut käyttäjätiedot tai sovelluksen rekisteröinti). Ilman tätä käyttöoikeutta telemetrian vienti epäonnistuu HTTP 403 -virheellä.

Ympäristö	Minimiversio, joka vaatii tämän vaiheen
.NET	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

Myönnä käyttöoikeudet käyttämällä jotakin alla olevista vaihtoehdoista.

Vaihtoehto A – Agent 365 CLI (vaatii yleisen järjestelmänvalvojan roolin. Suoritetaan agentin projektihakemistosta, joka sisältää tiedoston a365.config.json, tai käytetään kohdetta --agent-name)

a365 setup permissions bot

Tai ilman konfiguraatiotiedostoa:

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

Tämä komento myöntää suunnitelman kaikki puuttuvat oikeudet, mukaan lukien havaittavuuden laajuudet.

Vaihtoehto B – Entra-portaali (ei määritystiedostoja, edellyttää yleisen järjestelmänvalvojan käyttöoikeuden suunnitelman sovelluksen rekisteröimistä varten)

Siirry Entra-portaali>Sovellusten rekisteröinnit> -osioon ja valitse Blueprint-sovelluksesi.
Siirry API-oikeudet>Lisää käyttöoikeus>Organisaation käytössä olevat API:t> etsi 9b975845-388f-4429-889e-eab1ef63949c.
Valitse Delegoidut oikeudet>, tarkista Agent365.Observability.OtelWrite>Lisää käyttöoikeudet.
Toista vaiheet 2–3. Valitse tällä kertaa Sovelluksen käyttöoikeudet> valitse Agent365.Observability.OtelWrite>Lisää käyttöoikeudet.
Klikkaa Myönnä ylläpitäjän suostumus ja vahvista.

Sekä kohteen Agent365.Observability.OtelWrite (delegoitu) että kohteen Agent365.Observability.OtelWrite (sovellus) tulee olla tilassa Granted.

HTTP 403 Kielletty — agentin ID ei täsmää

Oireet: Vienti epäonnistuu HTTP 403 -virheellä ja palvelinviestillä, joka muistuttaa 403 Forbidden ja sisältää agent-ID-mismatch epäonnistumisia Agent 365:n jälkien päätepisteiden kutsumisessa.

Syy: Tämä virhe tapahtuu, kun käytät blueprintin asiakas-ID:täagentin instanssin asiakas-ID:n sijasta, kun asetat agentin tiedot. Agentin ID eksportin URL:ssa ei täsmää tokenin hyväksymän identiteetin kanssa, joten traces-päätepiste hylkää pyynnön.

Ratkaisu:

Varmista, että tenant ID on lisätty Agent 365:n sallittujen vuokraajien listalle.
Aseta agentin tiedot agentin instanssin asiakas-ID :llä (ei blueprint-asiakas-ID:llä).
Tarkista generoitu vienti-URL – se kirjataan, jos otat loggerin käyttöön. Vahvista, että agentti-ID URL-osoitteessa vastaa agentin instanssin client ID:tä.
Ota diagnostiikkalokit käyttöön SDK-kohtaisesti Paikallinen vahvistaminen -kohdan tietojen avulla.

HTTP 429- tai 5xx-virheet – tilapäiset virheet

Oireet: Vienti epäonnistuu ohimenevällä HTTP-tilakoodilla, kuten 429 tai 5xx.

Ratkaisu:

Nämä virheet ovat yleensä ohimeneviä ja ratkeavat itsestään. Python ja JavaScript SDK:t suorittavat automaattisen uudelleenyrityksen HTTP 408-, 429- ja 5xx-tilakoodeilla enintään kolme kertaa eksponentiaalisella viiveellä. .NET SDK ei yritä uudelleen automaattisesti.
Jos virheet jatkuvat, tarkista palvelun tilannepaneeli.
Harkitse vientien harventamista lisäämällä aikataulutettua viivettä erien välillä tai kasvattamalla vientierän enimmäiskokoa. Katso ympäristökohtaiset määritysvaihtoehdot Agent365ExporterOptions-taulukosta Määritys-kohdassa.

Viennin aikakatkaisu

Oireet: Vientiyritykset menevät aikakatkaisuun.

Ratkaisu:

Tarkista verkkoyhteys observability-endpointiin.
Aikakatkaisun oletusarvot vaihtelevat ympäristön mukaan. HTTP-pyynnön oletusaikakatkaisu on 30 sekuntia. Joillakin SDK:illa on myös erillinen vientitoiminnon yleinen aikakatkaisu, joka kattaa koko vientisyklin, mukaan lukien uudelleenyritykset. Tarkat ominaisuudet ja oletusasetukset ympäristökohtaisesti Agent365ExporterOptions-taulukosta Määritys-kohdassa.
Jos aikakatkaisuja esiintyy usein, kasvata sopivaa aikakatkaisuarvoa vientitoiminnon asetuksissa.

Vienti onnistuu, mutta telemetriaa ei näy Defenderissä tai Purviewissa

Oireet: Lokit osoittavat onnistuneen viennin, mutta telemetria ei ole näkyvissä Microsoft Defenderissä tai Microsoft Purview'ssa.

Ratkaisu:

Varmista, että vietyjen lokien katselun edellytykset täytetään. Purview'ssa auditointi on otettava käyttöön. Defenderissä on määritettävä edistynyt uhkien etsintä. Lisätietoja on kohdassa Vietyjen lokien tarkasteleminen.
Telemetrian päivittyminen voi kestää useita minuutteja onnistuneen viennin jälkeen. Odota, että tiedot tulevat näkyviin, ennen kuin jatkat tutkimista.

Lisätietoja havaittavuuden testaamisesta on kohdassa:

Agent 365:n havaittavuuskäsitteet – Tietotyönkulku, identiteettimallit, todennus, laajuudet ja rajat, jotka koskevat kaikkia integraatiopolkuja.
Agent 365:n havaittavuusattribuuttiviite – Kanoninen span-attribuuttikaavio, johon jokaisen Agent 365:n vastaanottaman haaran on vastattava.
Microsoft OpenTelemetry Distro – Suositeltu yhtenäinen SDK uusille integroinneille.

Palaute

Onko tästä sivusta apua?

Last updated on 2026-07-30

Näkyvyyden SDK

Avainedut

Tuetut agentit

Asentaminen

Määritys

Baggage-tietojen määritteet

Baggage-väliohjelmisto

Tunnuksen ratkaisija

Automaattinen instrumentointi

Semantic Kernel

OpenAI

Agent Framework

LangChain Framework

Manuaalinen instrumentointi

Agentin kutsuminen

Työkalun suoritus

Päättely

Tulos

Validoi paikallisesti

Vietyjen lokien tarkasteleminen

Myymälän julkaisun vahvistaminen

InvokeAgentScope-määritteet

ExecuteToolScope-määritteet

InferenceScope-määritteet

OutputScope-määritteet

Havainnointeja sisältävien agenttien testaus

Vianmääritys

Havainnointidata ei näy

Puuttuva vuokraaja-ID tai agentti-ID — spanit sivuutetaan

Token-resoluutiovirhe — vienti ohitettu tai valtuuttamaton

HTTP 401 Ei sallittu

HTTP 403 Käyttö estetty

HTTP 403 Kielletty — agentin ID ei täsmää

HTTP 429- tai 5xx-virheet – tilapäiset virheet

Viennin aikakatkaisu

Vienti onnistuu, mutta telemetriaa ei näy Defenderissä tai Purviewissa

Liittyvä sisältö

Palaute

Lisäresursseja

`InvokeAgentScope`-määritteet

`ExecuteToolScope`-määritteet

`InferenceScope`-määritteet

`OutputScope`-määritteet