트레이싱
Agents SDK에는 내장 트레이싱이 포함되어 있어 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 사용자 지정 이벤트까지. Traces 대시보드를 사용하면 개발 및 운영 환경에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다.
Note
트레이싱은 기본적으로 활성화되어 있습니다. 트레이싱을 비활성화하는 방법은 두 가지입니다:
- 환경 변수
OPENAI_AGENTS_DISABLE_TRACING=1를 설정하여 전역으로 비활성화 - 단일 실행에 대해
agents.run.RunConfig.tracing_disabled를True로 설정하여 비활성화
OpenAI의 API를 사용하는 Zero Data Retention (ZDR) 정책 조직의 경우, 트레이싱을 사용할 수 없습니다.
트레이스와 스팬
- 트레이스(Traces) 는 "워크플로"의 단일 엔드투엔드 동작을 나타냅니다. 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다:
workflow_name: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation" 또는 "Customer service"trace_id: 트레이스의 고유 ID입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은trace_<32_alphanumeric>여야 합니다group_id: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다disabled: True이면 트레이스가 기록되지 않습니다metadata: 트레이스에 대한 선택적 메타데이터
- 스팬(Spans) 은 시작 및 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다:
started_at및ended_at타임스탬프trace_id: 해당 스팬이 속한 트레이스를 나타냄parent_id: 이 스팬의 부모 스팬(있는 경우)을 가리킴span_data: 스팬에 대한 정보입니다. 예를 들어,AgentSpanData는 에이전트에 대한 정보를,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()로 래핑되어 있으므로, 개별 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다.
트레이스 생성
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()는 기본 프로세서를 사용자 지정 트레이스 프로세서로 교체 할 수 있게 합니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 이를 수행하는TracingProcessor를 포함해야 합니다
OpenAI가 아닌 모델에서의 트레이싱
트레이싱을 비활성화하지 않고도 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화하기 위해 OpenAI API 키를 OpenAI가 아닌 모델과 함께 사용할 수 있습니다.
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 대시보드에서 무료 트레이스를 확인하세요