Agents SDK에는 내장 트레이싱이 포함되어 있어 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 사용자 지정 이벤트까지.Traces 대시보드를 사용하여 개발 및 운영 환경에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다.

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

트레이스와 스팬

• 트레이스는 "워크플로"의 단일 엔드 투 엔드 작업을 나타냅니다. 스팬으로 구성됩니다. 트레이스는 다음 속성을 가집니다:
  • workflow_name: 논리적 워크플로 또는 앱 이름입니다. 예: "Code generation" 또는 "Customer service"
  • trace_id: 트레이스의 고유 ID 입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은trace_<32_alphanumeric> 이어야 합니다
  • group_id: 선택적 그룹 ID 로, 동일한 대화에서 나온 여러 트레이스를 연결하는 데 사용합니다. 예: 채팅 스레드 ID 를 사용할 수 있습니다
  • disabled: True 인 경우, 트레이스는 기록되지 않습니다
  • metadata: 트레이스에 대한 선택적 메타데이터
• 스팬은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다:
  • 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}")

1. Runner.run 에 대한 두 호출이with trace() 로 래핑되어 있으므로, 각각의 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다.

트레이스 생성

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

1. 권장: 컨텍스트 매니저로 사용합니다. 예:with trace(...) as my_trace. 적절한 시점에 트레이스를 자동으로 시작하고 종료합니다
2. 수동으로trace.start() 와trace.finish() 를 호출할 수도 있습니다

현재 트레이스는 Pythoncontextvar 를 통해 추적됩니다. 이는 자동으로 동시성에서도 동작함을 의미합니다. 트레이스를 수동으로 시작/종료하는 경우, 현재 트레이스를 업데이트하기 위해start()/finish() 에mark_as_current 및reset_current 를 전달해야 합니다.

스팬 생성

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

스팬은 자동으로 현재 트레이스의 일부가 되며, Pythoncontextvar 를 통해 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다.

민감 데이터

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

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 동작을 수정하려면 다음 두 가지 옵션이 있습니다:

1. add_trace_processor() 는 트레이스와 스팬이 준비될 때 이를 수신할추가 트레이스 프로세서를 추가할 수 있게 합니다. 이를 통해 트레이스를 OpenAI 백엔드로 보내는 것과 더불어 자체적인 처리를 수행할 수 있습니다
2. set_trace_processors() 는 기본 프로세서를 사용자 지정 트레이스 프로세서로대체 할 수 있게 합니다. 즉, OpenAI 백엔드로 트레이스를 보내는TracingProcessor 를 포함하지 않는 한 트레이스는 OpenAI 백엔드로 전송되지 않습니다

비 OpenAI 모델과의 트레이싱

트레이싱을 비활성화하지 않고도 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화하기 위해 비 OpenAI 모델과 함께 OpenAI API 키를 사용할 수 있습니다.

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 대시보드에서 무료 트레이스를 확인하세요

외부 트레이싱 프로세서 목록

• Weights & Biases
• Arize-Phoenix
• Future AGI
• MLflow (self-hosted/OSS)
• MLflow (Databricks hosted)
• Braintrust
• Pydantic Logfire
• AgentOps
• Scorecard
• Keywords AI
• LangSmith
• Maxim AI
• Comet Opik
• Langfuse
• Langtrace
• Okahu-Monocle
• Galileo
• Portkey AI
• LangDB AI
• Agenta