可觀察性 SDK

重要

若要在 Agent 365 中啟用可觀察性，請使用 Microsoft OpenTelemetry Distro。這個發行版在 Microsoft 各產品中提供單一可觀察性 SDK，為 Agent 365、Microsoft Foundry、Azure 監視器等提供支援。本文所述的現有做法會持續運作，不會有重大變更。如需依語言劃分的移轉指引，請參閱下列指南：

Python 移轉指南
JavaScript/TypeScript 移轉指南
.NET 移轉指南。如需適用於所有整合路徑的基礎資料模型、身分識別與驗證、範圍與同意，以及限制，請參閱 Agent 365 可觀察性概念。

注意

可觀察性是開始使用 Agent 365 開發中漸進式功能層級之一，適用於所有 Agent 類型。

若要參與 Agent 365 生態系統，請為您的 Agent 新增 Agent 365 可觀察性功能。 Agent 365 可觀察性以 OpenTelemetry (OTel) 為基礎，提供統一的架構，可在所有 Agent 平台上一致且安全地擷取遙測資料。實作這個必要元件後，IT 管理員即可在 Microsoft 系統管理中心監控您 Agent 的活動，安全性團隊也能使用 Defender 和 Purview 進行合規性與威脅偵測。

重點優勢

端對端可見性：擷取每次 Agent 叫用的完整遙測資料，包括工作階段、工具呼叫和例外狀況，讓您在各平台間都有完整的追蹤能力。
安全性與合規性強化：將統一的稽核記錄饋入 Defender 和 Purview，為您的 Agent 啟用進階安全性案例與合規性報告。
跨平台彈性：以 OTel 標準為基礎，支援 Copilot Studio、Foundry 等多元執行階段與平台，以及未來的 Agent 架構。
提升管理員作業效率：在 Microsoft 365 系統管理中心提供集中式可觀察性，縮短疑難排解時間，並透過角色型存取控制，為管理您 Agent 的 IT 團隊改善治理。

支援的 Agent

下列 Agent 類型支援 Agent 365 可觀察性：

已啟用 Microsoft Agent 365 的 Agent：使用可觀察性 SDK 對您的 Agent 進行檢測。
自訂引擎 Agent：使用可觀察性 SDK 對您的 Agent 進行檢測。
宣告式 Agent：開箱即用即支援可觀察性。不需要實作 SDK。

安裝

使用下列命令，為 Agent 365 支援的語言安裝可觀察性模組。

安裝核心可觀察性和執行階段套件。所有使用 Agent 365 可觀察性的 Agent 都需要這些套件。

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

如果您的 Agent 使用 Microsoft Agents Hosting 套件，請安裝適用於裝載的整合套件。這項元件提供中介軟體，可自動從 TurnContext 填入 Baggage 與範圍，並內建可觀察性匯出工具所需的權杖快取功能。

pip install microsoft-agents-a365-observability-hosting

如果您的 Agent 使用其中一個支援的 AI 架構，請安裝對應的自動檢測擴充功能，即可自動擷取遙測資料，而不需要手動撰寫檢測程式碼。如需設定詳細資料，請參閱自動檢測。

# 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

安裝核心可觀察性和執行階段套件。所有使用 Agent 365 可觀察性的 Agent 都需要這些套件。

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

如果您的 Agent 使用 @microsoft/agents-hosting 套件，請安裝適用於裝載的整合套件。這項元件提供中介軟體，可自動從 TurnContext 填入 Baggage 與範圍，並內建可觀察性匯出工具所需的權杖快取功能。

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

安裝核心可觀察性和執行階段套件。所有使用 Agent 365 可觀察性的 Agent 都需要這個套件。

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

如果您的 Agent 使用 Microsoft.Agents.A365.Observability.Hosting NuGet 套件，請安裝適用於裝載的整合套件。這項元件提供中介軟體，可自動從 TurnContext 填入 Baggage，並內建可觀察性匯出工具所需的權杖快取功能。

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

組態

使用下列設定，為您的 Agent 啟用並自訂 Agent 365 可觀察性。

若要啟用可觀察性，請將 ENABLE_A365_OBSERVABILITY_EXPORTER 環境變數設為 true。這項設定會將記錄匯出至服務，且需要提供 token_resolver。否則會使用主控台匯出工具。

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

權杖解析器不會記錄到主控台。

您可以將 Agent365ExporterOptions 執行個體傳遞至 exporter_options，藉此自訂匯出工具的行為。提供 exporter_options 時，其優先順序高於 token_resolver 和 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,
)

下表說明 configure() 的選擇性參數。

參數	描述	預設
`logger_name`	用於偵錯與主控台記錄輸出的 Python 記錄器名稱。	`microsoft_agents_a365.observability.core`
`exporter_options`	一併設定權杖解析器與叢集類別的 `Agent365ExporterOptions` 執行個體。	`None`
`suppress_invoke_agent_input`	設為 `True` 時，會隱藏 `InvokeAgent` Span 上的輸入訊息。	`False`

下表說明 Agent365ExporterOptions 的選擇性屬性。

屬性	說明	預設
`use_s2s_endpoint`	`True` 時，請使用服務到服務端點路徑。	`False`
`max_queue_size`	批次處理器的最大佇列大小。	`2048`
`scheduled_delay_ms`	匯出批次之間的延遲 (以毫秒為單位)。	`5000`
`exporter_timeout_ms`	匯出作業的逾時時間 (以毫秒為單位)。	`30000`
`max_export_batch_size`	匯出作業的最大批次大小。	`512`

若要啟用可觀察性，請將 ENABLE_A365_OBSERVABILITY_EXPORTER 環境變數設為 true。這項設定會將記錄匯出至服務，且需要提供權杖解析器。否則會使用主控台匯出工具。

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

除了環境變數之外，您也可以透過 withConfigurationProvider 方法使用設定提供者，以程式設計方式設定可觀察性。如果您也使用個別的建置器方法 (例如 withExporterOptions 或 withClusterCategory)，則這些個別建置器方法的優先順序高於設定提供者所提供的值。

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

您可以將 Agent365ExporterOptions 執行個體傳遞至 withExporterOptions，藉此自訂匯出工具的行為。這個選項可讓您控制批次處理、逾時，以及路由模式。

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

下表說明 Agent365ExporterOptions 的選擇性屬性。

屬性	說明	預設
`useS2SEndpoint`	`true` 時，請使用服務到服務端點路徑。	`false`
`maxQueueSize`	批次處理器的最大佇列大小。	`2048`
`scheduledDelayMilliseconds`	匯出批次之間的延遲 (以毫秒為單位)。	`5000`
`exporterTimeoutMilliseconds`	整個匯出作業的逾時時間 (以毫秒為單位)。	`90000`
`httpRequestTimeoutMilliseconds`	每個個別 HTTP 要求到後端的逾時時間 (以毫秒為單位)。	`30000`
`maxExportBatchSize`	匯出作業的最大批次大小。	`512`

您也可以提供實作 ILogger 介面 (info、warn、error、event) 的自訂記錄器。使用 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();

在 appsettings.json 中，將 EnableAgent365Exporter 設為 true。

在 Program.cs 中，將 Agent365ExporterOptions 新增至服務集合。這項變更會設定追蹤匯出工具用來取得權杖的委派 (delegate)。

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

您可以將設定委派與匯出工具類型傳遞至 AddA365Tracing()，藉此自訂匯出工具的行為。

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

下表說明 Agent365ExporterOptions 的選擇性屬性。

屬性	說明	預設
`UseS2SEndpoint`	`true` 時，請使用服務到服務端點路徑。	`false`
`MaxQueueSize`	批次處理器的最大佇列大小。	`2048`
`ScheduledDelayMilliseconds`	匯出批次之間的延遲 (以毫秒為單位)。	`5000`
`ExporterTimeoutMilliseconds`	匯出作業的逾時時間 (以毫秒為單位)。	`30000`
`MaxExportBatchSize`	匯出作業的最大批次大小。	`512`

Baggage 屬性

使用 BaggageBuilder 來設定可要求中所有跨度間流程的上下文資訊。 SDK 實現一個 SpanProcessor，能將所有非空的 Baggage 屬性複製到新啟動的跨度，且不會覆寫現有屬性。

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

若要從 TurnContext 自動填入 BaggageBuilder，請使用 microsoft-agents-a365-observability-hosting 套件中的 populate 協助程式。此協助工具會自動從活動中擷取呼叫者、Agent、租用戶、管道和交談詳細資料。

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

若要從 TurnContext 自動填入 BaggageBuilder，請使用 @microsoft/agents-a365-observability-hosting 套件中的 fromTurnContext 協助程式。此協助工具會自動從活動中擷取呼叫者、Agent、租用戶、管道和交談詳細資料。

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.

若要自動從 ITurnContext 填入 BaggageBuilder，請使用 Microsoft.Agents.A365.Observability.Hosting 套件內的 FromTurnContext 擴充功能方法。此方法會自動從活動中擷取呼叫者、Agent、租用戶、管道和交談詳細資料。

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

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

Baggage 中介軟體

如果您的 Agent 使用整合套件，請註冊 Baggage 中介軟體，讓每個傳入的要求自動填入 Baggage 。此步驟能免除在每個活動處理常式中手動呼叫 BaggageBuilder 的需求。

在配接器中介軟體集上註冊 BaggageMiddleware。它會自動從每個傳入的 TurnContext 中擷取呼叫者、Agent、租用戶、管道和交談詳細資料，並將要求裝合在 Baggage 範圍內。

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

或者，您也可以使用 ObservabilityHostingManager 設定 Baggage 中介軟體及其他裝載功能：

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

中介軟體會跳過非同步回覆 (ContinueConversation 事件) 的 Baggage 設定，以避免覆寫原始要求已設定的 Baggage。

在配接器上註冊 BaggageMiddleware。它會自動從每個傳入的 TurnContext 中擷取呼叫者、Agent、租用戶、管道和交談詳細資料，並將要求裝合在 Baggage 範圍內。

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

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

或者，您也可以使用 ObservabilityHostingManager 設定 Baggage 中介軟體及其他裝載功能：

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

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

中介軟體會跳過非同步回覆 (ContinueConversation 事件) 的 Baggage 設定，以避免覆寫原始要求已設定的 Baggage。

在配接器上註冊 BaggageTurnMiddleware。它會自動從每個傳入的 ITurnContext 中擷取呼叫者、Agent、租用戶、管道和交談詳細資料，並將要求裝合在 Baggage 範圍內。

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

adapter.Use(new BaggageTurnMiddleware());

中介軟體會跳過非同步回覆 (ContinueConversation 事件) 的 Baggage 設定，以避免覆寫原始要求已設定的 Baggage。

如果您需要 HTTP層級的 Baggage (例如，在 Bot Framework 管線執行前設定租用戶和 Agent 識別碼)，請使用 UseObservabilityRequestContext 擴充功能方法，將 ObservabilityBaggageMiddleware 註冊到 ASP.NET Core管線中。您必須提供一個解析器函式，從 HTTP 上下文中擷取租用戶識別碼和 Agent 識別碼。

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

權杖解析器

使用 Agent 365 匯出工具時，您必須提供會傳回驗證權杖的權杖解析器函式。搭配 Agent Hosting 架構使用 Agent 365 可觀察性 SDK 時，您可以透過 Agent 活動中的 TurnContext 產生權杖。

下列程式碼片段示範如何使用 microsoft_agents.hosting.core SDK 產生權杖。這裡產生的驗證權杖，會用於將 Span 匯出至 A365 擷取服務。 Agent 可以自行產生權杖，例如使用 Microsoft 驗證資源庫 (MSAL)，但必須確保權杖具有可觀察性範圍。

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

若 Agent 是透過 A365 CLI 建置，並使用 AI 隊友與 Microsoft Agent 365 Observability Hosting Library 套件，請使用 AgenticTokenCache 自動處理權杖快取。在活動處理常式中，針對每個 Agent 與租用戶註冊一次權杖，並在可觀察性設定中，將 cache.get_observability_token 做為 token_resolver 傳入。

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

下列程式碼片段示範如何使用 @microsoft/agents-hosting SDK 產生權杖。這裡產生的驗證權杖，會用於將 Span 匯出至 A365 擷取服務。 Agent 可以自行產生權杖，例如使用 Microsoft 驗證資源庫 (MSAL)，但必須確保權杖具有可觀察性範圍。

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

若 Agent 是透過 A365 CLI 建置，並使用 AI 隊友與 @microsoft/agents-a365-observability-hosting 套件，請使用 AgenticTokenCacheInstance 自動處理權杖快取。在活動處理常式中，針對每個 Agent 與租用戶呼叫一次 RefreshObservabilityToken，並在可觀察性設定中，將 AgenticTokenCacheInstance.getObservabilityToken 做為 tokenResolver 傳入。

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

下列程式碼片段示範如何使用 Microsoft.Agents 裝載 SDK 產生權杖。使用您產生的驗證權杖，將 Span 匯出至 A365 擷取服務。 Agent 可以自行產生權杖，例如使用 Microsoft 驗證資源庫 (MSAL)，但必須確保權杖具有可觀察性範圍。

藉由向 TokenResolver Delegate 註冊 Agent365ExporterOptions，提供權杖解析器。這個委派會接收 agentId 與 tenantId，並傳回驗證權杖。

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

若 Agent 是透過 A365 CLI 建置，並使用 AI 隊友與 Microsoft.Agents.A365.Observability.Hosting NuGet 套件，請使用 AddAgenticTracingExporter() 方法，透過相依性插入自動處理權杖快取。

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

在 Agent 應用程式中註冊權杖。

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

自動檢測

自動檢測會自動監聽代理式架構 (SDK) 現有的追蹤遙測訊號，並將其轉送至 Agent 365 可觀察性服務。這項功能可讓開發人員不必手動撰寫監控程式碼，簡化設定作業，並確保效能追蹤的一致性。

重要

自動檢測僅會填入標準 OTel 屬性。您必須使用 BaggageBuilder 來新增 Microsoft 特定的屬性。若要查看缺少哪些屬性，請對照市集記錄檢查您的主控台 Span 輸出，以取得差異集。

多個 SDK 與平台皆支援自動檢測：

平台	支援的 SDK / 架構
.NET	語意核心、OpenAI、Agent Framework
Python	語意核心、OpenAI、Agent Framework、LangChain
Node.js	OpenAI、LangChain

注意

自動檢測的支援程度會依平台與 SDK 實作而異。

語意核心

自動檢測需要使用 Baggage 建置器。使用 BaggageBuilder 設定 Agent 識別碼與租用戶識別碼。

安裝套件。

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

設定可觀察性。

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

將相依性新增至服務集合。

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

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

使用 BaggageBuilder 設定 AgentId 與 TenantId。請確認建立 ChatCompletionAgent 時所用的識別碼，與您傳遞給 BaggageBuilder 的 Agent 識別碼一致。

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

自動檢測需要使用 Baggage 建置器。使用 BaggageBuilder 設定 Agent 識別碼與租用戶識別碼。

安裝套件。

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

設定可觀察性。

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

安裝套件。

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

設定可觀察性。

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

將相依性新增至服務集合。

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

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

使用 BaggageBuilder 設定 AgentId 與 TenantId。針對工具呼叫，請在 ChatToolCall 執行個體上使用 Trace() 啟動追蹤。

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

自動檢測需要使用 Baggage 建置器。使用 BaggageBuilder 設定 Agent 識別碼與租用戶識別碼。

安裝套件。

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

設定可觀察性。

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

將相依性新增至服務集合。

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

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

使用 BaggageBuilder 設定 AgentId 與 TenantId。

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

自動檢測需要使用 Baggage 建置器。使用 BaggageBuilder 設定 Agent 識別碼與租用戶識別碼。

安裝套件。

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

設定可觀察性。

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

安裝套件。

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

設定可觀察性。

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

手動檢測

使用 Agent 365 可觀察性 SDK 了解 Agent 的內部運作方式。 SDK 提供您可以啟動的範圍：InvokeAgentScope、ExecuteToolScope、InferenceScope 與 OutputScope。

Agent 叫用

在您的 Agent 處理程序開始時使用這個範圍。使用叫用 Agent 範圍，您可以擷取目前所叫用的 Agent、Agent 使用者資料等屬性。

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

如果您的 Agent 使用 @microsoft/agents-a365-observability-hosting 套件，您可以使用 ScopeUtils.populateInvokeAgentScopeFromTurnContext 建立範圍，並自動從 TurnContext 衍生 Agent 詳細資料、呼叫者詳細資料及通道資訊。

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

工具執行

下列範例示範如何為您 Agent 的工具執行新增可觀察性追蹤。這項追蹤會擷取遙測資料，以供監控與稽核之用。

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

如果您的 Agent 使用 @microsoft/agents-a365-observability-hosting 套件，請使用 ScopeUtils.populateExecuteToolScopeFromTurnContext 建立範圍，並自動從 TurnContext 衍生 Agent 詳細資料。

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

推斷

下列範例示範如何為 AI 模型推斷呼叫加上可觀察性追蹤檢測，以擷取權杖使用量、模型詳細資料及回應中繼資料。

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

如果您的 Agent 使用 @microsoft/agents-a365-observability-hosting 套件，您可以使用 ScopeUtils.populateInferenceScopeFromTurnContext 建立範圍，並自動從 TurnContext 衍生 Agent 詳細資料。

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

輸出

當 InvokeAgentScope、ExecuteToolScope 或 InferenceScope 無法同步擷取輸出資料時，請針對非同步案例使用這個範圍。將 OutputScope 啟動為子 Span，在父範圍完成後記錄最終的輸出訊息。

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

在本機驗證

若要驗證您已成功整合可觀察性 SDK，請檢查您 Agent 產生的主控台記錄，以及可觀察性 SDK 的記錄。

將 ENABLE_A365_OBSERVABILITY_EXPORTER 環境變數設定為 false。這項設定會將 Span (追蹤) 匯出至主控台。

若要調查匯出失敗的問題，請將 ENABLE_A365_OBSERVABILITY_EXPORTER 設為 true，並在應用程式啟動時設定偵錯記錄，以啟用詳細記錄：

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)

主要記錄訊息：

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.

將 ENABLE_A365_OBSERVABILITY_EXPORTER 環境變數設定為 false。這項設定會將 Span (追蹤) 匯出至主控台。

若要調查匯出失敗的問題，請在 .env 或殼層 (shell) 中設定環境變數：

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

檢查主控台輸出中類似下列的訊息：

[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

您也可以選擇使用自訂記錄器，將匯出事件擷取到檔案中：

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

在 appsettings.json 中，將 EnableAgent365Exporter 設為 false。這項設定會將 Span (追蹤) 匯出至主控台。

若要調查匯出失敗的問題，請在 appsettings.json 中設定詳細記錄：

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

或設定環境變數：

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

主要記錄訊息：

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.

注意

如果您未在 DI 中註冊 ILoggerFactory，匯出工具會自動回復使用主控台記錄器。

檢視已匯出的記錄

若要在 Microsoft Purview 或 Microsoft Defender 中檢視 Agent 遙測資料，請確保符合以下要求：

Microsoft Purview：您的組織必須開啟稽核功能。如需指示，請參閱開啟或關閉稽核。
Microsoft Defender：必須設定進階搜捕功能，才能存取 CloudAppEvents資料表。詳情請參閱進階搜捕結構妙術中的 CloudAppEvents 資料表。

驗證是否可發佈至市集

重要

若要通過市集驗證，您的 Agent 必須實作 InvokeAgentScope、InferenceScope 及 ExecuteToolScope 範圍。發佈時必須具備這三個範圍。

發佈之前，請實作必要的 invoke agent、execute tool、inference 及 output 範圍，並使用主控台記錄驗證您 Agent 的可觀察性整合。接著，將您 Agent 的記錄與下列屬性清單進行比對，確認所有必要屬性皆已具備。在每個範圍或透過 Baggage 建置器擷取屬性，並可視需要納入選擇性屬性。

如需市集發佈需求的詳細資訊，請參閱市集驗證準則。

`InvokeAgentScope` 屬性

下列清單彙總啟動 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` 屬性

下列清單彙總啟動 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` 屬性

下列清單彙總啟動 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` 屬性

下列清單彙總啟動 OutputScope 時所記錄的必要與選擇性遙測屬性。當父範圍無法同步擷取輸出資料時，請針對非同步案例使用這個範圍。

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

使用可檢視性測試您的 Agent

在您的 Agent 中實作可觀察性之後，請進行測試，確保能正確擷取遙測資料。請遵循測試指南設定您的環境。接著，請主要參閱檢視可觀察性記錄一節，驗證您的可觀察性實作是否如預期運作。

驗證：

前往： https://admin.cloud.microsoft/#/agents/all
選取您的 Agent >活動
您會看到工作階段與工具呼叫

疑難排解

本節說明實作與使用可觀察性時常見的問題。

問題回報	Description
可檢視性資料未顯示	因為未啟用匯出、設定不正確，或權杖解析失敗，所以看不到任何遙測資料。
遺漏租用戶識別碼或 Agent 識別碼 - 已跳過跨度	如果缺少分割所需的身分識別屬性，Span 會在匯出前遭到捨棄。
權杖解析失敗 - 匯出跳過或未經授權	如果解析器未傳回權杖或發生例外狀況，匯出要求就會失敗或遭到略過。
HTTP 401 未授權	驗證在語法上成功，但因為範圍、類型或過期等因素，導致權杖對擷取而言無效。
HTTP 403 禁止	因為租用戶授權缺口或缺少可觀察性權限，所以存取遭拒。
HTTP 403 禁止 - Agent 識別碼不符	如果 URL 中的 Agent 身分識別與權杖所代表的身分識別不符，要求就會遭到拒絕。
HTTP 429 或 5xx 錯誤 - 暫時性錯誤	暫時的節流或服務端故障會中斷匯出，可能需要調整重試設定。
匯出逾時	因為網路延遲或端點回應速度，遙測批次超過設定的逾時範圍。
匯出成功，但 Defender 或 Purview 中未顯示遙測資料	擷取已完成，但下游的可見性因產品必要條件而延遲或遭到封鎖。

提示

Agent 365 疑難排解指南包含高階疑難排解建議、最佳做法，以及每個階段的疑難排解連結，涵蓋 Agent 365 開發生命週期的所有部分。

可檢視性資料未顯示

徵狀：

Agent 正在執行
系統管理中心中沒有遙測資料
無法查看 Agent 活動

根本原因：

未啟用可觀察性
組態錯誤
權杖解析器問題

解決方案：嘗試以下步驟來解決問題：

驗證可觀察性匯出工具是否已啟用

您必須明確啟用 Agent 365 匯出器。停用時，SDK 會回復使用主控台匯出工具，且不會將遙測資料傳送至服務。如需設定詳細資料，請參閱設定。
檢查權杖解析器設定

匯出器需要一個有效的權杖解析器，可為每個匯出要求傳回一個持有人權杖。如果遺漏權杖解析器或傳回 null，匯出會靜默跳過。請確認您的程式碼已正確實作權杖解析器。如需詳細資料，請參閱權杖解析器。
檢查記錄中的錯誤

啟用詳細記錄，並使用 az webapp log tail 命令搜尋記錄中與可觀察性相關的錯誤。如需依平台啟用記錄的詳細資料，請參閱在本機驗證。
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
驗證遙測資料匯出

確認遙測資料已如預期產生並匯出。
- 新增主控台匯出工具，並檢查是否已在本機產生遙測資料。如需如何使用主控台匯出工具及驗證輸出的詳細資料，請參閱在本機驗證。

遺漏租用戶識別碼或 Agent 識別碼 — 已跳過跨度

症狀：系統會靜默丟棄跨度，並永不將其匯出。部分 SDK 會記錄遭略過的 Span 數量，或顯示類似「找不到具有租用戶/Agent 身分識別的 Span」的訊息；其他 SDK 則會直接捨棄，不會記錄。

解決方法：

匯出之前，SDK 會依租用戶與 Agent 身分識別分割 Span。系統會捨棄缺少租用戶識別碼或 Agent 識別碼的 Span，且絕不會將其傳送至服務。
確保 BaggageBuilder 在建立跨度前，已經設定好租用戶識別碼和 Agent 識別碼。這些值會透過 OpenTelemetry 上下文傳播，並附加於所有在 Baggage 範圍內建立的跨度上。如需平台專屬的 API，請參閱 Baggage 屬性。
如果您使用裝載整合套件中的 Baggage 中介軟體或 Turn Context 協助程式來填入這些識別碼，請確認 TurnContext 活動具有含 Agent 身分識別的有效收件者。

權杖解析失敗 — 匯出跳過或未經授權

症狀：權杖解析器傳回 null 或拋出錯誤。視 SDK 而定，匯出作業可能會完全略過，或要求在未附加授權標頭的情況下傳送，並因 HTTP 401 而失敗。

解決方法：

初始化時必須提供權杖解析器。如果遺漏，匯出器會在啟動時拋出錯誤。驗證已提供權杖解析器，且能傳回有效的持有人權杖。
請確認 BaggageBuilder 使用的租用戶識別碼與 Agent 識別碼正確無誤，因為這些值會傳遞給權杖解析器。
對於在 Azure 上託管的 Agent，請驗證受管理識別具有可檢視性範圍所需的 API 權限。

HTTP 401 未授權

症狀：匯出失敗，並出現 HTTP 401 錯誤。匯出器不會重試這個錯誤。

解決方法：

驗證權杖對象是否符合可檢視性端點範圍。
檢查權杖解析器是否未傳回委派使用者權杖、對象不正確的權杖，或是過期權杖。

HTTP 403 禁止

症狀：匯出失敗，並出現 HTTP 403 錯誤。匯出器不會重試這個錯誤。

根本原因：HTTP 403 錯誤可能有多種原因。請依序檢查以下解決方案。

解決方法：

遺漏授權 — 請驗證您的租用戶在 Microsoft 365 系統管理中心中，已指派以下其中一項授權：
- 測試 - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
缺少 Agent365.Observability.OtelWrite 權限 — 如果您最近升級了可觀察性套件，就需要授與這項權限。請參閱下一節中的重要注意事項。

重要

升級至這些套件版本的現有 Agent 需要執行額外步驟

這個步驟僅適用於升級現有 Agent 的情況。新安裝的 Agent 不需要這個步驟。如果您要升級至下列套件版本或更新版本，必須將新的 Agent365.Observability.OtelWrite 權限授與您的身分識別 (受控識別或應用程式註冊)。若無此權限，遙測資料匯出將因 HTTP 403 而失敗。

平台	需要執行這個步驟的最低版本
.NET	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

請使用下列其中一個選項授與權限。

選項 A — Agent 365 CLI (需要全域管理員帳戶；請從包含 a365.config.json 的 Agent 專案目錄執行，或使用 --agent-name)

a365 setup permissions bot

或者，無需組態檔：

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

這個命令會授與藍圖上所有缺少的權限，包括可觀察性範圍。

選項 B — Entra 入口網站 (不需要設定檔；需要對藍圖應用程式註冊擁有全域管理員存取權)

移至 Entra 入口網站>應用程式註冊>，選取您的 Blueprint 應用程式。
移至 API 權限>新增權限>我的組織使用的 API> 尋找 9b975845-388f-4429-889e-eab1ef63949c。
選取委派權限>，勾選Agent365.Observability.OtelWrite>新增權限。
重複執行步驟 2–3，這次改選取應用程式權限>，勾選 Agent365.Observability.OtelWrite>新增權限。
按一下授與管理員同意並確認。

Agent365.Observability.OtelWrite (委派) 與 Agent365.Observability.OtelWrite (應用程式) 都應顯示 Granted 狀態。

HTTP 403 禁止 — Agent 識別碼不符

症狀：匯出時因 HTTP 403 而失敗，並收到類似 403 Forbidden 和 agent-ID-mismatch 的伺服器訊息，且在呼叫 Agent 365 追蹤端點時發生失敗。

根本原因：在您設定 Agent 詳細資料時，您使用藍圖用戶端識別碼而非 Agen t執行個體用戶端識別碼，就會導致此錯誤。匯出 URL 中的 Agent 識別碼與權杖授權的身分識別不相符，因此追蹤端點拒絕要求。

解決方法：

驗證租用戶識別碼是否已新增至 Agent 365 允許租用戶清單。
將 Agent 詳細資料設定為 Agent 執行個體用戶端識別碼 (而非藍圖用戶端識別碼)。
驗證產生的匯出 URL - 如果您啟用記錄器，會將它記錄下來。確認 URL 中的Agent 識別碼與 Agent 執行個體用戶端識別碼相符。
如需依 SDK 啟用診斷記錄的詳細資料，請參閱在本機驗證。

HTTP 429 或 5xx 錯誤 - 暫時性錯誤

症狀：匯出因暫時性 HTTP 狀態碼 (例如 429 或 5xx) 而失敗。

解決方法：

這些錯誤通常是暫時性的，會自行解決。 Python 與 JavaScript SDK 會針對 HTTP 408、429 及 5xx 狀態碼，以指數輪詢間隔自動重試最多三次。 .NET SDK 不會自動重試。
如果錯誤持續，請檢查服務健康狀態儀表板。
請考慮增加批次之間的排程延遲，或增加匯出批次的大小上限，藉此降低匯出頻率。如需依平台劃分的設定選項，請參閱設定中的 Agent365ExporterOptions 資料表。

匯出逾時

症狀：匯出嘗試逾時。

解決方法：

檢查與可檢視性端點的網路連線。
逾時的預設值會依平台而異。預設的 HTTP 要求逾時為 30 秒。部分 SDK 也另外提供整體匯出工具逾時設定，涵蓋包括重試在內的整個匯出週期。如需依平台劃分的確切屬性與預設值，請參閱設定中的 Agent365ExporterOptions 資料表。
如果經常發生逾時，請增加匯出工具選項中的相關逾時值。

匯出成功，但 Defender 或 Purview 中未顯示遙測資料

徵狀：記錄顯示匯出成功，但在 Microsoft Defender 或 Microsoft Purview 中看不到遙測資料。

解決方法：

請確認您符合檢視已匯出記錄的必要條件。若為 Purview，必須開啟稽核功能。若為 Defender，您必須設定進階搜捕。如需詳細資訊，請參閱檢視已匯出的記錄。
遙測資料在成功匯出後可能需要數分鐘才能填入。請先等待資料出現，再進一步調查。

如需深入了解如何測試可觀察性，請參閱：

Agent 365 可檢視性概念 - 適用於每個整合路徑的資料流、身分識別模型、驗證、範圍與限制。
Agent 365 可檢視性屬性參考 - 每個由 Agent 365 擷取的跨度都必須遵循的 Canonical 跨度屬性結構描述。
Microsoft OpenTelemetry Distro - 適用於新整合的建議統一 SDK。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-30

可觀察性 SDK

重點優勢

支援的 Agent

安裝

組態

Baggage 屬性

Baggage 中介軟體

權杖解析器

自動檢測

語意核心

OpenAI

Agent Framework

LangChain Framework

手動檢測

Agent 叫用

工具執行

推斷

輸出

在本機驗證

檢視已匯出的記錄

驗證是否可發佈至市集

InvokeAgentScope 屬性

ExecuteToolScope 屬性

InferenceScope 屬性

OutputScope 屬性

使用可檢視性測試您的 Agent

疑難排解​​

可檢視性資料未顯示

遺漏租用戶識別碼或 Agent 識別碼 — 已跳過跨度

權杖解析失敗 — 匯出跳過或未經授權

HTTP 401 未授權

HTTP 403 禁止

HTTP 403 禁止 — Agent 識別碼不符

HTTP 429 或 5xx 錯誤 - 暫時性錯誤

匯出逾時

匯出成功，但 Defender 或 Purview 中未顯示遙測資料

相關內容

意見反應

其他資源

`InvokeAgentScope` 屬性

`ExecuteToolScope` 屬性

`InferenceScope` 屬性

`OutputScope` 屬性

疑難排解