트레이싱

Agents SDK에는 내장 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트(LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 정의 이벤트 포함)의 포괄적인 기록을 수집합니다. Traces dashboard를 사용하면 개발 중과 프로덕션에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다.

Note

트레이싱은 기본적으로 활성화되어 있습니다. 일반적으로 다음 세 가지 방법으로 비활성화할 수 있습니다:

환경 변수 OPENAI_AGENTS_DISABLE_TRACING=1을 설정하여 전역적으로 트레이싱을 비활성화할 수 있습니다
코드에서 set_tracing_disabled(True)를 사용해 전역적으로 트레이싱을 비활성화할 수 있습니다
단일 실행에 대해 agents.run.RunConfig.tracing_disabled를 True로 설정하여 트레이싱을 비활성화할 수 있습니다

OpenAI API를 사용하면서 Zero Data Retention(ZDR) 정책을 적용하는 조직의 경우, 트레이싱을 사용할 수 없습니다.

트레이스와 스팬

Traces는 하나의 "워크플로"에 대한 단일 종단 간 작업을 나타냅니다. Traces는 Spans로 구성됩니다. Traces에는 다음 속성이 있습니다:
- workflow_name: 논리적 워크플로나 앱입니다. 예: "Code generation", "Customer service"
- trace_id: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 trace_<32_alphanumeric>이어야 합니다
- group_id: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다
- disabled: True이면 트레이스가 기록되지 않습니다
- metadata: 트레이스용 선택적 메타데이터입니다
Spans는 시작 시점과 종료 시점이 있는 작업을 나타냅니다. Spans에는 다음이 있습니다:
- started_at 및 ended_at 타임스탬프
- trace_id: 해당 스팬이 속한 트레이스를 나타냅니다
- parent_id: 이 스팬의 상위 스팬(있는 경우)을 가리킵니다
- span_data: 스팬 관련 정보입니다. 예를 들어 AgentSpanData는 Agent 정보를, GenerationSpanData는 LLM 생성 정보를 포함합니다

기본 트레이싱

기본적으로 SDK는 다음을 트레이싱합니다:

전체 Runner.{run, run_sync, run_streamed}()는 trace()로 감싸집니다
에이전트가 실행될 때마다 agent_span()으로 감싸집니다
LLM 생성은 generation_span()으로 감싸집니다
함수 도구 호출은 각각 function_span()으로 감싸집니다
가드레일은 guardrail_span()으로 감싸집니다
핸드오프는 handoff_span()으로 감싸집니다
오디오 입력(음성-텍스트)은 transcription_span()으로 감싸집니다
오디오 출력(텍스트-음성)은 speech_span()으로 감싸집니다
관련 오디오 스팬은 speech_group_span() 하위로 중첩될 수 있습니다

기본적으로 트레이스 이름은 "Agent workflow"입니다. trace를 사용하면 이 이름을 설정할 수 있고, RunConfig로 이름 및 기타 속성을 구성할 수도 있습니다.

또한 사용자 정의 트레이스 프로세서를 설정하여 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상).

상위 수준 트레이스

경우에 따라 여러 run() 호출을 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 이때 전체 코드를 trace()로 감싸면 됩니다.

from agents import Agent, Runner, trace

async def main():
    agent = Agent(name="Joke generator", instructions="Tell funny jokes.")

    with trace("Joke workflow"): # (1)!
        first_result = await Runner.run(agent, "Tell me a joke")
        second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}")
        print(f"Joke: {first_result.final_output}")
        print(f"Rating: {second_result.final_output}")

두 번의 Runner.run 호출이 with trace()로 감싸져 있으므로, 각각의 실행은 별도 트레이스 2개를 만드는 대신 전체 트레이스의 일부가 됩니다

트레이스 생성

trace() 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작과 종료가 필요합니다. 방법은 두 가지입니다:

권장: with trace(...) as my_trace처럼 컨텍스트 매니저로 사용합니다. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작/종료됩니다
trace.start() 및 trace.finish()를 수동으로 호출할 수도 있습니다

현재 트레이스는 Python contextvar로 추적됩니다. 즉, 동시성 환경에서도 자동으로 동작합니다. 트레이스를 수동 시작/종료하는 경우 현재 트레이스를 갱신하려면 start()/finish()에 mark_as_current와 reset_current를 전달해야 합니다.

스팬 생성

다양한 *_span() 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동 생성할 필요는 없습니다. 사용자 정의 스팬 정보 추적을 위해 custom_span() 함수가 제공됩니다.

스팬은 자동으로 현재 트레이스에 포함되며, Python contextvar로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다.

민감한 데이터

일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다.

generation_span()은 LLM 생성의 입력/출력을 저장하고, function_span()은 함수 호출의 입력/출력을 저장합니다. 여기에 민감한 데이터가 포함될 수 있으므로 RunConfig.trace_include_sensitive_data를 통해 해당 데이터 캡처를 비활성화할 수 있습니다.

마찬가지로 오디오 스팬에는 기본적으로 입력 및 출력 오디오에 대한 base64 인코딩 PCM 데이터가 포함됩니다. VoicePipelineConfig.trace_include_sensitive_audio_data를 구성하여 이 오디오 데이터 캡처를 비활성화할 수 있습니다.

기본적으로 trace_include_sensitive_data는 True입니다. 앱 실행 전에 OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA 환경 변수를 true/1 또는 false/0으로 설정해 코드 변경 없이 기본값을 지정할 수 있습니다.

사용자 정의 트레이싱 프로세서

트레이싱의 상위 수준 아키텍처는 다음과 같습니다:

초기화 시 트레이스를 생성하는 역할을 하는 전역 TraceProvider를 생성합니다
TraceProvider를 BatchTraceProcessor로 구성하고, 이는 트레이스/스팬을 배치로 BackendSpanExporter에 전송하며, 해당 Exporter는 스팬과 트레이스를 배치로 OpenAI 백엔드로 내보냅니다

기본 설정을 사용자화하여 트레이스를 대체 또는 추가 백엔드로 전송하거나 exporter 동작을 수정하려면 두 가지 방법이 있습니다:

add_trace_processor()를 사용하면 준비되는 즉시 트레이스와 스팬을 받는 추가 트레이스 프로세서를 더할 수 있습니다. 이를 통해 OpenAI 백엔드 전송과 별도로 자체 처리를 수행할 수 있습니다
set_trace_processors()를 사용하면 기본 프로세서를 사용자 정의 트레이스 프로세서로 대체할 수 있습니다. 이 경우 해당 작업을 수행하는 TracingProcessor를 포함하지 않으면 트레이스는 OpenAI 백엔드로 전송되지 않습니다

비 OpenAI 모델에서의 트레이싱

비 OpenAI 모델에서도 OpenAI API 키를 사용해 트레이싱 비활성화 없이 OpenAI Traces dashboard에서 무료 트레이싱을 활성화할 수 있습니다.

import os
from agents import set_tracing_export_api_key, Agent, Runner
from agents.extensions.models.litellm_model import LitellmModel

tracing_api_key = os.environ["OPENAI_API_KEY"]
set_tracing_export_api_key(tracing_api_key)

model = LitellmModel(
    model="your-model-name",
    api_key="your-api-key",
)

agent = Agent(
    name="Assistant",
    model=model,
)

단일 실행에 대해서만 다른 트레이싱 키가 필요하다면, 전역 exporter를 변경하는 대신 RunConfig를 통해 전달하세요.

from agents import Runner, RunConfig

await Runner.run(
    agent,
    input="Hello",
    run_config=RunConfig(tracing={"api_key": "sk-tracing-123"}),
)

추가 참고 사항

Openai Traces dashboard에서 무료 트레이스를 확인하세요

에코시스템 통합

다음 커뮤니티 및 벤더 통합은 OpenAI Agents SDK 트레이싱 표면을 지원합니다.