SDK Observabilitas

Penting

Untuk mengaktifkan observabilitas di Agent 365, gunakan Microsoft OpenTelemetry Distro. Distribusi ini menyediakan SDK observabilitas tunggal di seluruh Microsoft, mendukung Agent 365, Microsoft Foundry, Azure Monitor, dan banyak lagi. Pendekatan yang ada seperti dijelaskan dalam artikel ini tetap berfungsi tanpa perubahan yang memutus kompatibilitas. Untuk panduan migrasi berdasarkan bahasa, lihat panduan berikut.

• Panduan migrasi Python
• Panduan migrasi JavaScript/TypeScript
• Panduan migrasi .NET Untuk model data yang mendasarinya, identitas dan autentikasi, cakupan dan persetujuan, serta batasan—yang berlaku untuk setiap jalur integrasi—lihat Konsep observabilitas Agent 365.

Catatan

Observabilitas adalah salah satu tingkat kemampuan bertahap dalam Memulai pengembangan Agent 365 dan berlaku untuk semua jenis agen.

Untuk berpartisipasi dalam ekosistem Agent 365, integrasikan kemampuan Observabilitas Agent 365 ke dalam agen Anda. Observabilitas Agent 365 didasarkan pada OpenTelemetry (OTel) dan menyediakan kerangka kerja terpadu untuk mengambil telemetri secara konsisten dan aman di semua platform agen. Dengan mengimplementasikan komponen yang diperlukan ini, Anda memungkinkan admin TI memantau aktivitas agen Anda di Microsoft admin center dan memungkinkan tim keamanan menggunakan Defender dan Purview untuk kepatuhan dan deteksi ancaman.

Manfaat utama

• Visibilitas menyeluruh dari awal hingga akhir: Tangkap telemetri komprehensif untuk setiap eksekusi agen, termasuk sesi, pemanggilan alat, dan pengecualian, sehingga memberikan ketertelusuran penuh di seluruh platform.
• Kemampuan keamanan dan kepatuhan: Mengumpankan log audit terpadu ke Defender dan Purview, memungkinkan skenario keamanan tingkat lanjut dan pelaporan kepatuhan untuk agen Anda.
• Fleksibilitas lintas platform: Manfaatkan standar OTel dan dukung berbagai runtime serta platform seperti Copilot Studio, Foundry, dan kerangka kerja agen masa depan.
• Efisiensi operasional untuk admin: Sediakan observabilitas terpusat di pusat admin Microsoft 365, sehingga waktu pemecahan masalah berkurang dan tata kelola meningkat dengan kontrol akses berbasis peran untuk tim TI yang mengelola agen Anda.

Agen yang didukung

Jenis agen berikut ini mendukung observabilitas Agent 365:

• Agen berkemampuan Microsoft Agent 365: Gunakan SDK observabilitas untuk menginstrumentasi agen Anda.
• Agen engine kustom: Gunakan SDK observabilitas untuk menginstrumentasi agen Anda.
• Agen deklaratif: Observabilitas didukung secara bawaan. Tidak diperlukan implementasi SDK.

Penginstalan

Gunakan perintah-perintah ini untuk menginstal modul observabilitas untuk bahasa yang didukung oleh Agent 365.

Python

Instal paket observabilitas inti dan runtime. Semua agen yang menggunakan Observabilitas Agent 365 memerlukan paket-paket ini.

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

Jika agen Anda menggunakan paket Microsoft/agents-hosting, instal paket integrasi hosting. Paket ini menyediakan middleware yang secara otomatis mengisi atribut baggage dan ruang lingkup dari TurnContext, serta mencakup caching token untuk eksportir observabilitas.

pip install microsoft-agents-a365-observability-hosting

Jika agen Anda menggunakan salah satu framework AI yang didukung, pasang ekstensi auto-instrumentasi yang sesuai untuk secara otomatis menangkap telemetri tanpa kode instrumentasi manual. Untuk detail konfigurasi, lihat Auto-instrumentation.

# For Semantic Kernel
pip install microsoft-agents-a365-observability-extensions-semantic-kernel

# For OpenAI Agents SDK
pip install microsoft-agents-a365-observability-extensions-openai

# For Microsoft Agent Framework
pip install microsoft-agents-a365-observability-extensions-agent-framework

# For LangChain
pip install microsoft-agents-a365-observability-extensions-langchain

JavaScript

Instal paket observabilitas inti dan runtime. Semua agen yang menggunakan Observabilitas Agent 365 memerlukan paket-paket ini.

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

Jika agen Anda menggunakan paket @microsoft/agents-hosting, instal paket integrasi hosting. Paket ini menyediakan middleware yang secara otomatis mengisi atribut baggage dan ruang lingkup dari TurnContext, serta mencakup caching token untuk eksportir observabilitas.

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

Jika agen Anda menggunakan salah satu framework AI yang didukung, pasang ekstensi auto-instrumentasi yang sesuai untuk secara otomatis menangkap telemetri tanpa kode instrumentasi manual. Untuk detail konfigurasi, lihat Auto-instrumentation.

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

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

.NET

Instal paket inti observabilitas dan runtime. Semua agen yang menggunakan Observabilitas Agent 365 memerlukan paket ini.

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

Jika agen Anda menggunakan paket NuGet Microsoft.Agents.A365.Observability.Hosting, instal paket integrasi hosting. Paket ini menyediakan middleware yang secara otomatis mengisi atribut baggage dari TurnContext, serta menyertakan caching token untuk pengekspor observabilitas.

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

Jika agen Anda menggunakan salah satu framework AI yang didukung, pasang ekstensi auto-instrumentasi yang sesuai untuk secara otomatis menangkap telemetri tanpa kode instrumentasi manual. Untuk detail konfigurasi, lihat Auto-instrumentation.

// 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

Konfigurasi

Gunakan pengaturan berikut untuk mengaktifkan dan menyesuaikan Observabilitas Agent 365 untuk agen Anda.

Python

Atur ENABLE_A365_OBSERVABILITY_EXPORTER variabel lingkungan ke true untuk observabilitas. Pengaturan ini mengekspor log ke layanan dan mengharuskan token_resolver disediakan. Jika tidak, eksportir konsol digunakan.

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

Token resolver dikecualikan dari logging ke konsol.

Anda dapat menyesuaikan perilaku eksportir dengan meneruskan sebuah instans Agent365ExporterOptions ke exporter_options. Ketika exporter_options disediakan, itu lebih diutamakan daripada parameter token_resolver dan 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,
)

Tabel berikut menjelaskan parameter opsional untuk configure().

Parameter	Deskripsi	Default
logger_name	Nama logger Python yang digunakan untuk debugging dan output log konsol.	microsoft_agents_a365.observability.core
exporter_options	Sebuah instans Agent365ExporterOptions yang mengonfigurasi pemecah token dan kategori kluster bersama-sama.	None
suppress_invoke_agent_input	Saat True, menekan pesan input pada InvokeAgent rentang.	False

Tabel berikut menjelaskan properti opsional untuk Agent365ExporterOptions.

Properti	Deskripsi	Default
use_s2s_endpoint	Ketika True, menggunakan jalur titik akhir layanan ke layanan.	False
max_queue_size	Ukuran maksimum antrean untuk prosesor batch.	2048
scheduled_delay_ms	Penundaan dalam milidetik antara batch ekspor.	5000
exporter_timeout_ms	Batas waktu dalam milidetik untuk operasi ekspor.	30000
max_export_batch_size	Ukuran batch maksimum untuk operasi ekspor.	512

JavaScript

Atur ENABLE_A365_OBSERVABILITY_EXPORTER variabel lingkungan ke true untuk observabilitas. Setelan ini mengekspor log ke layanan dan memerlukan token resolver untuk disediakan. Jika tidak, eksportir konsol digunakan.

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

Sebagai alternatif variabel lingkungan, Anda dapat mengonfigurasi observabilitas secara programatis dengan menggunakan penyedia konfigurasi melalui metode withConfigurationProvider. Jika Anda juga menggunakan metode builder individual (seperti withExporterOptions atau withClusterCategory), metode builder individual akan memiliki prioritas dibandingkan nilai dari penyedia konfigurasi.

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

Anda dapat menyesuaikan perilaku eksportir dengan meneruskan sebuah instans Agent365ExporterOptions ke withExporterOptions. Opsi ini memungkinkan Anda mengatur batching, waktu tunggu, dan mode rute.

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

Tabel berikut menjelaskan properti opsional untuk Agent365ExporterOptions.

Properti	Deskripsi	Default
useS2SEndpoint	Ketika true, menggunakan jalur titik akhir layanan ke layanan.	false
maxQueueSize	Ukuran maksimum antrean untuk prosesor batch.	2048
scheduledDelayMilliseconds	Penundaan dalam milidetik antara batch ekspor.	5000
exporterTimeoutMilliseconds	Batas waktu dalam milidetik untuk seluruh operasi ekspor.	90000
httpRequestTimeoutMilliseconds	Batas waktu dalam milidetik untuk setiap permintaan HTTP individual ke backend.	30000
maxExportBatchSize	Ukuran batch maksimum untuk operasi ekspor.	512

Anda juga dapat menyediakan logger kustom yang mengimplementasikan antarmuka ILogger (info, warn, error, event). Berikan ke builder dengan menggunakan 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();

.NET

Setel EnableAgent365Exporter menjadi true dalam appsettings.json.

Di Program.cs, tambahkan Agent365ExporterOptions ke koleksi layanan. Perubahan ini mengonfigurasi delegat yang digunakan eksportir jejak untuk mengambil token.

Tambahkan dependensi terkait observabilitas dengan menggunakan 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();

Anda dapat menyesuaikan perilaku eksportir dengan meneruskan delegate konfigurasi dan jenis eksportir ke AddA365Tracing().

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

Tabel berikut menjelaskan properti opsional untuk Agent365ExporterOptions.

Properti	Deskripsi	Default
UseS2SEndpoint	Ketika true, menggunakan jalur titik akhir layanan ke layanan.	false
MaxQueueSize	Ukuran maksimum antrean untuk prosesor batch.	2048
ScheduledDelayMilliseconds	Penundaan dalam milidetik antara batch ekspor.	5000
ExporterTimeoutMilliseconds	Batas waktu dalam milidetik untuk operasi ekspor.	30000
MaxExportBatchSize	Ukuran batch maksimum untuk operasi ekspor.	512

Atribut bagasi

Gunakan BaggageBuilder untuk menetapkan informasi kontekstual yang mengalir melalui semua rentang dalam permintaan. SDK menerapkan SpanProcessor yang menyalin semua entri bagasi yang tidak kosong ke setiap rentang yang baru dimulai tanpa menimpa atribut yang sudah ada.

Python

from microsoft_agents_a365.observability.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

Untuk mengisi BaggageBuilder secara otomatis dari TurnContext, gunakan helper populate dalam paket microsoft-agents-a365-observability-hosting. Fungsi helper ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari aktivitas.

from microsoft_agents.hosting.core.turn_context import TurnContext
from microsoft_agents_a365.observability.core import BaggageBuilder
from microsoft_agents_a365.observability.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

JavaScript

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

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

Untuk mengisi BaggageBuilder secara otomatis dari TurnContext, gunakan helper fromTurnContext dalam paket @microsoft/agents-a365-observability-hosting. Fungsi helper ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari aktivitas.

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

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is auto-populated from the TurnContext activity
});

.NET

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

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

Untuk mengisi BaggageBuilder secara otomatis dari ITurnContext, gunakan metode ekstensi FromTurnContext di paket Microsoft.Agents.A365.Observability.Hosting. Metode ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari aktivitas.

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

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

Middleware bagasi

Jika agen Anda menggunakan paket integrasi hosting, daftarkan middleware bagasi untuk secara otomatis mengisi bagasi pada setiap permintaan yang masuk. Langkah ini menghilangkan kebutuhan untuk memanggil BaggageBuilder secara manual di setiap handler aktivitas.

Python

Daftarkan BaggageMiddleware pada set middleware adaptor. Ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari setiap TurnContext yang masuk, serta mengemas permintaan dalam lingkup baggage.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

Sebagai alternatif, gunakan ObservabilityHostingManager untuk mengonfigurasi middleware Baggage bersama dengan fitur hosting lainnya:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

Middleware melewatkan pengaturan bagasi untuk balasan asinkron (peristiwa ContinueConversation) untuk menghindari penimpaan bagasi yang sudah ditetapkan oleh permintaan asal.

JavaScript

Daftarkan BaggageMiddleware pada adaptor. Ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari setiap TurnContext yang masuk, serta mengemas permintaan dalam lingkup baggage.

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

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

Sebagai alternatif, gunakan ObservabilityHostingManager untuk mengonfigurasi middleware Baggage bersama dengan fitur hosting lainnya:

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

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

Middleware melewatkan pengaturan bagasi untuk balasan asinkron (peristiwa ContinueConversation) untuk menghindari penimpaan bagasi yang sudah ditetapkan oleh permintaan asal.

.NET

Daftarkan BaggageTurnMiddleware pada adapter. Ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari setiap ITurnContext yang masuk, serta mengemas permintaan dalam lingkup baggage.

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

adapter.Use(new BaggageTurnMiddleware());

Middleware melewatkan pengaturan bagasi untuk balasan asinkron (peristiwa ContinueConversation) untuk menghindari penimpaan bagasi yang sudah ditetapkan oleh permintaan asal.

Jika Anda memerlukan bagasi di tingkat HTTP (misalnya, untuk menetapkan ID penyewa dan ID agen sebelum alur Bot Framework dijalankan), daftarkan ObservabilityBaggageMiddleware di alur ASP.NET Core menggunakan metode ekstensi UseObservabilityRequestContext. Anda harus menyediakan fungsi resolver yang mengekstrak ID penyewa dan ID agen dari konteks HTTP.

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

Penyelesai token

Saat Anda menggunakan pengekspor Agent 365, Anda harus menyediakan fungsi penyelesai token yang mengembalikan token autentikasi. Saat Anda menggunakan Agent 365 Observability SDK dengan kerangka kerja Agent Hosting, Anda dapat menghasilkan token dengan memanfaatkan TurnContext yang berasal dari aktivitas agen.

Python

Cuplikan berikut menunjukkan cara menghasilkan token dengan memanfaatkan microsoft_agents.hosting.core SDK. Token autentikasi yang dihasilkan di sini digunakan untuk mengekspor span ke layanan penyerapan A365. Agen dapat menghasilkan token sendiri, misalnya dengan menggunakan Pustaka Autentikasi Microsoft (MSAL), tetapi agen ini perlu memastikan token memiliki cakupan observabilitas.

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

Untuk agen yang dibuat dengan A365 CLI yang menggunakan rekan tim AI dan paket Microsoft Agent 365 Observability Hosting Library, gunakan AgenticTokenCache untuk menangani penyimpanan cache token secara otomatis. Daftarkan token sekali untuk setiap agen dan penyewa melalui penangan aktivitas, dan teruskan cache.get_observability_token sebagai token_resolver dalam konfigurasi observabilitas Anda.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

JavaScript

Cuplikan berikut menunjukkan cara menghasilkan token dengan memanfaatkan @microsoft/agents-hosting SDK. Token autentikasi yang dihasilkan di sini digunakan untuk mengekspor span ke layanan penyerapan A365. Agen dapat menghasilkan token sendiri, misalnya dengan menggunakan Pustaka Autentikasi Microsoft (MSAL), tetapi agen ini perlu memastikan token memiliki cakupan observabilitas.

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

Untuk agen yang dibuat dengan A365 CLI yang menggunakan rekan tim AI dan paket @microsoft/agents-a365-observability-hosting, gunakan AgenticTokenCacheInstance untuk menangani penyimpanan cache token secara otomatis. Panggil RefreshObservabilityToken satu kali per agen dan penyewa di dalam penangan aktivitas, dan teruskan AgenticTokenCacheInstance.getObservabilityToken sebagai tokenResolver dalam konfigurasi observabilitas Anda.

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

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

.NET

Berikut adalah cuplikan yang menunjukkan cara menghasilkan token dengan menggunakan SDK hosting Microsoft.Agents. Gunakan token autentikasi yang Anda hasilkan untuk mengekspor span ke layanan penyerapan A365. Agen dapat menghasilkan token sendiri, misalnya dengan menggunakan Pustaka Autentikasi Microsoft (MSAL), tetapi agen ini perlu memastikan token memiliki cakupan observabilitas.

Sediakan penyelesai token dengan mendaftarkan Agent365ExporterOptions menggunakan Delegasi TokenResolver. Delegasi menerima agentId dan tenantId dan mengembalikan token autentikasi.

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

Untuk agen yang dibuat dengan A365 CLI yang menggunakan rekan tim AI dan paket NuGet Microsoft.Agents.A365.Observability.Hosting, gunakan metode AddAgenticTracingExporter() untuk menangani cache token secara otomatis melalui injeksi dependensi.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

Di aplikasi agen, daftarkan token.

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

Instrumentasi otomatis

Instrumentasi otomatis secara otomatis mendengarkan sinyal telemetri dari kerangka kerja agentik (SDK) yang ada untuk pelacakan dan meneruskannya ke layanan observabilitas Agent 365. Fitur ini menghilangkan kebutuhan bagi pengembang untuk menulis kode pemantauan secara manual, menyederhanakan penyiapan, dan memastikan pelacakan performa yang konsisten.

Penting

Instrumentasi otomatis hanya mengisi atribut OTel standar. Anda harus menambahkan atribut khusus Microsoft melalui BaggageBuilder. Untuk melihat atribut mana yang hilang, validasi output span konsol Anda terhadap log penyimpanan untuk set diff.

Beberapa SDK dan platform mendukung instrumentasi otomatis:

Platform	SDK/Kerangka Kerja yang Didukung
.NET	Kernel Semantik, OpenAI, Agent Framework
Python	Kernel Semantik, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

Catatan

Dukungan untuk instrumentasi otomatis bervariasi menurut platform dan implementasi SDK.

Kernel Semantik

Instrumentasi otomatis memerlukan penggunaan baggage builder. Atur ID agen dan ID penyewa dengan menggunakan BaggageBuilder.

Python

Instal paket.

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

Konfigurasikan observabilitas.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

JavaScript

Kernel Semantik tidak didukung dengan JavaScript.

.NET

Tambahkan dependensi ke kumpulan layanan.

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

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

Atur AgentId dan TenantId dengan menggunakan BaggageBuilder. Pastikan ID yang Anda gunakan saat membuat ChatCompletionAgent cocok dengan ID agen yang Anda teruskan ke 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

Instrumentasi otomatis memerlukan penggunaan baggage builder. Atur ID agen dan ID penyewa dengan menggunakan BaggageBuilder.

Python

Instal paket.

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

Konfigurasikan observabilitas.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

JavaScript

Instal paket.

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

Konfigurasikan observabilitas.

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

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

.NET

Tambahkan dependensi ke kumpulan layanan.

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

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

Atur AgentId dan TenantId dengan menggunakan BaggageBuilder. Untuk panggilan alat, mulai pelacakan dengan menggunakan Trace() pada instans ChatToolCall.

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

Instrumentasi otomatis memerlukan penggunaan baggage builder. Atur ID agen dan ID penyewa dengan menggunakan BaggageBuilder.

Python

Instal paket.

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

Konfigurasikan observabilitas.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.agentframework import (
    AgentFrameworkInstrumentor,
)

# Configure observability
configure(
    service_name="AgentFrameworkTracingWithAzureOpenAI",
    service_namespace="AgentFrameworkTesting",
)

# Enable auto-instrumentation
AgentFrameworkInstrumentor().instrument()

JavaScript

Agent Framework tidak didukung dengan JavaScript.

.NET

Tambahkan dependensi ke kumpulan layanan.

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

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

Atur AgentId dan TenantId dengan menggunakan 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();
    }
}

Kerangka Kerja LangChain

Instrumentasi otomatis membutuhkan penggunaan baggage builder. Atur ID agen dan ID penyewa dengan menggunakan BaggageBuilder.

Python

Instal paket.

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

Konfigurasikan observabilitas.

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor

# Configure observability
configure(
    service_name="my-langchain-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

JavaScript

Instal paket.

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

Konfigurasikan observabilitas.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { LangChainTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-langchain';
import * as LangChainCallbacks from '@langchain/core/callbacks/manager';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

sdk.start();

// Enable LangChain auto-instrumentation
LangChainTraceInstrumentor.instrument(LangChainCallbacks);

// Your LangChain code is now automatically traced

.NET

LangChain tidak didukung dengan .NET.

Instrumentasi Manual

Gunakan Agent 365 Observability SDK untuk memahami cara kerja internal agen. SDK ini menyediakan cakupan yang dapat Anda mulai: InvokeAgentScope, ExecuteToolScope, InferenceScope, dan OutputScope.

Pemanggilan agen

Gunakan cakupan ini di awal proses agen Anda. Dengan menggunakan cakupan pemanggilan agen, Anda dapat mengambil properti seperti agen saat ini yang dipanggil, data pengguna agen, dan lainnya.

Python

from microsoft_agents_a365.observability.core import (
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    AgentDetails,
    CallerDetails,
    UserDetails,
    Channel,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="My Agent",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

request = Request(
    content="User asks a question",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

caller_details = CallerDetails(
    user_details=UserDetails(
        user_id="user-123",
        user_email="jane.doe@contoso.com",
        user_name="Jane Doe",
    ),
)

with InvokeAgentScope.start(request, scope_details, agent_details, caller_details):
    # Perform agent invocation logic
    response = call_agent(...)

JavaScript

import {
  InvokeAgentScope,
  InvokeAgentScopeDetails,
  AgentDetails,
  CallerDetails,
  UserDetails,
  Channel,
  Request,
  ServiceEndpoint,
} from '@microsoft/agents-a365-observability';

// Use the same agentDetails instance across all scopes in a request
const agentDetails: AgentDetails = {
  agentId: 'agent-456',
  agentName: 'Email Assistant',
  agentDescription: 'An AI agent powered by Azure OpenAI',
  agentAuid: 'auid-123',
  agentEmail: 'agent@contoso.com',
  agentBlueprintId: 'blueprint-789',
  tenantId: 'tenant-123',
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

// Use the same request instance across all scopes in a request
const request: Request = {
  content: 'Please help me organize my emails',
  sessionId: 'session-42',
  conversationId: 'conv-xyz',
  channel: { name: 'msteams' } as Channel,
};

// Optional: Caller details (human user, or agent-to-agent)
const callerDetails: CallerDetails = {
  userDetails: {
    userId: 'user-123',
    userEmail: 'jane.doe@contoso.com',
    userName: 'Jane Doe',
  } as UserDetails,
};

const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails);

try {
  await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);

    // Your agent invocation logic here
    const response = await invokeAgent(request.content);

    // Record output messages
    scope.recordOutputMessages(['I found 15 urgent emails', 'Here is your organized inbox']);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Jika agen Anda menggunakan paket @microsoft/agents-a365-observability-hosting, Anda dapat menggunakan ScopeUtils.populateInvokeAgentScopeFromTurnContext untuk membuat cakupan dengan detail agen, detail pemanggil, dan informasi saluran yang secara otomatis berasal dari 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();
}

.NET

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

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

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

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

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

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

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

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

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

        return new AgentResponse { Content = output };
    }
}

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

Eksekusi alat

Contoh berikut menunjukkan cara menambahkan pelacakan observabilitas ke eksekusi alat agen Anda. Pelacakan ini mengambil telemetri untuk tujuan pemantauan dan audit.

Python

from microsoft_agents_a365.observability.core import (
    ExecuteToolScope,
    ToolCallDetails,
    Request,
    ServiceEndpoint,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=ServiceEndpoint(hostname="tools.contoso.com", port=8080),
)

with ExecuteToolScope.start(request, tool_details, agent_details) as scope:
    result = run_tool(tool_details)
    scope.record_response(result)

JavaScript

import { ExecuteToolScope, ToolCallDetails } from '@microsoft/agents-a365-observability';

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

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com', limit: 10 }),
  toolCallId: 'tool-call-456',
  description: 'Search emails by criteria',
  toolType: 'function',
  endpoint: {
    host: 'tools.contoso.com',
    port: 8080,  // Will be recorded since not 443
    protocol: 'https'
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Execute the tool
    const result = await searchEmails(toolDetails.arguments);

    // Record the tool execution result
    scope.recordResponse(result);

    return result;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Jika agen Anda menggunakan paket @microsoft/agents-a365-observability-hosting, gunakan ScopeUtils.populateExecuteToolScopeFromTurnContext untuk membuat cakupan dengan detail agen yang secara otomatis diambil dari 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();
}

.NET

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

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

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

// ... your tool logic here ...

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

Inferensi

Contoh berikut menunjukkan cara menginstrumentasikan panggilan inferensi model AI dengan pelacakan observabilitas untuk mengambil penggunaan token, detail model, dan metadata respons.

Python

from microsoft_agents_a365.observability.core import (
    InferenceScope,
    InferenceCallDetails,
    InferenceOperationType,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
)

with InferenceScope.start(request, inference_details, agent_details) as scope:
    completion = call_llm(...)
    scope.record_output_messages([completion.text])
    scope.record_input_tokens(completion.usage.input_tokens)
    scope.record_output_tokens(completion.usage.output_tokens)

JavaScript

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

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

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

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Summarize the following emails for me...']);

    // Call the LLM
    const response = await callLLM();

    // Record detailed telemetry with granular methods
    scope.recordOutputMessages(['Here is your email summary...']);
    scope.recordInputTokens(145);
    scope.recordOutputTokens(82);
    scope.recordFinishReasons(['stop']);

    return response.text;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

Jika agen Anda menggunakan paket @microsoft/agents-a365-observability-hosting, Anda dapat menggunakan ScopeUtils.populateInferenceScopeFromTurnContext untuk membuat cakupan dengan detail agen yang secara otomatis diambil dari 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();
}

.NET

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

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

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

// ... your inference logic here ...

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

Output

Gunakan cakupan ini untuk skenario asinkron di mana InvokeAgentScope, ExecuteToolScope, atau InferenceScope tidak dapat mengambil data output secara sinkron. Mulai OutputScope sebagai rentang turunan untuk merekam pesan ouput akhir setelah cakupan induk selesai.

Python

from microsoft_agents_a365.observability.core import (
    OutputScope,
    Response,
    SpanDetails,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

# Get the parent context from the originating scope
parent_context = invoke_scope.get_context()

response = Response(messages=["Here is your organized inbox with 15 urgent emails."])

with OutputScope.start(
    request,
    response,
    agent_details,
    span_details=SpanDetails(parent_context=parent_context),
):
    # Output messages are recorded automatically from the response
    pass

JavaScript

import { OutputScope, OutputResponse, SpanDetails } from '@microsoft/agents-a365-observability';

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

// Get the parent context from the originating scope
const parentContext = invokeScope.getSpanContext();

const response: OutputResponse = {
  messages: ['Here is your organized inbox with 15 urgent emails.'],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined, // userDetails
  { parentContext } as SpanDetails
);

// Output messages are recorded automatically from the response
scope.dispose();

.NET

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

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

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

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

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

Validasi secara lokal

Untuk memverifikasi bahwa Anda berhasil terintegrasi dengan SDK observabilitas, periksa log konsol yang dihasilkan oleh agen Anda dan log dari SDK observabilitas.

Python

Atur variabel lingkungan ENABLE_A365_OBSERVABILITY_EXPORTER ke false. Pengaturan ini mengekspor span (jejak) ke konsol.

Untuk menyelidiki kegagalan ekspor, aktifkan pengelogan verbose dengan mengatur ENABLE_A365_OBSERVABILITY_EXPORTER ke true dan mengonfigurasi pengelogan debug di awal aplikasi Anda:

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)

Pesan log kunci:

DEBUG  Token resolved for agent {agentId} tenant {tenantId}
DEBUG  Exporting {n} spans to {url}
DEBUG  HTTP 200 - correlation ID: abc-123
ERROR  Token resolution failed: {error}
ERROR  HTTP 401 exporting spans - correlation ID: abc-123
INFO   No spans with tenant/agent identity found; nothing exported.

JavaScript

Atur variabel lingkungan ENABLE_A365_OBSERVABILITY_EXPORTER ke false. Pengaturan ini mengekspor span (jejak) ke konsol.

Untuk menyelidiki kegagalan ekspor, atur variabel lingkungan pada .env atau shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Tinjau output konsol untuk pesan seperti:

[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

Secara opsional, gunakan logger kustom untuk mencatat kejadian ekspor ke dalam file:

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

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

.NET

Setel EnableAgent365Exporter menjadi false dalam appsettings.json. Pengaturan ini mengekspor span (jejak) ke konsol.

Untuk menyelidiki kegagalan ekspor, konfigurasikan pengelogan verbose di appsettings.json:

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

Atau atur variabel lingkungan:

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

Pesan log kunci:

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.

Catatan

Jika Anda tidak mendaftarkan ILoggerFactory di DI, pengekspor secara otomatis akan kembali ke logger konsol.

Melihat log yang diekspor

Untuk melihat telemetri agen di Microsoft Purview atau Microsoft Defender, pastikan persyaratan berikut terpenuhi:

• Microsoft Purview: Auditing harus diaktifkan untuk organisasi Anda. Untuk petunjuk, lihat Mengaktifkan atau menonaktifkan audit.
• Microsoft Defender: Perburuan tingkat lanjut harus dikonfigurasi untuk mengakses tabel CloudAppEvents. Untuk informasi selengkapnya, lihat tabel CloudAppEvents di skema perburuan tingkat lanjut.

Validasi untuk publikasi di toko

Penting

Untuk validasi toko yang sukses, agen Anda harus mengimplementasikan cakupan InvokeAgentScope, InferenceScope, dan ExecuteToolScope. Ketiga cakupan ini diperlukan untuk publikasi di toko.

Sebelum menerbitkan, gunakan log konsol untuk memvalidasi integrasi observabilitas Anda untuk agen dengan mengimplementasikan cakupan invoke agent, execute tool, inference, dan output yang diperlukan. Kemudian bandingkan log agen Anda dengan daftar atribut berikut untuk memastikan semua atribut yang diperlukan tersedia. Catat atribut pada setiap cakupan atau melalui baggage builder, dan sertakan atribut opsional sesuai pertimbangan Anda.

Untuk informasi selengkapnya tentang persyaratan penerbitan toko, lihat pedoman validasi toko.

InvokeAgentScope atribut

Daftar berikut ini merangkum atribut telemetri wajib dan opsional yang direkam saat Anda memulai InvokeAgentScope.

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

Daftar berikut ini merangkum atribut telemetri wajib dan opsional yang direkam saat Anda memulai ExecuteToolScope.

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

Daftar berikut ini merangkum atribut telemetri wajib dan opsional yang direkam saat Anda memulai InferenceScope.

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

Daftar berikut ini merangkum atribut telemetri wajib dan opsional yang direkam saat Anda memulai OutputScope. Gunakan cakupan ini untuk skenario asinkron di mana cakupan induk tidak dapat mengambil data output secara sinkron.

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

Menguji agen dengan observabilitas

Setelah Anda menerapkan observabilitas di agen Anda, uji untuk memastikan bahwa agen tersebut mengambil telemetri dengan benar. Ikuti panduan pengujian untuk menyiapkan lingkungan Anda. Kemudian, fokuskan terutama pada bagian Lihat log observabilitas untuk memvalidasi bahwa implementasi observabilitas Anda berfungsi seperti yang diharapkan.

Verifikasi:

• Buka: https://admin.cloud.microsoft/#/agents/all
• Pilih agen Anda > Aktivitas
• Anda melihat sesi dan panggilan alat

Pemecahan masalah

Bagian ini menjelaskan masalah umum saat menerapkan dan menggunakan observabilitas.

Masalah	Deskripsi
Data observabilitas tidak muncul	Tidak ada telemetri yang terlihat karena ekspor tidak diaktifkan, konfigurasi salah, atau resolusi token gagal.
ID penyewa atau ID agen tidak ada - rentang dilewati	Span dibuang sebelum diekspor ketika atribut identitas yang diperlukan untuk partisi hilang.
Kegagalan resolusi token - ekspor dilewati atau tidak diizinkan	Permintaan ekspor gagal atau dilewatkan saat resolver tidak mengembalikan token atau mengalami pengecualian.
HTTP 401 Tidak Sah	Autentikasi berhasil secara sintaksis tetapi token tidak valid untuk penyerapan karena cakupan, jenis, atau kedaluwarsa.
HTTP 403 Forbidden	Akses ditolak karena kesenjangan lisensi penyewa atau izin observabilitas yang hilang.
HTTP 403 Forbidden - Ketidakcocokan ID Agen	Permintaan ditolak ketika identitas agen di URL tidak cocok dengan identitas yang diwakili oleh token.
Kesalahan HTTP 429 atau 5xx - Kesalahan sementara	Pembatasan sementara atau kegagalan sisi layanan dapat menyebabkan ekspor terhenti dan mungkin memerlukan penyesuaian percobaan ulang.
Batas waktu ekspor	Batch telemetri melebihi jendela batas waktu yang dikonfigurasi karena latensi jaringan atau responsivitas titik akhir.
Ekspor berhasil tetapi telemetri tidak muncul di Defender atau Purview	Penyerapan selesai, tetapi visibilitas hilir tertunda atau diblokir oleh prasyarat produk.

Kiat

Panduan Pemecahan Masalah Agent 365 berisi rekomendasi pemecahan masalah tingkat tinggi, praktik terbaik, dan tautan ke konten pemecahan masalah untuk setiap bagian dari siklus hidup pengembangan Agent 365.

Data observabilitas tidak muncul

Gejala:

• Agen sedang berjalan
• Tidak ada telemetri di pusat admin
• Tidak dapat melihat aktivitas agen

Akar penyebab:

• Observabilitas tidak diaktifkan
• Kesalahan konfigurasi
• Masalah pada token resolver

Solusi: Coba langkah-langkah berikut untuk menyelesaikan masalah:

• Verifikasi bahwa exporter observabilitas diaktifkan

  Anda harus mengaktifkan eksportir Agent 365 secara eksplisit. Jika dinonaktifkan, SDK akan kembali menggunakan pengekspor konsol dan telemetri tidak dikirim ke layanan. Untuk detail konigurasi, lihat Konfigurasi.

• Periksa konfigurasi token resolver

  Eksportir memerlukan token resolver yang valid yang mengembalikan token pembawa untuk setiap permintaan ekspor. Jika token resolver tidak ada atau mengembalikan null, ekspor akan dilewati secara diam-diam. Pastikan kode Anda mengimplementasikan penyelesai token dengan benar. Untuk informasi lebih lanjut, lihat Penyelesai token.

• Periksa log untuk kesalahan

  Aktifkan pengelogan verbose dan gunakan perintah az webapp log tail untuk mencari kesalahan terkait observabilitas di log. Untuk detail tentang cara mengaktifkan pengelogan di setiap platform, lihat Validasi secara lokal.

  # Look for observability-related errors
  az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
  

• Verifikasi ekspor telemetri

  Pastikan telemetri dihasilkan dan diekspor sesuai harapan.

  • Tambahkan pengekspor konsol dan periksa apakah telemetri dihasilkan secara lokal. Untuk detail tentang cara menggunakan pengekspor konsol dan memvalidasi output, lihat Validasi secara lokal.

ID penyewa atau ID agen hilang — rentang diabaikan

Gejala: Sistem secara diam-diam mengabaikan rentang dan tidak pernah mengekspornya. Beberapa SDK mencatat jumlah span yang dilewati atau menampilkan pesan seperti "Tidak ada span dengan identitas penyewa/agen." SDK lain membuangnya tanpa mencatat di log.

Resolution:

• Sebelum diekspor, SDK membagi span berdasarkan identitas penyewa dan agen. Sistem menghilangkan span yang tidak memiliki ID penyewa atau ID agen dan tidak pernah mengirimkannya ke layanan.
• Pastikan BaggageBuilder telah disiapkan dengan ID penyewa dan ID agen sebelum membuat rentang. Nilai ini diteruskan melalui konteks OpenTelemetry dan melekat pada semua rentang yang dibuat dalam cakupan bagasi. Untuk API khusus platform, lihat Atribut bagasi.
• Pastikan aktivitas TurnContext memiliki penerima yang valid dengan identitas agen jika Anda menggunakan middleware baggage atau pembantu konteks turn dari paket integrasi hosting untuk mengisi ID-ID tersebut.

Kegagalan resolusi token — ekspor dilewati atau tidak diizinkan

Gejala: Token resolver mengembalikan null atau melempar kesalahan. Bergantung pada SDK, ekspor dapat dilewati sepenuhnya atau permintaan dikirim tanpa header otorisasi dan gagal dengan HTTP 401.

Resolution:

• Penyelesai token diperlukan saat inisialisasi. Jika tidak tersedia, eksportir melempar kesalahan saat memulai. Verifikasi bahwa token resolver telah disediakan dan mengembalikan token pembawa yang valid.
• Pastikan ID penyewa dan ID agen yang benar digunakan untuk BaggageBuilder, karena nilai-nilai ini akan diteruskan ke penyelesai token.
• Untuk agen yang di-host di Azure, pastikan Identitas Terkelola memiliki izin API yang diperlukan untuk cakupan observabilitas.

HTTP 401 Tidak Sah

Gejala: Ekspor gagal dengan HTTP 401. Eksportir tidak mencoba ulang kesalahan ini.

Resolution:

• Verifikasi bahwa audiens token sesuai dengan cakupan titik akhir observabilitas.
• Periksa apakah token resolver tidak mengembalikan token pengguna delegasi, token untuk audiens yang salah, atau token kedaluwarsa.

Pelarangan HTTP 403

Gejala: Ekspor gagal dengan HTTP 403. Eksportir tidak mencoba ulang kesalahan ini.

Penyebab utama: Kesalahan HTTP 403 dapat memiliki berbagai penyebab. Periksa resolusi berikut secara berurutan.

Resolution:

• Lisensi hilang — Verifikasi bahwa penyewa Anda memiliki salah satu lisensi berikut yang ditetapkan di Pusat admin Microsoft 365:

  • Uji - Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Izin Agent365.Observability.OtelWrite hilang — Jika Anda baru saja memperbarui paket observability Anda, Anda harus memberikan izin ini. Lihat catatan penting di bagian berikutnya.

Penting

Agen yang sudah ada yang memutakhirkan ke versi paket ini memerlukan langkah tambahan

Langkah ini hanya berlaku jika Anda memutakhirkan agen yang ada. Instalasi agen baru tidak memerlukan langkah ini. Jika Anda memutakhirkan ke versi paket berikutnya atau yang lebih baru, Anda harus memberikan izin Agent365.Observability.OtelWrite baru ke identitas Anda (Identitas Terkelola atau pendaftaran aplikasi). Tanpa izin ini, ekspor telemetri gagal dengan HTTP 403.

Platform	Versi minimum yang memerlukan langkah ini
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Memberikan izin dapat dilakukan dengan menggunakan salah satu opsi berikut.

Opsi A — Agent 365 CLI (memerlukan akun Administrator Global; jalankan dari direktori proyek agent yang berisi a365.config.json, atau gunakan --agent-name)

a365 setup permissions bot

Atau, tanpa file konfigurasi:

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

Perintah ini memberikan semua izin yang belum diberikan pada blueprint, termasuk cakupan Observability.

Opsi B — Portal Entra (file config tidak diperlukan; memerlukan akses Administrator Global ke pendaftaran aplikasi blueprint)

1. Buka portal Entra>Pendaftaran Aplikasi> pilih aplikasi Blueprint Anda.
2. Buka Izin API>Tambah izin>API yang digunakan organisasi saya> cari 9b975845-388f-4429-889e-eab1ef63949c.
3. Pilih Izin yang didelegasikan> periksa Agent365.Observability.OtelWrite>Tambah izin.
4. Ulangi langkah 2–3, kali ini pilih Izin aplikasi>, centang Agent365.Observability.OtelWrite>Tambahkan izin.
5. Klik Berikan persetujuan admin dan konfirmasi.

Baik Agent365.Observability.OtelWrite (Didelegasikan) maupun Agent365.Observability.OtelWrite (Aplikasi) harus menunjukkan status Granted.

HTTP 403 Forbidden — Ketidakcocokan ID Agen

Gejala: Ekspor gagal dengan HTTP 403 dan pesan server yang mirip dengan 403 Forbidden dengan agent-ID-mismatch gagal memanggil titik akhir pelacakan Agent 365.

Akar penyebab: Kesalahan ini terjadi ketika Anda menggunakan ID klien blueprint bukan ID klien instans agen saat mengatur detail agen. ID agen pada URL ekspor tidak sesuai dengan identitas yang diotorisasi oleh token, sehingga titik akhir pelacakan menolak permintaan tersebut.

Resolution:

• Verifikasi apakah ID penyewa telah ditambahkan ke daftar penyewa yang diizinkan Agent 365.
• Atur detail agen dengan ID klien instans agen (bukan ID klien blueprint).
• Verifikasi URL ekspor yang dihasilkan – URL tersebut dicatat jika Anda mengaktifkan logger. Pastikan ID agen pada URL sesuai dengan ID klien instans agen.
• Untuk mengaktifkan pembuatan log diagnostik per SDK, lihat Validasi secara lokal.

Kesalahan HTTP 429 atau 5xx - Kesalahan sementara

Gejala: Ekspor gagal dengan kode status HTTP sementara seperti 429 atau 5xx.

Resolution:

• Kesalahan ini biasanya bersifat sementara dan akan teratasi sendiri. SDK Python dan JavaScript secara otomatis melakukan percobaan ulang pada kode status HTTP 408, 429, dan 5xx hingga tiga kali dengan backoff eksponensial. SDK .NET tidak melakukan percobaan ulang secara otomatis.
• Jika kesalahan berlanjut, periksa dasbor kesehatan layanan.
• Pertimbangkan untuk mengurangi frekuensi ekspor dengan memperpanjang waktu tunda terjadwal antar-batch atau memperbesar ukuran batch ekspor maksimum. Untuk opsi konfigurasi per platform, lihat tabel Agent365ExporterOptions di Konfigurasi.

Batas waktu ekspor

Gejala: Batas waktu upaya ekspor.

Resolution:

• Periksa konektivitas jaringan ke titik akhir observabilitas.
• Pengaturan batas waktu default berbeda untuk setiap platform. Batas waktu default permintaan HTTP adalah 30 detik. Beberapa SDK juga memiliki batas waktu pengekspor keseluruhan terpisah yang mencakup seluruh siklus ekspor, termasuk percobaan ulang. Untuk properti dan default yang tepat per platform, lihat tabel Agent365ExporterOptions di Konfigurasi.
• Jika waktu habis sering terjadi, tingkatkan nilai batas waktu yang relevan pada pengaturan pengekspor Anda.

Ekspor berhasil tetapi telemetri tidak muncul di Defender atau Purview

Gejala: Log menunjukkan ekspor yang berhasil tetapi telemetri tidak muncul di Microsoft Defender atau Microsoft Purview.

Resolution:

• Pastikan Anda memenuhi prasyarat untuk melihat log yang diekspor. Untuk Purview, audit harus diaktifkan. Untuk Defender, Anda harus mengonfigurasi perburuan lanjutan. Untuk informasi selengkapnya, lihat Melihat log diekspor.
• Telemetri dapat membutuhkan beberapa menit untuk muncul setelah ekspor berhasil. Tunggu hingga data muncul sebelum menyelidiki lebih lanjut.

Untuk informasi lebih lanjut tentang pengujian observabilitas, lihat:

• Panduan pengujian - Melihat log observabilitas
• Konfigurasi observabilitas

Konten terkait

• Konsep observabilitas Agent 365 - Alur data, model identitas, autentikasi, cakupan, dan batas yang berlaku untuk setiap jalur integrasi.
• Referensi atribut observabilitas Agent 365 - Skema atribut rentang kanonik yang harus sesuai dengan setiap rentang yang diserap ke Agent 365.
• Microsoft OpenTelemetry Distro - SDK terpadu yang direkomendasikan untuk integrasi baru