代理可观测性

重要

需要成为 Frontier 预览计划的一部分才能提前访问 Microsoft Agent 365。边界将你直接与Microsoft最新的 AI 创新联系起来。 Frontier 预览版受客户协议中现有预览条款的约束。由于这些功能仍在开发中，其可用性和功能可能会随时间而变化。

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

关键优势

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

安装

使用这些命令为代理 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

配置

请使用以下设置为您的代理启用并自定义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`跨度上的输入消息。	`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， 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可选属性。

财产	描述	默认
`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

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

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助手。此帮助程序会自动从活动中提取调用方、代理、租户、通道和聊天详细信息。

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

令牌解析器

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

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

对于数字化工作者场景，如果您的代理使用 Microsoft Agent 365 Observability Hosting Library 包，请使用 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(),
    )

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

对于数字工作者场景，如果你的代理使用 @microsoft/agents-a365-observability-hosting 包，则使用 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()
    );
  }
);

通过向委托注册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);
            }
        };
    });

对于数字辅助角色方案，如果代理使用 Microsoft.Agents.A365.Observability.Hosting NuGet 包，请使用 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) 现有的跟踪遥测信号，并将其转发到 Agent 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，请查看代理生成的控制台日志。

将 ENABLE_A365_OBSERVABILITY_EXPORTER 环境变量设置为 false。此设置将范围（跟踪）导出到控制台。

若要调查导出失败，请在应用程序启动时通过设置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。此设置将范围（跟踪）导出到控制台。

若要调查导出失败，请在 .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。此设置将范围（跟踪）导出到控制台。

若要调查导出失败，请在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 表。

可观测性要求

IT管理员利用你代码中设置的数据来监控代理的活动。数据不完整意味着你无法充分发挥可观察性的好处。代理人必须提供所需数据以获得所有预期福利。验证过程用于验证这些数据的存在。

在遥测中，存在范围或上下文的概念。每个操作由你的代理执行时，都会存在于不同的范围内。您必须将数据包含在使用 BaggageScope创建的范围内，或者如手动检测中所述的单独范围内。

要验证你的实现，请按照本地验证说明生成你的仪器的控制台日志。然后查看“ 商店发布验证 ”部分，识别哪些属性是必需的，哪些是可选的。您必须设置所有必要的属性才能成功通过验证。

请审查这些类所需的属性和参数值：

你用 BaggageBuilder 类设置的属性可能会被相应作用域的属性设置或覆盖。

通过使用 InvokeAgentScope.start 方法设置下表中的属性。

Data	描述
`invoke_agent_details.details.agent_id`	AI 代理的唯一标识符
`invoke_agent_details.details.agent_name`	人工智能代理的人类可读名称
`invoke_agent_details.details.agent_auid`	代理用户 ID （AUID）
`invoke_agent_details.details.agent_upn`	代理用户主体名称（UPN）
`invoke_agent_details.details.agent_blueprint_id`	智能体蓝图/应用程序 ID
`invoke_agent_details.details.tenant_id`	代理的租户 ID
`invoke_agent_details.details.conversation_id`	会话或对话的标识符
`invoke_agent_details.endpoint`	代理调用的终结点
`tenant_details.tenant_id`	租户的唯一标识符
`request.content`	发送给代理调用的有效载荷内容
`request.execution_type`	调用类型表示请求起源（例如， `HumanToAgent` 或 `AgentToAgent`）
`caller_details.caller_id`	调用方的唯一标识符
`caller_details.caller_upn`	调用方的用户主体名称（UPN）
`caller_details.caller_user_id`	调用方的用户 ID
`caller_details.tenant_id`	调用方租户 ID

通过使用 ExecuteToolScope.start 方法设置下表中的属性。

Data	描述
`details.tool_name`	正在执行的工具的名称
`details.arguments`	工具参数或参数说明
`details.tool_call_id`	工具调用的唯一标识符
`details.tool_type`	正在执行的工具的类型
`details.endpoint`	如果进行外部工具调用
`agent_details.agent_id`	AI 代理的唯一标识符
`agent_details.agent_name`	人工智能代理的人类可读名称
`agent_details.agent_auid`	代理用户ID
`agent_details.agent_upn`	代理用户主体名称（UPN）
`agent_details.agent_blueprint_id`	代理蓝图或应用ID
`agent_details.tenant_id`	中介的租户身份证。
`agent_details.conversation_id`	智能体调用的对话 ID。
`tenant_details.tenant_id`	中介的租户身份证。

通过使用 InferenceScope.start 方法设置下表中的属性。

Data	描述
`details.operationName`	推理的操作名称或类型
`details.model`	型号名称或标识符
`details.providerName`	提供者名称
`agent_details.agent_id`	AI 代理的唯一标识符
`agent_details.agent_name`	人工智能代理的人类可读名称
`agent_details.agent_auid`	代理用户 ID （AUID）
`agent_details.agent_upn`	代理用户主体名称（UPN）
`agent_details.agent_blueprint_id`	代理蓝图或应用ID
`agent_details.tenant_id`	租户的唯一标识符
`agent_details.conversation_id`	会话或对话的标识符
`tenant_details.tenant_id`	租户的唯一标识符
`request.content`	发送到智能体进行推理的有效负载内容
`request.execution_type`	调用类型表示请求起源（例如， `HumanToAgent` 或 `AgentToAgent`）
`request.source_metadata`	表示信道信息

你用 BaggageBuilder 类设置的属性可能会被相应作用域的属性设置或覆盖。

通过使用 InvokeAgentScope.start 方法设置下表中的属性。

Data	描述
`agentDetails.agentId`	AI 代理的唯一标识符
`agentDetails.agentName`	人工智能代理的人类可读名称
`agentDetails.agentAuid`	代理用户 ID （AUID）
`agentDetails.agentEmail`	代理电子邮件地址
`agentDetails.agentBlueprintId`	智能体蓝图/应用程序 ID
`agentDetails.tenantId`	代理的租户 ID
`scopeDetails.endpoint.host`	代理调用端点的主机地址
`scopeDetails.endpoint.port`	代理调用端点的端口号
`request.content`	代理调用请求有效载荷的内容
`request.conversationId`	会话或对话的标识符
`request.sessionId`	代理调用的会话 ID
`request.channel.name`	频道信息如（`msteams`、 `email`，等等）
`callerDetails.userDetails.userId`	调用方的唯一标识符
`callerDetails.userDetails.userName`	调用方的显示名称
`callerDetails.userDetails.userEmail`	呼叫者的电子邮件地址

通过使用 ExecuteToolScope.start 方法设置下表中的属性。

Data	描述
`details.toolName`	正在执行的工具的名称
`details.arguments`	工具参数或参数说明
`details.toolCallId`	工具调用的唯一标识符
`details.toolType`	正在执行的工具的类型
`details.endpoint.host`	工具执行端点的主机地址。如果进行外部呼叫，则是必需的
`details.endpoint.port`	工具执行端点的端口号。如果进行外部呼叫，则是必需的
`agentDetails.agentId`	AI 代理的唯一标识符
`agentDetails.agentName`	人工智能代理的人类可读名称
`agentDetails.tenantId`	代理的租户 ID
`request.conversationId`	会话或对话的标识符

通过使用 InferenceScope.start 方法设置下表中的属性。

Data	描述
`details.operationName`	推理的操作名称或类型
`details.model`	型号名称或标识符
`details.providerName`	提供者名称
`agentDetails.agentId`	AI 代理的唯一标识符
`agentDetails.agentName`	人工智能代理的人类可读名称
`agentDetails.tenantId`	代理的租户 ID
`request.conversationId`	会话或对话的标识符

你用 BaggageBuilder 类设置的属性可能会被相应作用域的属性设置或覆盖。

通过使用 InvokeAgentScope.Start 方法设置下表中的属性。

Data	描述
`invokeAgentDetails.details.agentId`	代理的唯一标识符。
`invokeAgentDetails.details.agentName`	代理人的显示名称。
`invokeAgentDetails.details.agentAUID`	Azure代理的用户 ID（AUID）。
`invokeAgentDetails.details.agentUPN`	代理程序的用户主体名称（UPN）。
`invokeAgentDetails.details.agentBlueprintId`	智能体的蓝图/应用程序 ID。
`invokeAgentDetails.details.tenantId`	中介的租户身份证。
`invokeAgentDetails.endpoint`	用于调用代理的端点URI。
`tenantDetails.tenantId`	租户的标识。
`request.content`	提供给代理的有效载荷内容。
`request.executionType`	描述请求的执行类型。
`request.sourceMetadata.name`	来源的易读名称。渠道名称。
`conversationId`	智能体调用的对话 ID。

通过使用 ExecuteToolScope.Start 方法设置下表中的属性。

Data	描述
`details.toolName`	被调用的工具名称。
`details.arguments`	串行化的参数传递给工具。
`details.toolCallId`	工具调用的标识符。
`details.toolType`	工具的类型分类。
`details.endpoint`	远程工具执行所需的端点。
`agentDetails.agentId`	代理的唯一标识符。
`agentDetails.agentName`	代理人的显示名称。
`agentDetails.agentAUID`	Azure代理的用户 ID（AUID）。
`agentDetails.agentUPN`	代理程序的用户主体名称（UPN）。
`agentDetails.agentBlueprintId`	智能体的蓝图/应用程序 ID。
`agentDetails.tenantId`	中介的租户身份证。
`tenantDetails.tenantId`	租户的标识。

通过使用 InferenceScope.Start 方法设置下表中的属性。

Data	描述
`details.operationName`	用于推理作业的遥测标识符。
`details.model`	模型名称用于满足推理请求。
`details.providerName`	负责推断通话的服务提供者。
`agentDetails.agentId`	代理的唯一标识符。
`agentDetails.agentName`	代理人的显示名称。
`agentDetails.agentAUID`	Azure代理的用户 ID（AUID）。
`agentDetails.agentUPN`	代理程序的用户主体名称（UPN）。
`agentDetails.agentBlueprintId`	智能体的蓝图/应用程序 ID。
`agentDetails.tenantId`	中介的租户身份证。
`tenantDetails.tenantId`	租户的标识。
`parentId`	对于显式管理父范围。大多数情况下不是必须的。

针对商店发布进行验证

发布之前，请使用控制台日志通过实现所需的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
选择您的代理人 > 活动
你会看到会话记录和工具调用

Troubleshooting

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

小窍门

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

可观测性数据不出现

症状：

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

根本原因：

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

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

验证可观测性已被启用

在你的环境中启用可观察性标志。
```
# .env file
ENABLE_A365_OBSERVABILITY_EXPORTER=true
```
检查令牌解析器配置

确保你的代码正确实现了令牌解析器。直接查看SDK中最新的代码。

检查日志中的错误

使用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"

验证遥测导出

确认遥测数据按预期生成并导出。
- 添加控制台导出器进行测试
- 检查遥测数据是否在本地生成

了解更多关于可观察性测试的信息：

反馈

此页面是否有帮助？

Last updated on 2026-04-15

通过

代理可观测性

关键优势

安装

配置

行李属性

令牌解析器

自动检测

语义内核

OpenAI

代理框架

LangChain 框架

手动检测

代理调用

工具执行

推断

输出

本地验证

查看导出日志的先决条件

可观测性要求

针对商店发布进行验证

InvokeAgentScope 属性

ExecuteToolScope 属性

InferenceScope 属性

OutputScope 属性

使用可观测性测试智能体

Troubleshooting

可观测性数据不出现

反馈

其他资源

`InvokeAgentScope` 属性

`ExecuteToolScope` 属性

`InferenceScope` 属性

`OutputScope` 属性