代理可观测性

重要

若要在 Agent 365 中启用可观测性，请使用 Microsoft OpenTelemetry Distro。此软件包在整个 Microsoft 平台上提供一个统一的可观测性 SDK，支持 Agent 365、Microsoft Foundry、Azure Monitor 等服务。本文中所述的现有方法将继续工作，而无需重大更改。 Microsoft还将提供迁移指南，为客户提供充足的过渡时间。

注释

可观测性是 Agent 365 开发入门中的增量功能层之一，适用于所有代理类型。

要参与 Agent 365 生态系统，请为您的代理添加 Agent 365 可观测性功能。 Agent 365 可观测性构建于OpenTelemetry (OTel)之上，提供一个统一框架，用于在所有代理平台上持续且安全地捕获遥测数据。通过实现这一必需组件，你可以让IT管理员在Microsoft管理中心监控代理的活动，并允许安全团队使用Defender和Purview进行合规和威胁检测。

主要优点

端到端可视化：为每一次代理调用（包括会话、工具调用和异常）捕捉全面的遥测数据，实现跨平台的完整追踪。
安全与合规赋能：将统一审计日志输入Defender和Purview，为您的代理提供先进的安全场景和合规报告。
跨平台灵活性：基于 OTel 标准构建，支持多种运行时和平台，例如 Copilot Studio、Foundry 和未来的代理框架。
为管理员提高运作效率：在 Microsoft 365 管理中心提供集中式监控，减少故障排除时间，并通过基于角色的访问控制改进 IT 团队对代理的管理治理。

支持的代理

以下代理类型支持 Agent 365 可观测性：

已启用 Agent 365 的 Microsoft 代理：使用可观测性 SDK 监测您的代理。
自定义引擎代理：使用可观测性 SDK 检测代理。
声明性代理：可观测性开箱即用支持。不需要 SDK 实现。

安装

使用这些命令为代理 365 支持的语言安装可观测性模块。

安装核心可观测性和运行时包。使用 Agent 365 可观测性的所有代理都需要这些包。

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

如果代理使用 Microsoft Agents Hosting 包，请安装托管集成包。它提供中间件，能够从TurnContext自动填充上下文信息和作用域，并包括用于可观测性导出器的令牌缓存。

pip install microsoft-agents-a365-observability-hosting

如果代理使用其中一个受支持的 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 可观测性的所有代理都需要这些包。

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

如果代理使用 @microsoft/agents-hosting 包，请安装托管集成包。它提供中间件，能够从TurnContext自动填充上下文信息和作用域，并包括用于可观测性导出器的令牌缓存。

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 可观测性的所有代理都需要此软件包。

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

如果你的代理使用Microsoft.Agents.A365.Observability.Hosting NuGet 包，请安装托管集成包。它提供自动从TurnContext填充上下文信息的中间件，并包括对可观察性导出器的令牌缓存。

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

Configuration

请使用以下设置为您的代理启用并自定义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()的可选参数。

参数	Description	Default
`logger_name`	用于调试和控制台日志输出的Python记录器的名称。	`microsoft_agents_a365.observability.core`
`exporter_options`	一个 `Agent365ExporterOptions` 实例，用于配置令牌解析程序和群集类别。	`None`
`suppress_invoke_agent_input`	当`True`时，抑制`InvokeAgent`跨度上的输入消息。	`False`

下表描述了的 Agent365ExporterOptions可选属性。

财产	Description	Default
`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可选属性。

财产	Description	Default
`useS2SEndpoint`	当使用`true`时，调用服务到服务的终结点路径。	`false`
`maxQueueSize`	批处理处理器的最大队列大小。	`2048`
`scheduledDelayMilliseconds`	导出批处理之间的延迟（以毫秒为单位）。	`5000`
`exporterTimeoutMilliseconds`	整个导出操作的超时（以毫秒为单位）。	`90000`
`httpRequestTimeoutMilliseconds`	对后端的每个 HTTP 请求的超时（以毫秒为单位）。	`30000`
`maxExportBatchSize`	导出操作的最大批大小。	`512`

你也可以提供一个自定义日志器来实现该ILogger接口（info， warn， errorevent，）。通过使用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();

在EnableAgent365Exporter中设置true到appsettings.json。

在 Program.cs 中，将 Agent365ExporterOptions 添加到服务集合。此更改配置跟踪导出程序用于检索令牌的委托。

通过使用 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可选属性。

财产	Description	Default
`UseS2SEndpoint`	当使用`true`时，调用服务到服务的终结点路径。	`false`
`MaxQueueSize`	批处理处理器的最大队列大小。	`2048`
`ScheduledDelayMilliseconds`	导出批处理之间的延迟（以毫秒为单位）。	`5000`
`ExporterTimeoutMilliseconds`	导出操作的超时（以毫秒为单位）。	`30000`
`MaxExportBatchSize`	导出操作的最大批大小。	`512`

行李属性

使用 BaggageBuilder 设置在请求中贯穿所有范围的上下文信息。 SDK实现了一个 SpanProcessor ，将所有非空行李条目复制到新开始的跨度，且不覆盖现有属性。

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

要从BaggageBuilder自动填充TurnContext，请使用populate包中的microsoft-agents-a365-observability-hosting助手。此帮助程序会自动从活动中提取调用方、代理、租户、通道和聊天详细信息。

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

要从BaggageBuilder自动填充TurnContext，请使用fromTurnContext包中的@microsoft/agents-a365-observability-hosting助手。此帮助程序会自动从活动中提取调用方、代理、租户、通道和聊天详细信息。

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.

若要从 BaggageBuilder 自动填充 ITurnContext，请使用 FromTurnContext 包中的 Microsoft.Agents.A365.Observability.Hosting 扩展方法。此方法会自动从活动中提取调用方、代理、租户、通道和聊天详细信息。

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

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

行李中间件

如果代理使用托管集成包，请注册行李中间件，以便为每个传入请求自动填充行李。此步骤无需在每个活动处理程序中手动调用 BaggageBuilder 。

在适配器中间件集上注册 BaggageMiddleware 。它会自动从每个传入的 TurnContext 消息中提取调用方、代理、租户、通道和会话详细信息，并将请求包装在上下文范围内。

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

或者，您可以使用 ObservabilityHostingManager 配置行李中间件以及其他托管功能：

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

中间件会跳过异步响应（ContinueConversation 事件）的上下文信息设置，以避免覆盖原始请求已经设置的上下文信息。

在适配器上注册 BaggageMiddleware 。它会自动从每个传入的 TurnContext 消息中提取调用方、代理、租户、通道和会话详细信息，并将请求包装在上下文范围内。

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

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

或者，您可以使用 ObservabilityHostingManager 配置行李中间件以及其他托管功能：

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

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

中间件会跳过异步响应（ContinueConversation 事件）的上下文信息设置，以避免覆盖原始请求已经设置的上下文信息。

在适配器上注册 BaggageTurnMiddleware 。它会自动从每个传入的 ITurnContext 消息中提取调用方、代理、租户、通道和会话详细信息，并将请求包装在上下文范围内。

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

adapter.Use(new BaggageTurnMiddleware());

中间件会跳过异步响应（ContinueConversation 事件）的上下文信息设置，以避免覆盖原始请求已经设置的上下文信息。

如果需要 HTTP 级上下文信息（例如，在 Bot Framework 管道运行之前设置租户和代理 ID），请使用 ObservabilityBaggageMiddleware 扩展方法在 ASP.NET Core 管道中注册 UseObservabilityRequestContext。必须提供一个解析程序函数，用于从 HTTP 上下文中提取租户 ID 和代理 ID。

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

令牌解析器

使用代理 365 导出程序时，必须提供返回身份验证令牌的令牌解析程序函数。将 Agent 365 可观测性 SDK 与代理托管框架配合使用时，可以使用代理活动生成令牌 TurnContext 。

以下代码片段演示如何使用 microsoft_agents.hosting.core SDK 生成令牌。此处生成的身份验证令牌用于将范围导出到 A365 引入服务。代理可以自行生成令牌，例如，使用 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

对于使用 AI 团队成员和 Microsoft Agent 365 Observability 托管库包生成的 A365 CLI 代理，使用AgenticTokenCache自动处理令牌缓存。在活动处理程序中为每个代理和租户注册一次令牌，并在可观测性配置中传递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 生成令牌。此处生成的身份验证令牌用于将范围导出到 A365 引入服务。代理可以自行生成令牌，例如，使用 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
  }
);

对于使用 AI 团队成员和 @microsoft/agents-a365-observability-hosting 包，通过 A365 CLI 构建的代理，使用 AgenticTokenCacheInstance 来自动处理令牌缓存。在活动处理程序中，针对每个代理和租户调用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 生成令牌。使用生成的身份验证令牌将数据段导出到 A365 数据摄入服务。代理可以自行生成令牌，例如，使用 Microsoft身份验证库（MSAL），但需要确保令牌具有可观测性范围。

通过向委托注册Agent365ExporterOptionsTokenResolver来提供令牌解析程序。委托接收 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);
            }
        };
    });

对于使用 AI 团队成员和 Microsoft.Agents.A365.Observability.Hosting NuGet 包的 A365 CLI 生成的代理，请使用 AddAgenticTracingExporter() 方法通过依赖项注入实现令牌缓存的自动处理。

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

在代理应用程序中，注册令牌。

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）现有的跟踪遥测信号，并将其转发到代理 365 可观测性服务。此功能消除了开发者手动编写监控代码的需求，简化了设置，并确保了性能跟踪的一致性。

多个SDK和平台支持自动仪器化：

平台	支持的 SDK/框架
.NET	语义内核、OpenAI、Agent Framework
Python	语义内核、OpenAI、Agent Framework、LangChain
Node.js	OpenAI，LangChain

注释

对自动检测的支持因平台和 SDK 实现而异。

语义内核

自动检测需要使用行李生成器。设置代理 ID 和租户 ID，使用 BaggageBuilder。

安装此包。

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

通过使用 AgentId 设置 TenantId 和 BaggageBuilder。确保您在创建ChatCompletionAgent时使用的ID与传递给BaggageBuilder的代理ID相匹配。

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

自动检测需要使用行李生成器。设置代理 ID 和租户 ID，使用 BaggageBuilder。

安装此包。

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

通过使用 AgentId 设置 TenantId 和 BaggageBuilder。对于工具的调用，可以在Trace()实例上使用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>);
    }
}

代理框架

自动检测需要使用行李生成器。设置代理 ID 和租户 ID，使用 BaggageBuilder。

安装此包。

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

通过使用 AgentId 设置 TenantId 和 BaggageBuilder。

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

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

LangChain 框架

自动检测需要使用行李生成器。设置代理 ID 和租户 ID，使用 BaggageBuilder。

安装此包。

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来了解代理的内部工作原理。 SDK 提供可以启动的范围： InvokeAgentScope、 ExecuteToolScope、 InferenceScope和 OutputScope。

代理调用

在开始代理程序时使用此范围。通过调用代理范围，你可以捕获当前代理、代理用户数据等属性。

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

如果代理使用 @microsoft/agents-a365-observability-hosting 包，则可以使用 ScopeUtils.populateInvokeAgentScopeFromTurnContext 创建范围，其中代理详细信息、调用方详细信息和通道信息会自动从 TurnContext 中派生。

import { InvokeAgentScopeDetails, AgentDetails, ServiceEndpoint } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const agentDetails: AgentDetails = { agentId: 'agent-456' };
const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

const scope = ScopeUtils.populateInvokeAgentScopeFromTurnContext(
  agentDetails,
  scopeDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    // Agent details, caller details, and channel are auto-populated from context
    const response = await invokeAgent(context.activity.text);
    scope.recordOutputMessages([response]);
  });
} finally {
  scope.dispose();
}

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

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

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

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

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

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

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

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

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

        return new AgentResponse { Content = output };
    }
}

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

工具执行

以下示例展示了如何在代理工具执行中添加可观测性跟踪。该跟踪记录可采集遥测数据，用于监控和审计。

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

如果代理使用 @microsoft/agents-a365-observability-hosting 包，请使用 ScopeUtils.populateExecuteToolScopeFromTurnContext 来创建作用域，从 TurnContext 自动派生代理详细信息。

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

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

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

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

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

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

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

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

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

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

推断

以下示例演示如何使用可观测性跟踪检测 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();
}

如果代理使用@microsoft/agents-a365-observability-hosting包，则可以使用ScopeUtils.populateInferenceScopeFromTurnContext创建作用域，其中代理详细信息会自动从TurnContext派生。

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

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

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

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

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

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

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

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

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

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

输出

将此范围用于异步方案，在这种情况下 InvokeAgentScope， ExecuteToolScope或者 InferenceScope 无法同步捕获输出数据。开始 OutputScope 作为子跨度，以便在父范围完成后记录最终输出消息。

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 集成，请检查代理生成的控制台日志和可观测性 SDK 中的日志。

将 ENABLE_A365_OBSERVABILITY_EXPORTER 环境变量设置为 false。这个设置会导出跨度（traces）到控制台。

若要调查导出失败，请在应用程序启动时通过设置ENABLE_A365_OBSERVABILITY_EXPORTERtrue和配置调试日志记录来启用详细日志记录：

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。这个设置会导出跨度（traces）到控制台。

若要调查导出失败，请在 .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 });
  }
});

在EnableAgent365Exporter中设置false到appsettings.json。这个设置会导出跨度（traces）到控制台。

若要调查导出失败，请在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中的代理遥测数据，请确保满足以下要求：

Microsoft Purview：必须为组织开启审核。有关说明，请参阅打开或关闭审核。
Microsoft Defender：必须将高级搜寻配置为访问 CloudAppEvents 表。有关详细信息，请参阅高级搜寻架构中的 CloudAppEvents 表。

验证以备商店发布

重要

若要成功进行存储验证，代理必须实现InvokeAgentScope和InferenceScopeExecuteToolScope作用域。发布需要具有这三个范围。

发布之前，请使用控制台日志通过实现所需的invoke agent、execute toolinference范围和output范围来验证代理的可观测性集成。然后将你的客服日志与以下属性列表进行比较，以确认所有必需属性都存在。可以在每个范围或通过行李生成器中捕捉属性，并根据需要添加可选属性。

有关商店发布要求的更多信息，请参见商店验证指南。

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

使用可观测性测试代理

在代理中实现可观测性后，对其进行测试以确保它正确捕获遥测数据。按照测试指南搭建环境。然后，主要关注 “查看可观测性日志 ”部分，以验证可观测性实现是否按预期工作。

验证：

转到：https://admin.cloud.microsoft/#/agents/all
选择您的代理人 > 活动
你会看到会话记录和工具调用

故障排除

本节描述实现和使用可观察性时常见的问题。

提示

Agent 365 故障排除指南包含高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。

可观测性数据不出现

症状：

代理程序正在运行
管理中心没有遥测
看不到代理活动

根本原因：

未启用可观测性
配置错误
令牌解析器问题

解决方案： 请尝试以下步骤来解决问题：

验证是否启用了可观测性导出程序

必须显式启用 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"
```
验证遥测导出

确认遥测数据按预期生成并导出。
- 添加控制台导出程序并检查遥测是否在本地生成。有关如何使用控制台导出程序并验证输出的详细信息，请参阅本地验证。

缺少租户 ID 或代理 ID — 范围被跳过

症状： 系统以无提示方式删除范围，从不导出它们。某些 SDK 会记录跳过的跨度计数或类似“找不到租户/代理标识的跨度”的消息。其他则会在不记录的情况下删除它们。

解决方法：

在导出之前，SDK 会根据租户和代理标识来分隔跨度。系统会删除缺少租户 ID 或代理 ID 的跨度，且绝不会将其发送到服务。
在创建范围之前，请确保 BaggageBuilder 使用租户 ID 和代理 ID 进行设置。这些值通过 OpenTelemetry 上下文传播，并附加到在挂件范围内创建的所有跨度。有关特定于平台的 API，请参阅 Baggage 属性。
在使用行李中间件或从托管集成包的轮次上下文帮助程序来填充这些 ID 时，请确认TurnContext活动具有有效的代理身份收件人。

令牌解析失败——导出已跳过或未经授权

症状： 令牌解析程序返回 null 或引发错误。根据 SDK，导出过程可能会被完全跳过，或者在请求没有授权标头的情况下发送，从而导致 HTTP 401 错误。

解决方法：

初始化时需要令牌解析程序。如果缺少，导出程序会在启动时引发错误。验证是否提供了令牌解析程序并返回有效的持有者令牌。
请确保使用 BaggageBuilder正确的租户 ID 和代理 ID，因为这些值将传递给令牌解析程序。
对于托管在 Azure 上的代理，请验证托管身份是否具有可观测性范围所需的 API 权限。

HTTP 401 未授权

症状： 导出失败并出现 HTTP 401。导出程序不会重试此错误。

解决方法：

验证令牌访问群体是否与可观测性终结点范围匹配。
检查令牌解析程序是否未返回委派的用户令牌、目标受众不正确的令牌或过期的令牌。

HTTP 403 禁止访问

症状： 导出失败并出现 HTTP 403。导出程序不会重试此错误。

根源： HTTP 403 错误可能有不同的原因。按顺序检查以下解决方法。

解决方法：

许可证丢失 — 验证租户是否在 Microsoft 365 管理中心中分配了以下许可证之一：
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
缺少 Agent365.Observability.OtelWrite 权限 - 如果最近升级了可观测性包，则需要授予此权限。请参阅下面的重要说明。

重要

升级到这些包版本的现有代理需要额外的步骤

仅当正在升级现有代理时，此步骤才适用。新代理安装不需要此步骤。如果要升级到下列包版本或更新的版本，则必须为您的身份（托管身份或应用注册）授予新的 Agent365.Observability.OtelWrite 权限。如果没有此权限，遥测导出会失败并出现 HTTP 403。

平台	需要此步骤的最低版本
.NET	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

使用以下选项之一授予权限。

Option A — Agent 365 CLI（需要配置目录中的 a365.config.json 和 a365.generated.config.json、全局管理员帐户以及 Agent 365 CLI v1.1.139-preview 或更高版本）

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

此命令授予所有缺失的权限，包括新的可观测性范围。

选项 B — Entra Portal （不需要配置文件;需要全局管理员访问蓝图应用注册）

转到 Entra 门户>应用注册>，选择蓝图应用程序。
转到 API 权限>添加权限>我的组织使用的 API> 搜索 9b975845-388f-4429-889e-eab1ef63949c。
选择 “委派权限> ”检查 Agent365.Observability.OtelWrite>“添加权限”。
重复步骤 2–3，这次选择 “应用程序权限> ”检查 Agent365.Observability.OtelWrite>“添加权限”。
单击“ 授予管理员同意 ”并确认。

Agent365.Observability.OtelWrite（委派）和Agent365.Observability.OtelWrite（应用）应显示Granted状态。

HTTP 429 / 5xx — 暂时性错误

症状： 导出失败，出现暂时性 HTTP 状态代码，例如 429 或 5xx。

解决方法：

这些错误通常是暂时性的，可以自行解决。 Python和 JavaScript SDK 会自动在 HTTP 408、429 和 5xx 错误状态代码重试，最多三次，使用指数退避。 .NET SDK 不会自动重试。
如果错误仍然存在，请检查服务运行状况仪表板。
请考虑通过增加批之间的计划延迟或增加最大导出批大小来降低导出频率。有关每个平台的配置选项，请参阅Agent365ExporterOptions“配置”中的表。

导出超时

症状： 导出尝试超时。

解决方法：

检查与可观测性终结点的网络连接。
超时默认值因平台而异。默认 HTTP 请求超时为 30 秒。某些 SDK 还有一个单独的整体导出操作超时设置，涵盖整个导出过程，包括重试。有关每个平台的确切属性和默认值，请参阅Agent365ExporterOptions“配置”中的表。
如果超时频繁发生，请在导出程序选项中增加相关的超时值。

导出成功，但遥测不会显示在 Defender 或 Purview 中

Symptoms： 日志显示成功导出，但遥测在Microsoft Defender或Microsoft Purview中不可见。

解决方法：

验证是否满足查看导出日志的先决条件。对于 Purview，必须启用审核。对于Defender，必须配置高级搜寻。有关详细信息，请参阅查看导出的日志。
成功导出后，遥测数据可能需要几分钟才能显示。等待数据出现，然后进一步调查。

若要了解有关测试可观测性的详细信息，请参阅：

反馈

此页面是否有帮助？

Last updated on 2026-05-01

代理可观测性

主要优点

支持的代理

安装

Configuration

行李属性

行李中间件

令牌解析器

自动检测

语义内核

OpenAI

代理框架

LangChain 框架

手动检测

代理调用

工具执行

推断

输出

本地验证

查看导出的日志

验证以备商店发布

InvokeAgentScope 属性

ExecuteToolScope 属性

InferenceScope 属性

OutputScope 属性

使用可观测性测试代理

故障排除

可观测性数据不出现

缺少租户 ID 或代理 ID — 范围被跳过

令牌解析失败——导出已跳过或未经授权

HTTP 401 未授权

HTTP 403 禁止访问

HTTP 429 / 5xx — 暂时性错误

导出超时

导出成功，但遥测不会显示在 Defender 或 Purview 中

反馈

其他资源

`InvokeAgentScope` 属性

`ExecuteToolScope` 属性

`InferenceScope` 属性

`OutputScope` 属性