OpenAI Agents SDK 가이드: tracing·span과 민감 데이터 제어

InYourLeague 리서치 · 2026-08-27

Answer in brief

OpenAI Agents SDK는 에이전트 실행을 위한 tracing을 기본 제공하며, trace는 전체 워크플로를, span은 워크플로 내부의 시작·종료 시점이 있는 작업을 나타냅니다. 이 문서는 2026-08-27 기준으로 경계 설정, 백그라운드 내보내기, flush, 사용자 정의 processor, 민감 데이터 설정에 관한 공식 근거의 범위를 설명합니다.

Key facts at a glance

Failure modes and verification

FAQ

OpenAI Agents SDK에서 tracing은 자동으로 활성화됩니까?

예. tracing은 기본적으로 활성화되지만 OPENAI_AGENTS_DISABLE_TRACING=1이나 set_tracing_disabled(True)로 전역 비활성화할 수 있고, RunConfig.tracing_disabled=True로 개별 실행에서 끌 수 있습니다. 자세한 내용은 공식 tracing 가이드를 참조하십시오.

Trace와 span의 차이는 무엇입니까?

Trace는 하나의 논리적인 종단 간 워크플로를 나타냅니다. Span은 그 워크플로 안에서 실행되는 시간 경계가 있는 작업이며, 소속 trace, 선택적인 상위 span, 작업별 데이터를 포함합니다. 구조는 공식 가이드에 설명되어 있습니다.

flush_traces()는 언제 호출해야 합니까?

작업이 끝날 때 버퍼의 기록을 즉시 내보내야 한다면 trace() 컨텍스트가 닫힌 뒤 flush_traces()를 호출합니다. 현재 버퍼에 있는 trace와 span이 모두 내보내질 때까지 차단되므로, 일반적인 백그라운드 내보내기 지연을 허용할 수 있다면 생략할 수 있습니다. 공식 flush 설명을 참조하십시오.

사용자 정의 tracing processor는 무엇을 구현해야 합니까?

TracingProcessor는 trace와 span의 시작·종료 callback, shutdown, force_flush 처리를 구현합니다. API reference에 따르면 메서드는 thread-safe해야 하고, 장시간 차단하지 않아야 하며, 오류를 안전하게 처리해야 합니다.

openai-agents-sdk에서 선택할 수 있는 model ID가 있습니까?

공식 출처는 이 제품에서 선택할 수 있는 model ID를 공개하지 않습니다. tracing 문서는 관찰 가능성 동작을 설명하며 선택 가능한 모델 식별자를 제시하지 않으므로, 공개된 제품 범위는 공식 문서에서 확인해야 합니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

직접 답변

OpenAI Agents SDK는 에이전트 실행을 기록하는 built-in tracing을 제공하며, tracing은 기본적으로 활성화됩니다. trace는 하나의 논리적인 종단 간 워크플로를 나타내고, trace에 속한 span은 모델 생성, 도구 호출, handoff, guardrail처럼 시작 시각과 종료 시각이 있는 개별 작업을 나타냅니다. 기본 processor는 버퍼에 쌓인 기록을 백그라운드에서 내보내며, 작업 단위가 끝날 때 즉시 전달을 보장해야 한다면 trace를 닫은 뒤 flush_traces()를 호출할 수 있습니다. 이 문서는 2026-08-27 기준으로 검증했습니다.

핵심 경계

기본 동작에서는 전체 Runner.run(), Runner.run_sync(), Runner.run_streamed() 실행이 trace()로 감싸집니다. 각 runner 호출에는 task_span()이, 각 모델 turn에는 turn_span()이 생성됩니다. 에이전트 실행, LLM generation, function tool 호출, guardrail, handoff, 음성 전사, 음성 출력, 관련 음성 그룹에도 해당 span이 생성됩니다. 기본 trace 이름은 Agent workflow입니다. RunConfig(tracing={"include_task_and_turn_spans": False})를 사용하면 자동 task span과 turn span을 생략할 수 있지만, agent, generation, function, guardrail, handoff, custom span은 계속 기록됩니다. 자세한 범위는 공식 tracing 가이드에서 확인할 수 있습니다.

권장 구성 순서

1. 먼저 애플리케이션에서 하나의 논리적 워크플로가 어디에서 시작하고 끝나는지 정합니다. 기본 runner 단위가 원하는 경계와 일치하면 기본 trace를 사용합니다. 여러 runner 호출이 하나의 상위 업무를 구성한다면 전체 호출을 명시적인 trace() 컨텍스트로 감싸 하나의 trace에 포함합니다.
2. task와 turn 수준의 세부 구조가 디버깅과 관찰에 필요한지 판단합니다. 일반적인 계층이 유용하면 기본값을 유지하고, 더 간결한 계층이 필요할 때만 include_task_and_turn_spans를 False로 설정합니다. 이 설정은 모든 span을 끄는 옵션이 아니라 자동 task span과 turn span만 줄이는 설정입니다.
3. 약간의 대시보드 지연을 허용할 수 있다면 기본 백그라운드 내보내기를 사용합니다. BatchTraceProcessor는 몇 초마다 내보내고, 메모리 큐가 크기 trigger에 도달하면 더 일찍 내보내며, 프로세스가 종료될 때 최종 flush도 수행합니다. 따라서 장시간 실행되는 Celery, RQ, Dramatiq 또는 FastAPI background task에서는 일반적으로 추가 코드 없이도 기록이 내보내지지만, 각 job이 끝난 직후 대시보드에 나타난다고 단정해서는 안 됩니다.
4. 작업 종료 시점의 즉시 전달이 필요하면 trace() 컨텍스트가 종료된 뒤 flush_traces()를 호출합니다. flush_traces()는 현재 버퍼에 있는 trace와 span의 내보내기가 끝날 때까지 차단됩니다. 아직 구성 중인 trace를 flush하지 않도록 trace가 닫힌 이후에 호출해야 합니다. 기본 내보내기 지연을 허용할 수 있다면 이 호출은 생략할 수 있습니다.
5. 다른 목적지에도 tracing 데이터를 보내거나 기본 목적지를 대체해야 한다면 사용자 정의 TracingProcessor를 추가합니다. 공식 API reference에 따라 on_trace_start, on_trace_end, on_span_start, on_span_end, shutdown, force_flush를 구현합니다. 모든 메서드는 thread-safe해야 하며, 오랫동안 차단하지 않아야 하고, processor 오류가 에이전트 실행을 방해하지 않도록 처리해야 합니다.

민감 데이터 제어

제공된 공식 발췌문에서 확인되는 제어는 tracing 비활성화와 ZDR 제한입니다. 전역 비활성화에는 OPENAI_AGENTS_DISABLE_TRACING=1 또는 set_tracing_disabled(True)를 사용할 수 있고, 개별 실행에는 RunConfig.tracing_disabled=True를 사용할 수 있습니다. 또한 OpenAI API를 Zero Data Retention 정책으로 사용하는 조직에서는 tracing을 사용할 수 없다고 명시되어 있습니다.

공식 가이드에는 Sensitive data 절이 존재하지만, 제공된 발췌문은 추가적인 민감 데이터 설정의 정확한 이름이나 동작을 제시하지 않습니다. 따라서 이 문서는 입력, 출력 또는 특정 span payload를 선택적으로 포함하거나 제외하는 별도 옵션을 추정하지 않습니다. 실제 설정 전에 최신 공식 tracing 가이드에서 지원되는 설정과 데이터 처리 범위를 다시 확인해야 합니다.

구성 점검표

• 논리적인 trace 경계와 의미 있는 workflow_name을 정의했습니다.
• 동일한 대화처럼 관련 trace를 연결해야 할 때만 group_id를 사용했습니다.
• task span과 turn span을 유지할지 결정했습니다.
• 즉시 내보내기가 필요할 때 flush_traces()를 trace 컨텍스트 뒤에 배치했습니다.
• 사용자 정의 processor 메서드가 thread-safe이고, 장시간 차단하지 않으며, 오류를 안전하게 처리하는지 확인했습니다.
• 민감 데이터 요구사항과 ZDR 호환성을 공식 문서에 대조했습니다.
• 전역 또는 개별 실행 단위에서 tracing을 비활성화해야 하는지 결정했습니다.

모델 참고사항

공식 출처는 이 제품에서 선택할 수 있는 model ID를 공개하지 않습니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.