트레이싱
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. 동일한 대화에서의 여러 트레이스를 연결하는 데 사용. 예: 채팅 스레드 IDdisabled: 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() 로 래핑하면 됩니다.
fromagentsimportAgent,Runner,traceasyncdefmain():agent=Agent(name="Joke generator",instructions="Tell funny jokes.")withtrace("Joke workflow"):# (1)!first_result=awaitRunner.run(agent,"Tell me a joke")second_result=awaitRunner.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 를 구성해 이 오디오 데이터 캡처를 비활성화할 수 있습니다.
사용자 정의 트레이싱 프로세서
트레이싱의 상위 수준 아키텍처는 다음과 같습니다:
- 초기화 시 전역
TraceProvider를 생성하며, 이는 트레이스를 생성하는 역할을 담당 TraceProvider를BatchTraceProcessor로 구성하여 트레이스/스팬을 배치로BackendSpanExporter에 전송하며, Exporter는 스팬과 트레이스를 OpenAI 백엔드로 배치 전송
기본 설정을 맞춤화하여 다른 백엔드로 전송하거나 추가 백엔드를 사용하거나 Exporter 동작을 수정하려면 두 가지 옵션이 있습니다:
add_trace_processor()는추가 트레이스 프로세서를 등록하여 스팬과 트레이스가 준비되는 즉시 수신하도록 합니다. 이를 통해 OpenAI 백엔드로의 전송과 함께 자체 처리를 수행할 수 있습니다set_trace_processors()는 기본 프로세서를 사용자의 트레이스 프로세서로대체 합니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 이를 수행하는TracingProcessor를 포함해야 합니다
비-OpenAI 모델과의 트레이싱
OpenAI의 API 키를 비-OpenAI 모델과 함께 사용하여 트레이싱을 비활성화하지 않고도 OpenAI Traces 대시보드에서 무료 트레이싱을 사용할 수 있습니다.
importosfromagentsimportset_tracing_export_api_key,Agent,Runnerfromagents.extensions.models.litellm_modelimportLitellmModeltracing_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,)참고
- OpenAI Traces 대시보드에서 무료 트레이스를 확인하세요