Microsoft OpenTelemetry 发行版

Prerequisites： Python 3.10 或更高版本。

pip install microsoft-opentelemetry

先决条件： Node.js 18 或更高版本。 ESM 应用需要 Node.js 20.6.0 或更高版本。

npm install @microsoft/opentelemetry

node --import @microsoft/opentelemetry/loader ./dist/index.js

安装 Microsoft.OpenTelemetry NuGet 包。 此单个包包括 Agent 365 可观测性运行时、托管集成、针对支持的 AI 框架的自动检测以及标准 OpenTelemetry 库。

<PackageReference Include="Microsoft.OpenTelemetry" />

或使用 .NET CLI：

dotnet add package Microsoft.OpenTelemetry

调用 use_microsoft_opentelemetry() 以启用可观测性。

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache

token_cache = AgenticTokenCache()

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=lambda agent_id, tenant_id: (
        (t := asyncio.run(token_cache.get_observability_token(agent_id, tenant_id)))
        and t.token or None
    ),
)

有关自定义令牌解析（而不是默认 令牌解析程序），请参阅手动令牌解析程序。

可以通过将可选 a365_* kwargs 传递给 use_microsoft_opentelemetry() 自定义导出程序行为。

使用ObservabilityManager和AgenticTokenCacheInstance一起自动处理令牌缓存。

import { useMicrosoftOpenTelemetry, AgenticTokenCacheInstance } from '@microsoft/opentelemetry';
import { resourceFromAttributes } from '@opentelemetry/resources';

useMicrosoftOpenTelemetry({
  resource: resourceFromAttributes({
    'service.name': 'Default Token Cache Sample',
    'service.version': '1.0.0',
  }),
  azureMonitor: {
    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
  },
  instrumentationOptions: {
    http: { enabled: false },
  },
  a365: {
    enabled: process.env.ENABLE_A365_OBSERVABILITY_EXPORTER !== 'false',
    tokenResolver: (agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId) ?? '',
  },
});

有关自定义令牌解析（而不是默认 令牌解析程序），请参阅手动令牌解析程序。

可以通过在a365对象上设置可选属性来自定义导出器行为。

有关完整配置选项和环境变量，请参阅 JavaScript 存储库自述文件。

在 Program.cs 中调用 UseMicrosoftOpenTelemetry() 以启用可观测性。 ExportTarget 标志枚举控制遥测的发送位置 - 将目标与 | 组合（例如，ExportTarget.Console | ExportTarget.Agent365）。

自动（DI）令牌缓存 （建议用于 Agent Framework 应用）：

如果未设置 TokenResolver，发行版会自动通过 DI 注册 IExporterTokenCache<AgenticTokenStruct> 。 代理在运行时调用 RegisterObservability() 以提供凭据，缓存处理令牌获取和刷新。

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // TokenResolver is auto-registered via the agentic token cache in DI, with required imports in the next code snippet.
});

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

// In your agent class
public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

有关自定义令牌解析（而不是默认 令牌解析程序），请参阅手动令牌解析程序。

通过在o.Agent365.Exporter上设置可选属性，可以自定义导出器行为。

from microsoft.opentelemetry.a365.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-opentelemetry 包中使用 populate 辅助程序。 此帮助程序会自动从活动中提取调用方、代理、租户、通道和聊天详细信息。

from microsoft.opentelemetry.a365.core import BaggageBuilder
from microsoft.opentelemetry.a365.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, InvokeAgentScope, ExecuteToolScope } from '@microsoft/opentelemetry';

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

import { BaggageBuilder, BaggageBuilderUtils } from '@microsoft/opentelemetry';

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

baggageScope.run(() => {
  // 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();

在 Python 中，通过 ObservabilityHostingManager.configure() 而不是直接在适配器上注册行李中间件。

from microsoft.opentelemetry.a365.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

中间件会跳过异步回复（ContinueConversation 事件）的行李配置，以避免覆盖源请求已设置的行李。

在适配器上注册 BaggageMiddleware 。 它会从每个传入的 TurnContext 中自动提取呼叫方、智能体、租户、通道和对话详细信息，并将请求整合在行李作用域中。

import { BaggageMiddleware } from '@microsoft/opentelemetry';

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

或者，使用 ObservabilityHostingManager 配置负载中间件以及其他托管功能。

import { ObservabilityHostingManager } from '@microsoft/opentelemetry';

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），请使用 UseObservabilityRequestContext 扩展方法在 ASP.NET Core 管道中注册 ObservabilityBaggageMiddleware。 必须提供一个解析程序函数，用于从 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);
});

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

Node.js 不支持 语义内核 自动检测。

默认情况下，语义内核 仪器化已启用。 为禁用它，请明确设置工具选项。

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableSemanticKernelInstrumentation = false;
});

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    openaiAgents: { enabled: true },
  },
});

OpenAI 和 Azure OpenAI 检测默认处于启用状态。 为禁用它，请明确设置工具选项。

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableOpenAIInstrumentation = false;
});

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

Node.js不支持代理框架自动检测。

默认情况下，代理框架检测处于启用状态。 为禁用它，请明确设置工具选项。

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableAgentFrameworkInstrumentation = false;
});

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    langchain: { enabled: true },
  },
});

不会为 .NET 列出 LangChain 自动检测。

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="[email protected]",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

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

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

import { InvokeAgentScope } from "@microsoft/opentelemetry";
import type {
  AgentDetails,
  A365Request,
  InvokeAgentScopeDetails,
} from "@microsoft/opentelemetry";

const agentDetails: AgentDetails = {
  agentId: "agent-456",
  agentName: "Email Assistant",
  agentDescription: "An AI agent powered by Azure OpenAI",
  agentAUID: "auid-123",
  agentEmail: "[email protected]",
  agentBlueprintId: "blueprint-789",
  tenantId: "tenant-123",
};

const request: A365Request = {
  content: "Please help me organize my emails",
  sessionId: "session-42",
  conversationId: "conv-xyz",
  channel: { name: "msteams" },
};

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

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

try {
  await invokeScope.withActiveSpanAsync(async () => {
    invokeScope.recordInputMessages(["Please help me organize my emails"]);

    // Run the agent invocation.

    invokeScope.recordOutputMessages(["I found 15 urgent emails."]);
  });
} catch (error) {
  invokeScope.recordError(error as Error);
  throw error;
} finally {
  invokeScope.dispose();
}

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

var agentDetails = new AgentDetails(
    agentId: "agent-456",
    agentName: "Email Assistant",
    agentDescription: "An AI agent powered by Azure OpenAI",
    agenticUserId: "auid-123",
    agenticUserEmail: "[email protected]",
    agentBlueprintId: "blueprint-789",
    tenantId: "tenant-123");

var request = new Request(
    content: "Please help me organize my emails",
    sessionId: "session-42",
    conversationId: "conv-xyz",
    channel: new Channel(name: "msteams"));

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

using var invokeScope = InvokeAgentScope.Start(
    request: request,
    scopeDetails: scopeDetails,
    agentDetails: agentDetails);

invokeScope.RecordInputMessages(new[] { "Please help me organize my emails" });

// Run the agent invocation.

invokeScope.RecordOutputMessages(new[] { "I found 15 urgent emails." });

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:[email protected]"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

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

import { ExecuteToolScope } from "@microsoft/opentelemetry";
import type { ToolCallDetails } from "@microsoft/opentelemetry";

const toolDetails: ToolCallDetails = {
  toolName: "email-search",
  arguments: JSON.stringify({ query: "from:[email protected]" }),
  toolCallId: "tool-call-456",
  description: "Search emails by criteria",
  toolType: "function",
  endpoint: {
    host: "tools.contoso.com",
    port: 8080,
    protocol: "https",
  },
};

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

try {
  await invokeScope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var toolDetails = new ToolCallDetails(
    toolName: "email-search",
    arguments: "{\"query\": \"from:[email protected]\"}",
    toolCallId: "tool-call-456",
    description: "Search emails by criteria",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080"));

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

// Execute the tool.

scope.RecordResponse("{\"count\": 15}");

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

import { InferenceOperationType, InferenceScope } from "@microsoft/opentelemetry";
import type { InferenceDetails } from "@microsoft/opentelemetry";

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

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

try {
  await invokeScope.withActiveSpanAsync(async () => {
    scope.recordInputMessages(["Summarize the following emails for me."]);
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
    scope.recordFinishReasons(["stop"]);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI");

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

scope.RecordInputMessages(new[] { "Summarize the following emails for me." });

// Call the model.

scope.RecordOutputMessages(new[] { "Here is your email summary." });
scope.RecordInputTokens(145);
scope.RecordOutputTokens(82);
scope.RecordFinishReasons(new[] { "stop" });

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

import { OutputScope } from "@microsoft/opentelemetry";
import type { A365SpanDetails, OutputResponse } from "@microsoft/opentelemetry";

// Capture this before disposing the originating InvokeAgentScope.
const parentContext = invokeScope.getSpanContext();
const response: OutputResponse = {
  messages: ["Here is your organized inbox."],
};

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

scope.dispose();

// Capture this before disposing the originating InvokeAgentScope.
var parentContext = invokeScope.GetActivityContext();
var response = new Response(new[] { "Here is your organized inbox." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext));

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

useMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Otlp;
    o.OtlpEndpoint = new Uri("http://localhost:4317");
});

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "local-validation-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
)

# Run instrumented application code.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

import {
  useMicrosoftOpenTelemetry,
  shutdownMicrosoftOpenTelemetry,
} from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "local-validation-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
});

// Run instrumented application code.

await shutdownMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Console;
});

解析程序必须是 同步的。 获取异步活动处理程序（或通过 MSAL）中的令牌，并将其缓存给解析程序。

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
import { TurnState, AgentApplication, TurnContext, MemoryStorage } from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId: string, tenantId: string, authScopes?: string[]) =>
      myTokenService.getToken(agentId, tenantId),
  },
});


export class A365Agent extends AgentApplication<TurnState> {
  isApplicationInstalled: boolean = true;
  termsAndConditionsAccepted: boolean = true;
  agentName = 'A365 Agent';
  authHandlerName = 'agentic';

  constructor() {
    const useAgenticAuth = process.env.USE_AGENTIC_AUTH === 'true';

    super({
      storage: new MemoryStorage(),
      ...(useAgenticAuth && {
        authorization: {
          agentic: {
            type: 'agentic',
          }
        }
      })
    });

    this.onActivity(ActivityTypes.Message, async (context: TurnContext, state: TurnState) => {
      await this.handleAgentMessageActivity(context, state);
    });
  }

  async handleAgentMessageActivity(turnContext: TurnContext, _state: TurnState): Promise<void> {
    if (process.env.USE_AGENTIC_AUTH !== 'true') {
      console.log('[A365Agent] Authorization not configured, skipping observability token preload');
      return;
    }

    const agentId = turnContext?.activity?.recipient?.agenticAppId ?? '';
    const tenantId = turnContext?.activity?.recipient?.tenantId ?? '';

    // Acquire auth token via OBO exchange
    const authToken = await this.authorization.exchangeToken(turnContext, 'agentic', {
      scopes: ['api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite']
    });

    // Cache the token so it can be returned by the token resolver
    myTokenService.set(agentId, tenantId, authToken?.token || '');
  }
}

using Microsoft.OpenTelemetry;

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
    {
        return await MyTokenService.GetTokenAsync(agentId, tenantId);
    };
});

当您明确设置 TokenResolver 时，不会注册自动 DI 令牌缓存 — 使用您的解析器。

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache, AgenticTokenStruct
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

token_cache = AgenticTokenCache()

_cached_tokens: dict[tuple[str, str], str | None] = {}

# Keep the sync resolver side-effect free; refresh the cache in the async request handler.
def sync_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_tokens.get((agent_id, tenant_id))

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=sync_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    agent_id = context.activity.recipient.id
    tenant_id = context.activity.recipient.tenant_id
    token_cache.register_observability(
        agent_id=agent_id,
        tenant_id=tenant_id,
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )
    _cached_tokens[(agent_id, tenant_id)] = await token_cache.get_observability_token(
        agent_id, tenant_id,
    )

使用 configureA365Hosting 在适配器上注册 A365 中间件。 此中间件会自动处理负载和令牌管道。

import { configureA365Hosting } from "@microsoft/opentelemetry";

configureA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: false,
});

如果不希望将响应内容捕获为跨度属性，则设置 enableOutputLogging: false 。

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // IExporterTokenCache<AgenticTokenStruct> is auto-registered via DI
});

在代理类中，每次轮次调用 RegisterObservability() ：

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

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}