在 Microsoft Foundry（預覽版）（經典版）中追蹤並觀察 AI 代理

僅適用於：Foundry（經典）入口。這篇文章無法在新的 Foundry 入口網站中提供。了解更多關於新入口網站的資訊。

註

本文中的連結可能會開啟新版 Microsoft Foundry 文件的內容，而非您目前正在瀏覽的 Foundry（經典版）文件。

重要

本文中標示為（預覽）的項目目前正處於公開預覽階段。此預覽版未簽訂服務水準協議，且不建議用於生產工作負載。某些功能可能不被支援或功能受限。欲了解更多資訊，請參閱Microsoft Azure預覽補充使用條款。

在本文中，您將學習如何：

了解關鍵的追蹤概念。
在 Foundry 中追蹤並觀察 AI 代理。
探索多代理可觀察性的新語意慣例。
整合熱門代理框架。
在 Foundry 入口網站和 Azure 監視器中查看追蹤。
在代理人遊樂場查看代理討論串。

釐清代理執行背後的原因對於故障排除和除錯非常重要。然而，對於複雜的代理人來說，這可能因多種原因而變得困難：

生成回應可能需要大量步驟，讓人難以全部記住。
步驟順序可能會因使用者輸入而有所不同。
每個階段的輸入與輸出可能較長，值得更詳細的檢視。
代理執行時間的每個步驟也可能涉及巢狀結構。例如，代理可能會呼叫一個工具，該工具使用另一個程序，進而又呼叫另一個工具。如果你發現頂層代理執行輸出異常或錯誤，可能很難確定問題是在執行的哪個階段被引入的。

追蹤結果解決了這個問題，讓你能查看特定代理執行中每個基元的輸入與輸出。結果會依照原語被調用的順序顯示，方便理解並除錯 AI 代理的行為。

追蹤關鍵概念概述

在開始之前，這裡有個關鍵概念的簡要概述：

關鍵概念	描述
痕跡	追蹤透過記錄事件與狀態變更（如函式呼叫、數值與系統事件）來捕捉請求或工作流程在應用程式中的歷程。參見 OpenTelemetry Traces。
跨度	跨度是跡線的構成單元，代表跡線內的單一操作。每個區間捕捉起始與結束時間、屬性，並可巢狀以顯示階層關係。你可以看到完整的呼叫堆疊和操作順序。
屬性	屬性是附加於追蹤與範圍的鍵值對。它們提供上下文元資料，如函式參數、回傳值或自訂註解。這些資料豐富了痕跡資料，使其更具資訊性且有助於分析。
語意慣例	OpenTelemetry 定義語意慣例，以標準化追蹤資料屬性的名稱與格式。這些慣例使得跨工具與平台的資料解讀與分析變得更容易。欲了解更多，請參閱 OpenTelemetry 的語意慣例。
追蹤出口商	追蹤匯出器會將追蹤資料傳送至後端系統進行儲存與分析。 Azure AI 支援將追蹤資料匯出至 Azure 監視器及其他 OpenTelemetry 相容平台，並能整合多種可觀測工具。

最佳實務

使用一致的跨度屬性。
將評估運行ID關聯起來，以進行品質與績效分析。
刪除敏感內容。避免在屬性中儲存秘密。

擴展 OpenTelemetry 以實現多代理觀測功能

Microsoft 透過與思科孵化引擎 Outshift 合作開發的 OpenTelemetry 引入新的語意慣例，來提升多代理可觀察性。這些新增內容建立在 OpenTelemetry 與 W3C Trace Context 之上，建立了多代理系統內追蹤與遙測的標準化實務。它們促進了品質、效能、安全性與成本等關鍵指標的持續記錄。這種系統化的方法使得對多代理工作流程（包括工具調用與協作）有更全面的可視化。 Microsoft 將這些進展整合進 Microsoft Foundry、Microsoft Agent Framework、語意核心以及 LangChain、LangGraph 和 OpenAI Agents SDK 的 Azure AI 套件中。透過使用 Foundry，客戶可以為使用這些框架所建構的代理系統獲得統一的可觀察性。了解更多關於追蹤整合的資訊。

類型	背景/父級範圍	名稱/屬性/事件	目的
跨度	—	執行任務	捕捉任務規劃與事件傳播，提供任務如何分解與分配的洞見。
兒童年齡	invoke_agent	代理對代理交互作用	追蹤代理程式之間的通訊。
兒童年齡	invoke_agent	代理狀態管理	有效的情境、短期或長期記憶管理。
兒童年齡	invoke_agent	代理規劃	記錄代理人的內部規劃步驟。
兒童年齡	invoke_agent	代理協調	捕捉代理與代理之間的協調作業。
屬性	invoke_agent	工具定義	描述工具的用途或配置。
屬性	invoke_agent	llm_spans	記錄模型呼叫持續時間。
屬性	執行_工具	tool.call.arguments	記錄工具調用時傳遞的參數。
屬性	執行_工具	tool.call.results	記錄工具回傳的結果。
活動	—	評估（名稱、錯誤類型、標籤）	能結構化評估客服人員的績效與決策。

在 Microsoft Foundry SDK 中設定追蹤

若想完成聊天或使用 Foundry 建置代理，請安裝：

pip install azure-ai-projects azure-identity

要進行儀器追蹤，請安裝以下儀器函式庫：

pip install azure-monitor-opentelemetry opentelemetry-sdk

要在 Foundry 中查看追蹤，請將 Application Insights 資源連結到你的 Foundry 專案。

請至 Foundry 平台左側的導航窗格中選擇追蹤。
請建立新的 Application Insights 資源，如果您還沒有的話。
將資源與你的 Foundry 專案連結。

程式碼中的儀器追蹤

要追蹤聊天訊息內容，請將環境變數設 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED 為 true（不區分大小寫）。此內容可能包含個人資料。欲了解更多資訊，請參閱 Azure核心追蹤 OpenTelemetry Python 用戶端函式庫。

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

讓我們透過 AIProjectClient 從驗證並連接您的 Azure AI 專案開始，然後為我們的代理配置 OpenTelemetry 追蹤。

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

接著，從連接到你專案的 Application Insights 資源取得連接字串，並設定 OTLP 匯出器將遙測資料傳送到 Azure 監視器。

from azure.monitor.opentelemetry import configure_azure_monitor

connection_string = project_client.telemetry.get_application_insights_connection_string()
configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

現在，追蹤你在 Azure AI Project 中建立並執行代理與使用者訊息的程式碼，這樣你就能看到詳細的故障排除或監控步驟。

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

運行完你的代理人後，你可以開始在 Foundry 入口網站查看痕跡。

本地日誌追蹤

若要連接 Aspire Dashboard 或其他相容 OpenTelemetry 的後端，請安裝 OpenTelemetry 協定（OTLP）匯出器。透過這個匯出器，你可以將描線列印到控制台，或使用本地檢視器如 Aspire Dashboard。

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

接著，設定控制台輸出的追蹤記錄：

from azure.core.settings import settings
settings.tracing_implementation = "opentelemetry"

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

或者根據 Aspire 儀表板修改前述程式碼，以追蹤至本地 OTLP 檢視器。

現在啟用代理儀表並執行你的代理程式：

from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument()

# Start tracing
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

替代方案：VS Code 的 AI 工具包

AI Toolkit 提供你一個簡單的方法，可以在 VS Code 中本地追蹤。它使用本地相容的 OTLP 收集器，非常適合開發與除錯。

該工具包支援 Foundry Agents Service、OpenAI、Anthropic 及 LangChain 等 AI 框架，透過 OpenTelemetry。你可以在 VS Code 中立即看到痕跡，不需要雲端存取。

如需詳細設定說明及 SDK 專屬程式碼範例，請參閱 AI 工具包中的追蹤。

追蹤自訂函式

要追蹤你的自訂函式，可以使用 OpenTelemetry SDK 來進行程式碼的儀器化。

設置追蹤器提供者：初始化追蹤器提供者以管理並建立跨度。
建立跨度：用跨度包裹你想追蹤的程式碼。每個跨度代表一個工作單位，你可以將跨度巢狀組成跡樹。
新增屬性：在跨度中新增屬性以提供更多追蹤資料的上下文。
設定匯出器：將追蹤資料傳送到後端進行分析與視覺化。

這裡有一個追蹤自訂函式的範例：

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

如需詳細說明與進階使用，請參閱 OpenTelemetry 文件。

將使用者回饋附加於追蹤記錄

若要將使用者回饋附加到追蹤圖並在 Foundry 入口網站中視覺化，請為應用程式設置儀器以啟用追蹤，並使用 OpenTelemetry 的語意慣例記錄使用者回饋。

透過使用回應 ID 或串程 ID 將回饋追蹤與其聊天請求追蹤做關聯，您可以在 Foundry 入口網站中查看和管理這些追蹤。 OpenTelemetry 的規範允許標準化且豐富的追蹤資料，您可以在 Foundry 入口網站中分析這些資料，以優化效能並獲得使用者體驗洞察。這種方法幫助你充分發揮 OpenTelemetry 的效能，提升應用程式中的可觀察性。

要記錄用戶回饋，請遵循以下格式：

使用者回饋評估事件僅在使用者對生成式人工智慧模型回應做出反應時被捕捉。若可能，將此事件父化為描述此類回應的生成式 AI 範圍。

使用者回饋事件體的結構如下：

車身場	類型	描述	範例	需求等級
`comment`	字串	關於使用者回饋的更多細節	`"I did not like it"`	`Opt-in`

在追蹤資料中使用服務名稱

若要在 Application Insights 中透過唯一 ID 來識別你的服務，請在追蹤資料中使用服務名稱 OpenTelemetry 屬性。這個特性對於將多個應用程式的資料記錄到同一個 Application Insights 資源，並且想要區分它們時非常有用。

舉例來說，假設你有兩個應用程式： App-1 和 App-2，追蹤設定為將資料記錄到同一個 Application Insights 資源。或許你想設定 App-1 由 Relevance 持續評估， App-2 由 Relevance 持續評估。你可以在 Foundry 入口網站監控應用程式時，使用服務名稱來篩選 Application 。

要設定服務名稱屬性，請直接在應用程式代碼中加入，依照「使用多個追蹤器提供者與不同資源」的步驟。或者，在部署應用程式前先設定環境變數 OTEL_SERVICE_NAME 。欲了解更多關於服務名稱操作的資訊，請參閱 OTEL 環境變數與服務資源語意慣例。

要查詢給定服務名稱的追蹤資料，請查詢該屬性。cloud_roleName

| where cloud_RoleName == "service_name"

系統整合

Foundry 透過與 Microsoft Agent Framework、語意核心、LangChain、LangGraph 及 OpenAI Agent SDK 的追蹤整合，讓追蹤記錄變得簡單且變動最小。

基於 Microsoft Agent Framework 與語意核心建構的追蹤代理程式

Foundry 原生整合 Microsoft Agent Framework 與語意核心。基於這兩個框架的代理程式在可觀察性中，能立即獲得不需額外設定的追蹤功能。

了解更多關於追蹤與可觀察性的資訊，請參考語意核心和 Microsoft代理框架。

啟用基於 LangChain 與 LangGraph 的代理的追蹤

註

此處描述的 LangChain 與 LangGraph 的追蹤整合目前僅支援 Python。

你可以依據 opentelemetry-instrumentation-langchain 啟用符合 OpenTelemetry 標準的 LangChain 追蹤。

安裝必要的套件後，你就能輕鬆在程式碼中設置追踪功能。

註

LangChain 與 LangGraph 的「v1」版本目前正積極開發中。 API 表面與追蹤行為可能會在本版本中有所變動。請參考 LangChain v1.0 版本的更新說明頁面。

範例：使用 Azure AI 追蹤的 LangChain v1 代理程式

使用這個端到端範例，利用langchain-azure-ai跟蹤器來設置LangChain v1 代理。它實作了最新的 OpenTelemetry（OTel）規範，讓你能在 Observability 中查看豐富的追蹤。

安裝套件

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

設定環境

APPLICATION_INSIGHTS_CONNECTION_STRING：Azure 監視器 Application Insights 連接字串用於追蹤。
AZURE_OPENAI_ENDPOINT：你Azure OpenAI 端點網址。
AZURE_OPENAI_CHAT_DEPLOYMENT：聊天模式部署名稱。
AZURE_OPENAI_VERSION： API 版本，例如 2024-08-01-preview。
Azure憑證透過 DefaultAzureCredential（支援環境變數、管理身份、VS Code 登入等）來解析。

你可以把這些數值存到 .env 檔案中，方便本地開發。

追蹤工具設置

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

模型設定（Azure OpenAI）

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

定義工具與提示

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

使用執行時上下文並定義使用者資訊工具

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

建立代理人

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass

@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

使用追蹤模式執行代理

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))

if __name__ == "__main__":
    main()

啟用 langchain-azure-ai後，所有 LangChain v1 操作（LLM 呼叫、工具調用、代理步驟）都會使用最新的 OpenTelemetry 語意慣例來追蹤。它們會出現在可觀察性（Observability）中，並連結到你的應用洞察資源。

範例：LangGraph代理程式搭配Azure AI追蹤

本範例展示了一個簡單的 LangGraph 代理，使用langchain-azure-ai進行儀表化，以發出符合 OpenTelemetry 標準的追蹤資料，適用於圖形步驟、工具呼叫及模型調用。

安裝套件

pip install \
  langchain-azure-ai \
  langgraph==1.0.0a4 \
  langchain==1.0.0a10 \
  langchain-openai \
  azure-identity \
  python-dotenv

設定環境

APPLICATION_INSIGHTS_CONNECTION_STRING：Azure 監視器 Application Insights 連接字串用於追蹤。
AZURE_OPENAI_ENDPOINT：你Azure OpenAI 端點網址。
AZURE_OPENAI_CHAT_DEPLOYMENT：聊天模式部署名稱。
AZURE_OPENAI_VERSION： API 版本，例如 2024-08-01-preview。

你可以把這些數值存到 .env 檔案中，方便本地開發。

追蹤工具設置

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

工具

from langchain_core.tools import tool

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"

@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"

tools = [play_song_on_apple, play_song_on_spotify]

模型設定（Azure OpenAI）

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

建立 LangGraph 工作流程

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"

def call_model(state: MessagesState):
    messages = state["messages"]
    response = model.invoke(messages)
    return {"messages": [response]}

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

使用追蹤來執行

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

啟用 langchain-azure-ai後，你的 LangGraph 執行會輸出符合 OpenTelemetry 標準的範圍，用於模型呼叫、工具調用及圖轉換。這些追蹤會流向應用程式洞察（Application Insights），並在可觀察性（Observability）中顯現。

範例：LangChain 0.3 設定搭配 Azure AI 追蹤

這個簡易設定展示了如何在 LangChain 0.3 應用程式中，使用 langchain-azure-ai tracer 和 AzureChatOpenAI 來啟用 Azure AI 追蹤功能。

安裝套件

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

設定環境

APPLICATION_INSIGHTS_CONNECTION_STRING：用於追蹤的應用洞察連接字串。
AZURE_OPENAI_ENDPOINT：Azure OpenAI 端點網址。
AZURE_OPENAI_CHAT_DEPLOYMENT：聊天模式部署名稱。
AZURE_OPENAI_VERSION： API 版本，例如 2024-08-01-preview。
AZURE_OPENAI_API_KEY：Azure OpenAI API 金鑰。

示蹤器與模型設置

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

將 callbacks=[azure_tracer] 附加到您的鏈條、工具或代理上，以確保 LangChain 0.3 的操作能被追蹤並在觀測性中可見。

啟用基於 OpenAI Agents SDK 的代理追蹤功能

安裝所需的套件：

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

使用此片段設定 OpenAI Agent SDK 的 OpenTelemetry 追蹤，並對框架進行監測。如果設定為 APPLICATION_INSIGHTS_CONNECTION_STRING，它會匯出成 Azure 監視器;否則，會回退到主機。

import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

在 Foundry 平台查看追蹤記錄

在你的專案中，請進入 追蹤（Trace ）選項，依照你認為合適的方式過濾你的追蹤。

透過選擇追蹤，你可以逐一檢視每個區間，找出問題，同時觀察應用程式的反應情況。這個過程有助於你除錯並找出應用程式中的問題。

在 Azure 監視器中查看追蹤

如果你是用前面的程式碼片段記錄追蹤，現在就可以在 Azure 監視器 Application Insights 中查看你的追蹤了。你可以從 管理資料來源 開啟應用程式洞察，並使用 端對端交易細節檢視 來進一步調查。

欲了解更多如何將 Azure AI 推論追蹤傳送至 Azure 監視器並建立 Azure 監視器資源的資訊，請參見 Azure 監視器開放遙測文件。

在 Foundry Agents 遊樂場查看討論串結果

Foundry 入口平台的 Agent 測試環境讓你可以查看代理人生成的執行緒與運行結果。要查看執行串結果，請選擇活躍執行串中的 「線程日誌 」。您也可以選擇「指標」，以啟用模型在多個 AI 品質 及 風險與安全維度的自動評估。

註

如定價頁面中「信任與可觀察性」所述，操場評估是收費的。結果會在到期前24小時內公布。要取得評估結果，請選擇你想要的指標並與你的經紀人交流。

以下地區無法提供評估。
- australiaeast
- japaneast
- southindia
- uksouth

選擇 Thread 日誌後，請查看：

討論串細節
運行資訊
有序運行步驟與工具呼叫
使用者與代理人之間的輸入與輸出
連結評估指標（若啟用）

提示

如果你想查看先前討論串的結果，請在代理人畫面選擇「我的討論串」。 選擇一個討論串，然後選擇 「在遊樂場嘗試」。你可以在螢幕頂端看到 「線程日誌」 按鈕，可以查看追蹤結果。

註

可觀察性功能如風險與安全評估，依據 Azure 價格頁面列出的消耗量計費。

Python 範例包含可執行的 Python 程式碼，可透過同步與非同步客戶端進行追蹤。
用於控制台追蹤和 Azure 監視器的追蹤代理程式的 Python 範例
JavaScript 範例包含可完全執行的 JavaScript 程式碼，可透過同步與非同步用戶端進行追蹤。
C# Samples 包含可完整執行的 C# 程式碼，可透過同步與非同步方法進行推論。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-01

在 Microsoft Foundry（預覽版）（經典版）中追蹤並觀察 AI 代理

追蹤關鍵概念概述

最佳實務

擴展 OpenTelemetry 以實現多代理觀測功能

在 Microsoft Foundry SDK 中設定追蹤

程式碼中的儀器追蹤

本地日誌追蹤

替代方案：VS Code 的 AI 工具包

追蹤自訂函式

將使用者回饋附加於追蹤記錄

在追蹤資料中使用服務名稱

系統整合

基於 Microsoft Agent Framework 與 語意核心 建構的追蹤代理程式

啟用基於 LangChain 與 LangGraph 的代理的追蹤

範例：使用 Azure AI 追蹤的 LangChain v1 代理程式

安裝套件

設定環境

追蹤工具設置

模型設定（Azure OpenAI）

定義工具與提示

使用執行時上下文並定義使用者資訊工具

建立代理人

使用追蹤模式執行代理

範例：LangGraph代理程式搭配Azure AI追蹤

安裝套件

設定環境

追蹤工具設置

工具

模型設定（Azure OpenAI）

建立 LangGraph 工作流程

使用追蹤來執行

範例：LangChain 0.3 設定搭配 Azure AI 追蹤

安裝套件

設定環境

示蹤器與模型設置

啟用基於 OpenAI Agents SDK 的代理追蹤功能

在 Foundry 平台查看追蹤記錄

在 Azure 監視器 中查看追蹤

在 Foundry Agents 遊樂場查看討論串結果

相關內容

意見反應

其他資源

基於 Microsoft Agent Framework 與語意核心建構的追蹤代理程式

在 Azure 監視器中查看追蹤