Microsoft OpenTelemetry 發行版

Microsoft OpenTelemetry 發行版是一個統一的可檢視性發行版，為 Agent 型與非 Agent 型應用程式的追蹤、度量指標和記錄提供單一的上線體驗。 它支援 Microsoft Agent 365、Microsoft Foundry、Azure 監視器以及任何與 OpenTelemetry 通訊協定 (OTLP) 相容後端的可檢視性。 此發行版支援 .NET、Node.js 和 Python，並透過一次匯入及一次設定呼叫取代跨多個可檢視性堆疊的碎片化設定。

重點優勢

Microsoft OpenTelemetry 發行版提供以下優勢：

  • 一個套件，一個 API：以單一相依性取代多個匯出器和檢測套件。
  • 多後端支援：可同時將遙測資料送至 Azure 監視器、任何相容於 OpenTelemetry 通訊協定 (OTLP) 的端點 (如 Datadog、Grafana 或 New Relic)，以及 Microsoft Agent 365。
  • 內建的檢測：可對 HTTP、資料庫、Azure SDK、Azure Functions 等進行自動檢測，無需額外設定。
  • 基於標準：根據 OpenTelemetry 建置，這是產業標準的可檢視性框架。
  • 最小樣板：於應用程式入口點新增一次匯入和一次函式呼叫。

安裝和設定

本指南將指導您如何使用 Microsoft OpenTelemetry 發行版，將可檢視性新增到您的應用程式。 此發行版會自動透過內建檢測來收集追蹤、度量指標和記錄，並將遙測資料匯出至 Azure 監視器、任何 OpenTelemetry 通訊協定 (OTLP) 端點或 Microsoft Agent 365。

安裝程式庫

若要開始使用 Microsoft OpenTelemetry 發行版，請使用您的程式語言的套件管理器針對您的開發平台安裝適合的函式庫。

先修條件：Python 3.10 或更新版本。

pip install microsoft-opentelemetry

組態

Agent 365 匯出器不使用連接字串。 它會根據租用戶自動發現其端點。 若要啟用匯出到 Agent 365，請設定匯出器目標，並提供一個會傳回根據指定 Agent 識別碼和租用戶識別碼之存取權杖的權杖解析器。

呼叫 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() 來自訂匯出器行為。

參數 描述 預設
a365_use_s2s_endpoint True 時，請使用服務到服務端點路徑。 False
a365_max_queue_size 批次處理器的最大佇列大小。 2048
a365_scheduled_delay_ms 匯出批次之間的延遲 (以毫秒為單位)。 5000
a365_exporter_timeout_ms 匯出作業的逾時時間 (以毫秒為單位)。 30000
a365_max_export_batch_size 匯出作業的最大批次大小。 512

傳播上下文

為了維持分散式 Agent 365 作業間的可檢視性，請傳播上下文。 當你透過 Agent 和服務傳遞上下文時，便能確保追蹤記錄、記錄和度量指標於整個要求生命週期內得到正確的關聯。 這種關聯是完整且有效的 Microsoft Agent 365 監控體驗所必需的。

Baggage 屬性

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

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 協助工具。 此協助工具會自動從活動中擷取呼叫者、Agent、租用戶、管道和交談詳細資料。

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

Baggage 中介軟體

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

在 Python 中，Baggage 中介軟體是透過 ObservabilityHostingManager.configure() 註冊，而不是直接在配接器上註冊。

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

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

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

確認資料在產品中流動

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

自動檢測

Microsoft OpenTelemetry 發行版結合標準 OpenTelemetry 管線與 Microsoft 策劃的儀器。 發行版可以根據語言和組態，收集應用程式遙測資料、基礎結構遙測資料，以及 Agent 或生成式 AI 遙測資料。

類別 涵蓋範圍
訊號管線 追蹤、計量指標和紀錄。
資源偵測 服務、主機、雲端及 Azure 執行階段上下文 (視支援情況而定)
基礎結構檢測 HTTP、ASP.NET Core、Azure SDK、資料庫用戶端及記錄框架 (視支援情況而定)
生成式 AI 儀器 OpenAI、Azure OpenAI、語意核心、LangChain、OpenAI Agents SDK 及 Agent Framework (視支援情況而定)。
手動 Agent 範圍 Agent 叫用、工具執行、推理和輸出遙測資料 (視支援情況而定)。
匯出器與處理器 Azure 監視器、Microsoft Agent 365、OTLP、主控台輸出、跨度處理器、記錄處理器和計量讀取器。

檢測覆蓋範圍

語言 常見應用程式檢測 常見 Agent 與生成式 AI檢測
Python OpenTelemetry 資源、處理器、讀取器、記錄、指標與追蹤。 語意核心、OpenAI Agents SDK、Agent Framework、LangChain、Microsoft Agent 365 行李，以及 Microsoft Agent 365 範圍。
Node.js HTTP、Azure SDK、Azure Functions、MongoDB、MySQL、PostgreSQL、Redis、Bunyan 和 Winston。 OpenAI Agents SDK、LangChain、Microsoft Agent 365 行李，及 Microsoft Agent 365 範圍。
.NET ASP.NET Core、HttpClient、SQL Client、Azure SDK、資源偵測、指標和記錄。 語意核心、OpenAI 和 Azure OpenAI、Agent Framework、Microsoft Agent 365 行李，以及 Microsoft Agent 365 範圍。

自動檢測會監聽依支援的函式庫與框架發出的遙測訊號。 當應用程式需要描述 Agent 專屬做作業 (例如叫用、工具執行、推論或非同步輸出) 時，會使用手動檢測。

當內建檢測處理未涵蓋您的應用程式產生的遙測資料時，請新增自訂的 OpenTelemetry 來源、計量指標、處理器或讀取器。

重要

自動檢測只會填入標準的 OpenTelemetry 屬性。 它並不包含 Agent 365 所需的所有屬性。 您必須使用 BaggageBuilder 來新增 Microsoft 特定的屬性。 欲了解需要哪些屬性，請參閱儲存確認屬性。

內建檢測程式庫

自動檢測會監聽由支援的架構發出的遙測資料，並將其轉送到發行版本的 OpenTelemetry 管線。 對於 Agent 案例，在檢測架構建立跨度之前，先設定租用戶識別碼和 Agent 識別碼等行李。

架構 Python Node.js .NET
語意核心 已支援 不支援 已支援
OpenAI 與 OpenAI Agent SDK 已支援 支援 已支援
Agent Framework 已支援 不支援 已支援
LangChain 已支援 已支援 未列出

語意核心

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

OpenAI

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

Agent Framework

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

LangChain

注意

LangChain Framework 的自動檢測同時支援 LangGraph 和深度 Agent。 同一個檢測也能自動為使用這些框架建置的 Agent 擷取遙測資料。

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

手動檢測

當自動檢測無法提供足夠詳細資料來描述 Agent 作業時，請使用手動檢測。 手動作用範圍讓應用程式能以一致的方式跨語言描述常見的 Agent 活動。

範圍 適用時機
InvokeAgentScope Agent 叫用的開始與完成。
ExecuteToolScope Agent 發出的工具呼叫。
InferenceScope AI 模型推論作業。
OutputScope 必須在原始範圍完成後才記錄輸出。

在同一要求的不同範圍中重複使用相同的要求與 Agent 身分識別值，以關聯相關的遙測資料。

Agent 叫用

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="agent@contoso.com",
    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."])

工具執行

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

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    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)

推斷

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"])

輸出

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

產品文件應為這些範圍定義所有產品特定的確認要求。

本機確認

本機確認會確認應用程式在確認產品特定的目的地之前，就已產生遙測資料。 使用控制台輸出或本機 OTLP 端點來檢查追蹤、計量指標和記錄是否已建立。

透過本機 OTLP 端點進行確認

將發行版設定為將遙測資料傳送到本機收集器或其他與 OTLP 相容的端點。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

使用本機輸出確認

當您想在遙測資料傳送到遠端目的地之前先確認檢測，請使用本機輸出。

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.

檢閱本機輸出中來自預期來源的跨度，例如 HTTP 要求、OpenAI 或 Azure OpenAI 呼叫、 Agent 叫用範圍、工具執行範圍或推論範圍。 針對特定目的地的確認內容是該目的地產品文件的一部分。

手動設定驗證

當您使用 Agent 365 匯出器時，必須提供一個機制來提供驗證權杖。 權杖解析器在每次匯出批次時，會使用作用中 Baggage 上下文中的 Agent 識別碼和租用戶識別碼。 發行版支援兩種方法。

提示

如果您正在使用 Microsoft 365 Agents SDK 建置 Agent，請參閱 Agent SDK 的可檢視性驗證設定，其中提供針對 Agent 型與非 Agent 型 Agent 設定 OBO 與 S2S 權杖取得的逐步指示。

手動權杖解析器

當您在 Agent Framework 管線外取得權杖、建置非 Agent Framework 應用程式，或使用服務對服務 (S2S) 驗證 (用戶端認證流程) 時，請使用手動解析器。 Agent 可以自行產生權杖，例如使用 Microsoft 驗證庫 (MSAL) 或其他權杖取得方法，但必須確保權杖具有正確的可檢視性範圍 (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite)。

注意

如果您使用服務對服務 (S2S) 驗證，則必須使用這種手動權杖解析器方法。 Agent 型權杖快取僅支援代理者 (OBO) 驗證流程。

以下範例展示 OBO (代理者) 權杖解析器模式 — Agent 透過 Agent 型驗證處理常式取得使用者權杖，並將其交換為可檢視性範圍的權杖。 有關 S2S (服務對服務)範例，以及 OBO 與 S2S 驗證的比較，請參閱 Agent SDK 的可檢視性驗證設定。

解析器必須是同步的。 在您的非同步活動處理常式中 (或透過 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",
    )

Agent 型權杖快取與 Agent Framework 應用程式

對於使用代理者 (OBO) 驗證的 Agent Framework 應用程式，若您未設定自訂 TokenResolver，發行版會透過 DI 自動註冊 IExporterTokenCache<AgenticTokenStruct>。 您的 Agent 會在執行階段呼叫 RegisterObservability() 以提供認證，快取則會負責權杖的取得與重新整理。

注意

此方法僅支援代理者 (OBO) 驗證流程。 對於服務對服務 (S2S) 驗證，請改用手動權杖解析器。

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

儲存確認屬性

為了順利通過儲存確認，您的 Agent必須 實作 InvokeAgentScope、InferenceScope 和 ExecuteToolScope。 每個範圍都對應到 Canonical 結構描述中的一個跨度作業：

SDK 範圍 跨度作業 通用參考程式碼
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

如需完整的每個範圍必要屬性與選用屬性清單 - 包括每個屬性的語意、值選擇指引，以及哪些屬性可透過 Microsoft Defender 進階搜捕查詢 - 請參閱 Agent 365可檢視性屬性參考。 適用於資料行會識別每個屬性所屬的作用域，必要資料行則區分必要 (M) 與選用 ( O) 屬性。

使用可檢視性測試您的 Agent

實作可檢視性後，請驗證是否擷取遙測資料：

  1. 移至 https://admin.cloud.microsoft/#/agents/all。
  2. 選取您的 Agent，然後選取活動。
  3. 驗證工作階段和工具呼叫會出現。

樣本應用程式和進階組態

如需運作中的樣本和進階組態選項，請參閱各語言的 GitHub 存放庫：

程式設計參考

請使用以下程式參考資料，檢閱 Microsoft OpenTelemetry 發行版類型：

疑難排解​​

此區段會說明透過 Agent 365 實作及使用 Microsoft OpenTelemetry 發行版時，所遇到的常見問題。

問題回報 Description
可檢視性資料未顯示 因為 Agent 365未啟用匯出、設定不完整或權杖解析失敗，所以無法顯示遙測資料。
遺漏租用戶識別碼或 Agent 識別碼 - 已跳過跨度 當缺少所需的租用戶或 Agent 識別碼屬性時，跨度會在匯出前篩選掉。
權杖解析失敗 - 匯出跳過或未經授權 當權杖解析器在權杖取得過程中未傳回任何權杖或發生錯誤時，匯出會跳過或遭到拒絕。
HTTP 401 未授權 要求觸達服務，但驗證失敗，因為權杖無效、過期或對象錯誤。
HTTP 403 禁止 授權失敗，因為遺漏租用戶授權或遺漏可檢視性寫入權限。
HTTP 403 禁止 - Agent 識別碼不符 當要求中的 Agent 識別碼與權杖授權的 Agent 身分識別不相符時，服務會拒絕匯出。
HTTP 429 或 5xx 錯誤 - 暫時性錯誤 暫時性節流或後端不穩定會中斷匯出，可能需要重試或批次調整。
匯出逾時 匯出作業因網路延遲或端點回覆時間過長而超過逾時限制。
匯出成功，但 Defender 或 Purview 中未顯示遙測資料 資料擷取成功，但可檢視性因下游先決條件與結構描述需求而延遲或遭到阻擋。

提示

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

可檢視性資料未顯示

徵兆：

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

根本原因：

  • Agent 365 匯出功能未啟用
  • 組態錯誤
  • 權杖解析器問題

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

  • 驗證 Agent 365 匯出已啟用

    您必須明確啟用 Agent 365 匯出器。 如果您沒有設定它，發行版可能會退回到控制台匯出器，或什麼都不匯出。 以程式碼啟用：

    from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)

    或環境變數：

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    注意

    ENABLE_A365_OBSERVABILITY_EXPORTER是次要切換開關，只有在 enable_a365=True 以程式碼設定時才會生效。 您也可以透過 a365_enable_observability_exporter kwarg 來控制。

  • 檢查權杖解析器設定

    匯出器需要一個有效的權杖解析器，可為每個匯出要求傳回一個持有人權杖。 如果權杖解析器遺漏或傳回 null，會靜默跳過匯出。

  • 啟用控制台匯出並在本機器檢查遙測資料

    新增一個控制台匯出器，以驗證遙測資料在觸達 Agent 365 端點前已產生：

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • 啟用詳細資訊記錄

    import logging

logging.basicConfig(level=logging.DEBUG)

  • 檢查記錄是否有匯出錯誤

    使用 az webapp log tail 命令來搜尋記錄中與可檢視性相關的錯誤：

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

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

症狀：系統會靜默丟棄跨度，並永不將其匯出。 某些平台會記錄跳過的跨度計數，或顯示類似 No spans with tenant/agent identity found 的訊息。 其他會在沒有記錄任何資訊的情況下靜默丟棄跨度。

解決方法：

  • 在匯出之前，發行版會依租用戶識別碼和 Agent 身分識別，將跨度分組。 缺少租用戶識別碼或 Agent 識別碼的跨度會遭到丟棄，且永遠不會送出至服務。
  • 確保 BaggageBuilder 在建立跨度前，已經用租用戶識別碼和 Agent 識別碼設定好。 這些值會透過 OpenTelemetry 上下文傳播，並附加於所有在 Baggage 範圍內建立的跨度上。 如需平台專屬的 API，請參閱 Baggage 屬性。
  • 如果您使用 Baggage 中介軟體或從託管整合套件中使用轉換上下文協助工具，請確認 TurnContext 活動具有有效的 Agent 身分識別收件者。

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

症狀：權杖解析器傳回 null 或拋出錯誤。 根據平台，可能會完全跳過匯出，或因 HTTP 401 錯誤而失敗。

解決方法：

  • 需要權杖解析器。 如果遺漏，匯出器會在啟動時拋出錯誤。 驗證已提供權杖解析器，且能傳回有效的持有人權杖。
  • 請確保傳遞給 BaggageBuilder 正確的租用戶識別碼和 Agent 識別碼，因為這些值會轉發給權杖解析器。
  • 對於在 Azure 上託管的 Agent，請驗證受管理識別具有可檢視性範圍所需的 API 權限。
  • 對於使用 Agent Framework 託管套件的 .NET 應用程式，權杖交換會透過 DI 自動處理。 如果遺漏權杖，請確認 Microsoft.Agents.A365.Observability.Hosting 已安裝並註冊。

HTTP 401 未授權

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

解決方法：

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

HTTP 403 禁止

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

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

解決方法：

  • 遺漏授權 — 請驗證您的租用戶在 Microsoft 365 系統管理中心中，已指派以下其中一項授權：

    • 測試 - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • 遺漏Agent365.Observability.OtelWrite 權限 — 請將權限授與您的身分識別 (受控識別或應用程式註冊)。 否則，遙測資料匯出將因 HTTP 403 而失敗。

授與權限

請使用以下任一選項：

  • Agent 365 CLI

    需要全域管理員帳戶；請從包含 a365.config.json 的 Agent 專案目錄執行，或使用 --agent-name。

    a365 setup permissions bot

    或者，無需組態檔：

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

  • Entra 入口網站

    無需組態檔；需要擁有藍圖應用程式註冊的全域管理員存取權。

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

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

HTTP 403 禁止 — Agent 識別碼不符

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

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

解決方法：

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

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

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

解決方法：

  • 這些錯誤通常是暫時性的，會自行解決。 Python 和 JavaScript 發行版會自動重試 HTTP 408、429 和 5xx 狀態碼。 .NET 發行版不會自動重試。
  • 如果錯誤持續，請檢查服務健康狀態儀表板。
  • 考慮透過增加批次間的排程延遲或最大匯出批次大小來降低匯出頻率。 對於 Python 和 JavaScript，請使用已在 GitHub 存放庫中記載的相關 exporterOptions或 a365_* 參數。 對於 .NET，請使用 o.Agent365.Exporter.ScheduledDelayMilliseconds 和 o.Agent365.Exporter.MaxExportBatchSize。

匯出逾時

症狀：匯出嘗試逾時。

解決方法：

  • 檢查與可檢視性端點的網路連線。

  • 在所有平台上，預設的 HTTP 要求逾時時間為 30 秒。 如果逾時經常發生，請增加匯出器選項中的逾時值：

    use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)

    請參閱 Python 存放庫，了解 a365_* 選項的完整清單。

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

症狀：記錄顯示匯出成功 (HTTP 200)，但遙測資料未顯示在 Microsoft Defender 或 Microsoft Purview 中。

解決方法：

  • 驗證您符合檢視匯出記錄的先決條件：
  • 遙測資料在成功匯出後可能需要數分鐘才能填入。 在進一步調查之前，請稍候。
  • 驗證闊度包含有效的 microsoft.tenant.id 和 gen_ai.agent.id 屬性。 即使 HTTP 匯出傳回 200，遺漏身分識別屬性也會導致跨度在伺服器端遭到丟棄。

相關內容

  • Last updated on