探索 Agent 式開發 -

AI Toolkit 中的追蹤 (Tracing)

AI Toolkit 提供追蹤功能，協助您監控並分析 AI 應用程式的效能。您可以追蹤 AI 應用程式的執行過程，包含與生成式 AI 模型的互動，藉此深入了解其行為與效能表現。

AI Toolkit 會代管一個本機 HTTP 與 gRPC 伺服器來收集追蹤資料。此收集器伺服器與 OTLP (OpenTelemetry Protocol) 相容，大多數語言模型 SDK 要麼直接支援 OTLP，要麼擁有非微軟提供的檢測函式庫來支援它。請使用 AI Toolkit 來視覺化所收集的檢測資料。

所有支援 OTLP 並遵循 生成式 AI 系統語意慣例 (semantic conventions for generative AI systems) 的框架或 SDK 皆受支援。下表列出了已測試相容性的常見 AI SDK。

Azure AI Inference Foundry Agent Service Anthropic Gemini LangChain OpenAI SDK 3 OpenAI Agents SDK
Python ✅ ✅ ✅ (traceloop, monocle)1,2 ✅ (monocle) ✅ (LangSmith, monocle)1,2 ✅ (opentelemetry-python-contrib, monocle)1 ✅ (Logfire, monocle)1,2
TS/JS ✅ ✅ ✅ (traceloop)1,2 ❌ ✅ (traceloop)1,2 ✅ (traceloop)1,2 ❌
  1. 括號內的 SDK 是非微軟工具，用於增加對 OTLP 的支援，因為官方 SDK 本身並不支援 OTLP。
  2. 這些工具並未完全遵循生成式 AI 系統的 OpenTelemetry 規則。
  3. 對於 OpenAI SDK，僅支援 Chat Completions API。目前尚不支援 Responses API。

如何開始使用追蹤功能

  1. 透過在樹狀檢視中選擇 **Tracing** 來開啟追蹤網頁檢視。

  2. 選擇 **Start Collector** 按鈕以啟動本機 OTLP 追蹤收集器伺服器。

    Screenshot showing the Start Collector button in the Tracing webview.

  3. 使用程式碼片段啟用檢測。請參閱 設定檢測 章節，以取得適用於不同語言與 SDK 的程式碼片段。

  4. 執行您的應用程式以產生追蹤資料。

  5. 在追蹤網頁檢視中，選擇 **Refresh** 按鈕以查看新的追蹤資料。

    Screenshot showing the Trace List in the Tracing webview.

設定檢測 (Instrumentation)

在您的 AI 應用程式中設定追蹤以收集追蹤資料。以下程式碼片段顯示如何為不同的 SDK 與語言設定追蹤：

所有 SDK 的流程皆類似

  • 將追蹤功能加入您的 LLM 或 Agent 應用程式。
  • 設定 OTLP 追蹤匯出工具 (exporter) 以使用 AITK 本機收集器。
Azure AI Inference SDK - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http azure-ai-inference[opentelemetry]

設定

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"
os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-azure-ai-agents"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from azure.ai.inference.tracing import AIInferenceInstrumentor
AIInferenceInstrumentor().instrument(True)
Azure AI Inference SDK - TypeScript/JavaScript

安裝

npm install @azure/opentelemetry-instrumentation-azure-sdk @opentelemetry/api @opentelemetry/exporter-trace-otlp-proto @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/sdk-trace-node

設定

const { context } = require('@opentelemetry/api');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const {
  NodeTracerProvider,
  SimpleSpanProcessor
} = require('@opentelemetry/sdk-trace-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');

const exporter = new OTLPTraceExporter({
  url: 'https://:4318/v1/traces'
});
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    'service.name': 'opentelemetry-instrumentation-azure-ai-inference'
  }),
  spanProcessors: [new SimpleSpanProcessor(exporter)]
});
provider.register();

const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const {
  createAzureSdkInstrumentation
} = require('@azure/opentelemetry-instrumentation-azure-sdk');

registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()]
});
Foundry Agent Service - Python

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http azure-ai-inference[opentelemetry]

設定

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"
os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-azure-ai-agents"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument(True)
Foundry Agent Service - TypeScript/JavaScript

安裝

npm install @azure/opentelemetry-instrumentation-azure-sdk @opentelemetry/api @opentelemetry/exporter-trace-otlp-proto @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/sdk-trace-node

設定

const { context } = require('@opentelemetry/api');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const {
  NodeTracerProvider,
  SimpleSpanProcessor
} = require('@opentelemetry/sdk-trace-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');

const exporter = new OTLPTraceExporter({
  url: 'https://:4318/v1/traces'
});
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    'service.name': 'opentelemetry-instrumentation-azure-ai-inference'
  }),
  spanProcessors: [new SimpleSpanProcessor(exporter)]
});
provider.register();

const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const {
  createAzureSdkInstrumentation
} = require('@azure/opentelemetry-instrumentation-azure-sdk');

registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()]
});
Anthropic - Python

OpenTelemetry

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-anthropic

設定

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-anthropic-traceloop"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
AnthropicInstrumentor().instrument()

Monocle

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

設定

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-anthropic",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)
Anthropic - TypeScript/JavaScript

安裝

npm install @traceloop/node-server-sdk

設定

const { initialize } = require('@traceloop/node-server-sdk');
const { trace } = require('@opentelemetry/api');

initialize({
  appName: 'opentelemetry-instrumentation-anthropic-traceloop',
  baseUrl: 'https://:4318',
  disableBatch: true
});
Google Gemini - Python

OpenTelemetry

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-google-genai

設定

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-google-genai"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
GoogleGenAiSdkInstrumentor().instrument(enable_content_recording=True)

Monocle

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

設定

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-google-genai",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)
LangChain - Python

LangSmith

安裝

pip install langsmith[otel]

設定

import os
os.environ["LANGSMITH_OTEL_ENABLED"] = "true"
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://:4318"

Monocle

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

設定

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-langchain",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)
LangChain - TypeScript/JavaScript

安裝

npm install @traceloop/node-server-sdk

設定

const { initialize } = require('@traceloop/node-server-sdk');
initialize({
  appName: 'opentelemetry-instrumentation-langchain-traceloop',
  baseUrl: 'https://:4318',
  disableBatch: true
});
OpenAI - Python

OpenTelemetry

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-openai-v2

設定

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
import os

os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"

# Set up resource
resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-openai"
})

# Create tracer provider
trace.set_tracer_provider(TracerProvider(resource=resource))

# Configure OTLP exporter
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces"
)

# Add span processor
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)

# Set up logger provider
logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

# Enable OpenAI instrumentation
OpenAIInstrumentor().instrument()

Monocle

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

設定

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-openai",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)
OpenAI - TypeScript/JavaScript

安裝

npm install @traceloop/instrumentation-openai @traceloop/node-server-sdk

設定

const { initialize } = require('@traceloop/node-server-sdk');
initialize({
  appName: 'opentelemetry-instrumentation-openai-traceloop',
  baseUrl: 'https://:4318',
  disableBatch: true
});
OpenAI Agents SDK - Python

Logfire

安裝

pip install logfire

設定

import logfire
import os

os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = "https://:4318/v1/traces"

logfire.configure(
    service_name="opentelemetry-instrumentation-openai-agents-logfire",
    send_to_logfire=False,
)
logfire.instrument_openai_agents()

Monocle

安裝

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http monocle_apptrace

設定

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-openai-agents",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

範例 1：使用 Opentelemetry 設定 Azure AI Inference SDK 的追蹤

以下端對端範例使用 Python 中的 Azure AI Inference SDK，並展示如何設定追蹤提供者與檢測。

先決條件

若要執行此範例，您需要具備以下先決條件：

設定您的開發環境

使用以下說明來部署一個預先設定好的開發環境，其中包含執行此範例所需的所有相依性項目。

  1. 設定 GitHub 個人存取權杖 (Personal Access Token)

    使用免費的 GitHub Models 作為範例模型。

    開啟 GitHub Developer Settings 並選擇 **Generate new token**。

    重要

    權杖必須具備 models:read 權限，否則將會回傳未授權錯誤。此權杖會被發送到 Microsoft 服務。

  2. 建立環境變數

    使用下列任一程式碼片段，建立一個環境變數將您的權杖設定為用戶端程式碼的 key。請將 <your-github-token-goes-here> 取代為您的實際 GitHub 權杖。

    bash

    export GITHUB_TOKEN="<your-github-token-goes-here>"

    powershell

    $Env:GITHUB_TOKEN="<your-github-token-goes-here>"

    Windows 命令提示字元

    set GITHUB_TOKEN=<your-github-token-goes-here>

  3. 安裝 Python 套件

    以下指令會安裝使用 Azure AI Inference SDK 進行追蹤所需的 Python 套件：

    pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http azure-ai-inference[opentelemetry]

  4. 設定追蹤

    1. 在您的電腦上為此專案建立一個新的本機目錄。

      mkdir my-tracing-app

    2. 導覽至您建立的目錄。

      cd my-tracing-app

    3. 在該目錄中開啟 Visual Studio Code

      code .

  5. 建立 Python 檔案

    1. 在 my-tracing-app 目錄中，建立一個名為 main.py 的 Python 檔案。

      您將會在其中加入設定追蹤並與 Azure AI Inference SDK 互動的程式碼。

    2. 將以下程式碼加入 main.py 並儲存檔案

      import os

### Set up for OpenTelemetry tracing ###
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"
os.environ["AZURE_SDK_TRACING_IMPLEMENTATION"] = "opentelemetry"

from opentelemetry import trace, _events
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._events import EventLoggerProvider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

github_token = os.environ["GITHUB_TOKEN"]

resource = Resource(attributes={
    "service.name": "opentelemetry-instrumentation-azure-ai-inference"
})
provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(
    endpoint="https://:4318/v1/traces",
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

logger_provider = LoggerProvider(resource=resource)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://:4318/v1/logs"))
)
_events.set_event_logger_provider(EventLoggerProvider(logger_provider))

from azure.ai.inference.tracing import AIInferenceInstrumentor
AIInferenceInstrumentor().instrument()
### Set up for OpenTelemetry tracing ###

from azure.ai.inference import ChatCompletionsClient
from azure.ai.inference.models import UserMessage
from azure.ai.inference.models import TextContentItem
from azure.core.credentials import AzureKeyCredential

client = ChatCompletionsClient(
    endpoint = "https://models.inference.ai.azure.com",
    credential = AzureKeyCredential(github_token),
    api_version = "2024-08-01-preview",
)

response = client.complete(
    messages = [
        UserMessage(content = [
            TextContentItem(text = "hi"),
        ]),
    ],
    model = "gpt-4.1",
    tools = [],
    response_format = "text",
    temperature = 1,
    top_p = 1,
)

print(response.choices[0].message.content)

  6. 執行程式碼

    1. 在 Visual Studio Code 中開啟新的終端機。

    2. 在終端機中，使用指令 python main.py 執行程式碼。

  7. 在 AI Toolkit 中檢查追蹤資料

    當您執行程式碼並重新整理追蹤網頁檢視後，列表中將會出現新的追蹤記錄。

    選擇該追蹤記錄以開啟追蹤詳細資訊網頁檢視。

    Screenshot showing selecting a trace from the Trace List in the Tracing webview.

    在左側的跨度樹狀檢視 (span tree view) 中檢查應用程式的完整執行流程。

    在右側的跨度詳細資訊檢視中選擇一個跨度，即可在 **Input + Output** 索引標籤中查看生成式 AI 訊息。

    選擇 **Metadata** 索引標籤以檢視原始中繼資料。

    Screenshot showing the Trace Details view in the Tracing webview.

範例 2：使用 Monocle 設定 OpenAI Agents SDK 的追蹤

以下端對端範例使用 Python 中的 OpenAI Agents SDK 搭配 Monocle，並展示如何為多 Agent 旅遊預訂系統設定追蹤。

先決條件

若要執行此範例，您需要具備以下先決條件：

設定您的開發環境

使用以下說明來部署一個預先設定好的開發環境，其中包含執行此範例所需的所有相依性項目。

  1. 建立環境變數

    使用下列任一程式碼片段，為您的 OpenAI API Key 建立環境變數。請將 <your-openai-api-key> 取代為您的實際 OpenAI API Key。

    bash

    export OPENAI_API_KEY="<your-openai-api-key>"

    powershell

    $Env:OPENAI_API_KEY="<your-openai-api-key>"

    Windows 命令提示字元

    set OPENAI_API_KEY=<your-openai-api-key>

    或者，在您的專案目錄中建立一個 .env 檔案

    OPENAI_API_KEY=<your-openai-api-key>

  2. 安裝 Python 套件

    建立一個內容如下的 requirements.txt 檔案

    opentelemetry-sdk
opentelemetry-exporter-otlp-proto-http
monocle_apptrace
openai-agents
python-dotenv

    使用以下指令安裝套件

    pip install -r requirements.txt

  3. 設定追蹤

    1. 在您的電腦上為此專案建立一個新的本機目錄。

      mkdir my-agents-tracing-app

    2. 導覽至您建立的目錄。

      cd my-agents-tracing-app

    3. 在該目錄中開啟 Visual Studio Code

      code .

  4. 建立 Python 檔案

    1. 在 my-agents-tracing-app 目錄中，建立一個名為 main.py 的 Python 檔案。

      您將會在其中加入使用 Monocle 設定追蹤並與 OpenAI Agents SDK 互動的程式碼。

    2. 將以下程式碼加入 main.py 並儲存檔案

      import os

from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Import monocle_apptrace
from monocle_apptrace import setup_monocle_telemetry

# Setup Monocle telemetry with OTLP span exporter for traces
setup_monocle_telemetry(
    workflow_name="opentelemetry-instrumentation-openai-agents",
    span_processors=[
        BatchSpanProcessor(
            OTLPSpanExporter(endpoint="https://:4318/v1/traces")
        )
    ]
)

from agents import Agent, Runner, function_tool

# Define tool functions
@function_tool
def book_flight(from_airport: str, to_airport: str) -> str:
    """Book a flight between airports."""
    return f"Successfully booked a flight from {from_airport} to {to_airport} for 100 USD."

@function_tool
def book_hotel(hotel_name: str, city: str) -> str:
    """Book a hotel reservation."""
    return f"Successfully booked a stay at {hotel_name} in {city} for 50 USD."

@function_tool
def get_weather(city: str) -> str:
    """Get weather information for a city."""
    return f"The weather in {city} is sunny and 75°F."

# Create specialized agents
flight_agent = Agent(
    name="Flight Agent",
    instructions="You are a flight booking specialist. Use the book_flight tool to book flights.",
    tools=[book_flight],
)

hotel_agent = Agent(
    name="Hotel Agent",
    instructions="You are a hotel booking specialist. Use the book_hotel tool to book hotels.",
    tools=[book_hotel],
)

weather_agent = Agent(
    name="Weather Agent",
    instructions="You are a weather information specialist. Use the get_weather tool to provide weather information.",
    tools=[get_weather],
)

# Create a coordinator agent with tools
coordinator = Agent(
    name="Travel Coordinator",
    instructions="You are a travel coordinator. Delegate flight bookings to the Flight Agent, hotel bookings to the Hotel Agent, and weather queries to the Weather Agent.",
    tools=[
        flight_agent.as_tool(
            tool_name="flight_expert",
            tool_description="Handles flight booking questions and requests.",
        ),
        hotel_agent.as_tool(
            tool_name="hotel_expert",
            tool_description="Handles hotel booking questions and requests.",
        ),
        weather_agent.as_tool(
            tool_name="weather_expert",
            tool_description="Handles weather information questions and requests.",
        ),
    ],
)

# Run the multi-agent workflow
if __name__ == "__main__":
    import asyncio

    result = asyncio.run(
        Runner.run(
            coordinator,
            "Book me a flight today from SEA to SFO, then book the best hotel there and tell me the weather.",
        )
    )
    print(result.final_output)

  5. 執行程式碼

    1. 在 Visual Studio Code 中開啟新的終端機。

    2. 在終端機中，使用指令 python main.py 執行程式碼。

  6. 在 AI Toolkit 中檢查追蹤資料

    當您執行程式碼並重新整理追蹤網頁檢視後，列表中將會出現新的追蹤記錄。

    選擇該追蹤記錄以開啟追蹤詳細資訊網頁檢視。

    Screenshot showing selecting a trace from the Trace List in the Tracing webview.

    在左側的跨度樹狀檢視中檢查應用程式的完整執行流程，包含 Agent 呼叫、工具呼叫與 Agent 委派。

    在右側的跨度詳細資訊檢視中選擇一個跨度，即可在 **Input + Output** 索引標籤中查看生成式 AI 訊息。

    選擇 **Metadata** 索引標籤以檢視原始中繼資料。

    Screenshot showing the Trace Details view in the Tracing webview.

您所學到的內容

在本文章中，您學習了如何：

  • 使用 Azure AI Inference SDK 與 OpenTelemetry 在您的 AI 應用程式中設定追蹤。
  • 設定 OTLP 追蹤匯出工具，將追蹤資料傳送至本機收集器伺服器。
  • 執行您的應用程式以產生追蹤資料，並在 AI Toolkit 網頁檢視中檢視追蹤記錄。
  • 透過 OTLP，將追蹤功能用於多種 SDK 與語言（包含 Python 和 TypeScript/JavaScript）以及非微軟工具。
  • 使用提供的程式碼片段，對各種 AI 框架（Anthropic、Gemini、LangChain、OpenAI 等）進行檢測。
  • 使用追蹤網頁檢視 UI（包含 **Start Collector** 與 **Refresh** 按鈕）來管理追蹤資料。
  • 設定您的開發環境（包含環境變數與套件安裝）以啟用追蹤功能。
  • 使用跨度樹狀結構與詳細資訊檢視，分析應用程式的執行流程，包含生成式 AI 的訊息傳遞流程與中繼資料。
10/03/2025
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.