이 출시되었습니다! 11월의 새로운 기능 및 수정 사항을 읽어보세요.

AI Toolkit의 추적

AI Toolkit은 AI 애플리케이션의 성능을 모니터링하고 분석하는 데 도움이 되는 추적 기능을 제공합니다. 생성형 AI 모델과의 상호 작용을 포함하여 AI 애플리케이션의 실행을 추적하여 동작 및 성능에 대한 인사이트를 얻을 수 있습니다.

AI Toolkit은 추적 데이터를 수집하기 위한 로컬 HTTP 및 gRPC 서버를 호스팅합니다. 수집기 서버는 OTLP(OpenTelemetry Protocol)와 호환되며 대부분의 언어 모델 SDK는 OTLP를 직접 지원하거나 이를 지원하기 위한 비 Microsoft 계측 라이브러리를 보유하고 있습니다. AI Toolkit을 사용하여 수집된 계측 데이터를 시각화하세요.

OTLP를 지원하고 생성형 AI 시스템에 대한 의미 체계 규칙을 따르는 모든 프레임워크 또는 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는 공식 SDK가 OTLP를 지원하지 않기 때문에 OTLP 지원을 추가하는 비 Microsoft 도구입니다.
  2. 이러한 도구는 생성형 AI 시스템에 대한 OpenTelemetry 규칙을 완전히 따르지 않습니다.
  3. OpenAI SDK의 경우 Chat Completions API만 지원됩니다. Responses API는 아직 지원되지 않습니다.

추적 시작하기

  1. 트리 보기에서 **추적**을 선택하여 추적 웹뷰를 엽니다.

  2. 로컬 OTLP 추적 수집기 서버를 시작하려면 **수집기 시작** 버튼을 선택합니다.

    Screenshot showing the Start Collector button in the Tracing webview.

  3. 코드 스니펫으로 계측을 활성화합니다. 다양한 언어 및 SDK에 대한 코드 스니펫은 계측 설정 섹션을 참조하세요.

  4. 앱을 실행하여 추적 데이터를 생성합니다.

  5. 추적 웹뷰에서 **새로고침** 버튼을 선택하여 새 추적 데이터를 확인합니다.

    Screenshot showing the Trace List in the Tracing webview.

계측 설정

추적 데이터를 수집하기 위해 AI 애플리케이션에 추적을 설정합니다. 다음 코드 스니펫은 다양한 SDK 및 언어에 대한 추적 설정을 보여줍니다.

모든 SDK에 대해 프로세스는 유사합니다.

  • LLM 또는 에이전트 앱에 추적을 추가합니다.
  • AITK 로컬 수집기를 사용하도록 OTLP 추적 내보내기를 설정합니다.
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 개인 액세스 토큰 설정

    무료 GitHub Models를 예제 모델로 사용합니다.

    GitHub 개발자 설정을 열고 **새 토큰 생성**을 선택합니다.

    중요

    토큰에 `models:read` 권한이 필요합니다. 그렇지 않으면 unauthorized 오류가 반환됩니다. 토큰은 Microsoft 서비스로 전송됩니다.

  2. 환경 변수 만들기

    다음 코드 스니펫 중 하나를 사용하여 토큰을 클라이언트 코드의 키로 설정하는 환경 변수를 만듭니다. ``를 실제 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.

    왼쪽 스팬 트리 보기에서 앱의 전체 실행 흐름을 확인합니다.

    오른쪽 스팬 세부 정보 보기에서 스팬을 선택하여 **입력 + 출력** 탭에서 생성형 AI 메시지를 확인합니다.

    **메타데이터** 탭을 선택하여 원시 메타데이터를 확인합니다.

    Screenshot showing the Trace Details view in the Tracing webview.

예제 2: Monocle을 사용하여 OpenAI Agents SDK로 추적 설정

다음의 종단 간 예제는 Monocle을 사용하는 Python의 OpenAI Agents SDK를 사용하며 다중 에이전트 여행 예약 시스템에 대한 추적 설정을 보여줍니다.

전제 조건

이 예제를 실행하려면 다음 전제 조건이 필요합니다.

개발 환경 설정

이 예제를 실행하는 데 필요한 모든 종속성을 포함하는 사전 구성된 개발 환경을 배포하려면 다음 지침을 사용하세요.

  1. 환경 변수 만들기

    다음 코드 스니펫 중 하나를 사용하여 OpenAI API 키에 대한 환경 변수를 만듭니다. ``를 실제 OpenAI API 키로 바꾸세요.

    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.

    왼쪽 스팬 트리 보기에서 에이전트 호출, 도구 호출 및 에이전트 위임을 포함한 앱의 전체 실행 흐름을 확인합니다.

    오른쪽 스팬 세부 정보 보기에서 스팬을 선택하여 **입력 + 출력** 탭에서 생성형 AI 메시지를 확인합니다.

    **메타데이터** 탭을 선택하여 원시 메타데이터를 확인합니다.

    Screenshot showing the Trace Details view in the Tracing webview.

학습 내용

이 문서에서는 다음 방법을 배웠습니다.

  • Azure AI Inference SDK와 OpenTelemetry를 사용하여 AI 애플리케이션에 추적을 설정합니다.
  • OTLP 추적 내보내기를 구성하여 로컬 수집기 서버로 추적 데이터를 보냅니다.
  • 애플리케이션을 실행하여 추적 데이터를 생성하고 AI Toolkit 웹뷰에서 추적을 확인합니다.
  • Python 및 TypeScript/JavaScript를 포함한 여러 SDK 및 언어와 OTLP를 통한 비 Microsoft 도구를 사용하여 추적 기능을 사용합니다.
  • 제공된 코드 스니펫을 사용하여 다양한 AI 프레임워크(Anthropic, Gemini, LangChain, OpenAI 등)를 계측합니다.
  • **수집기 시작** 및 **새로고침** 버튼을 포함한 추적 웹뷰 UI를 사용하여 추적 데이터를 관리합니다.
  • 추적을 활성화하기 위해 환경 변수 및 패키지 설치를 포함한 개발 환경을 설정합니다.
  • 생성형 AI 메시지 흐름 및 메타데이터를 포함하여 스팬 트리 및 세부 정보 보기를 사용하여 앱의 실행 흐름을 분석합니다.
10/03/2025
English 한국어 中文(简体)
© . This site is unofficial and not affiliated with Microsoft.