트레이싱
Agents SDK에는 트레이싱 기능이 내장되어 있어 에이전트 실행 중 발생하는 LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 정의 이벤트까지 포괄적으로 기록합니다. 트레이스 대시보드를 사용하면 개발 및 프로덕션 환경에서 워크플로를 디버깅하고, 시각화하고, 모니터링할 수 있습니다.
내보내기 루프 수명 주기
섹션 제목: “내보내기 루프 수명 주기”지원되는 서버 런타임에서는 트레이스를 일정한 간격으로 내보냅니다. Cloudflare Workers를 비롯한 일부 런타임에서는 트레이싱 자체는 활성화되어 있어도 자동 내보내기 루프를 사용할 수 없습니다. 이러한 환경에서는 요청 수명 주기의 일부로 getGlobalTraceProvider().forceFlush()를 호출하여 런타임이 종료되기 전에 대기 중인 트레이스를 내보내야 합니다.
브라우저에서는 트레이싱이 기본적으로 비활성화되어 있으므로 이 지침이 적용되지 않습니다.
예를 들어 Cloudflare Worker에서는 코드를 try/catch/finally 블록으로 감싸고 forceFlush()를 waitUntil과 함께 사용하여 worker가 종료되기 전에 트레이스가 내보내지도록 해야 합니다.
import { getGlobalTraceProvider } from '@openai/agents';
export default { async fetch(request, env, ctx): Promise<Response> { try { // your agent code here return new Response(`success`); } catch (error) { console.error(error); return new Response('Internal Server Error', { status: 500 }); } finally { // make sure to flush any remaining traces before exiting ctx.waitUntil(getGlobalTraceProvider().forceFlush()); } },};트레이스와 스팬
섹션 제목: “트레이스와 스팬”- 트레이스는 “워크플로”의 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다:
workflow_name: 논리적 워크플로 또는 앱을 나타냅니다. 예를 들어 “코드 생성” 또는 “고객 서비스”입니다.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는 기본적으로 다음을 추적합니다:
- 전체
run()또는Runner.run()은Trace로 감쌉니다. - 각 최상위 runner 호출은
TaskSpan으로 감쌉니다. - 에이전트가 실행될 때마다
AgentSpan으로 감쌉니다. - 에이전트 루프의 각 반복은
TurnSpan으로 감쌉니다. - LLM 생성은
GenerationSpan으로 감쌉니다. - 각 함수 도구 호출은
FunctionSpan으로 감쌉니다. - 가드레일은
GuardrailSpan으로 감쌉니다. - 핸드오프는
HandoffSpan으로 감쌉니다.
기본 계층 구조는 TaskSpan → AgentSpan → TurnSpan이며, 모델 및 도구 작업은 턴 아래에 중첩됩니다. 작업 스팬은 해당 호출의 요청 및 토큰 사용량을 집계합니다. 각 턴 스팬은 턴 번호, 에이전트 이름, 입력, 출력, 캐시된 입력 및 캐시 쓰기 토큰 수를 기록합니다.
작업 및 턴 스팬은 기본적으로 활성화됩니다. 이 추가 계층을 생략하려면 Runner 또는 개별 실행에 tracing: { includeTaskAndTurnSpans: false }를 설정하세요. 실행별 트레이싱 옵션은 runner 수준의 설정보다 우선합니다.
기본적으로 트레이스 이름은 “Agent workflow”입니다. withTrace를 사용할 때 이 이름을 설정하거나, RunConfig.workflowName으로 이름과 기타 속성을 구성할 수 있습니다.
또한 사용자 정의 트레이싱 프로세서를 설정하여 트레이스를 다른 대상으로 보낼 수 있습니다(기존 대상을 대체하거나 보조 대상으로 사용).
음성 에이전트 트레이싱
섹션 제목: “음성 에이전트 트레이싱”기본 OpenAI Realtime API와 함께 RealtimeAgent 및 RealtimeSession을 사용하는 경우, RealtimeSession에서 tracingDisabled: true를 사용하거나 OPENAI_AGENTS_DISABLE_TRACING 환경 변수를 사용하여 비활성화하지 않는 한 Realtime API 측에서 트레이싱이 자동으로 수행됩니다.
자세한 내용은 음성 에이전트 개요를 참고하세요.
상위 수준 트레이스
섹션 제목: “상위 수준 트레이스”여러 run() 호출을 하나의 트레이스에 포함하고 싶을 때가 있습니다. 전체 코드를 withTrace()로 감싸면 됩니다.
import { Agent, run, withTrace } from '@openai/agents';
const agent = new Agent({ name: 'Joke generator', instructions: 'Tell funny jokes.',});
await withTrace('Joke workflow', async () => { const result = await run(agent, 'Tell me a joke'); const secondResult = await run( agent, `Rate this joke: ${result.finalOutput}`, ); console.log(`Joke: ${result.finalOutput}`); console.log(`Rating: ${secondResult.finalOutput}`);});- 두 번의
run호출이withTrace()로 감싸져 있으므로, 개별 실행은 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다.
트레이스 생성
섹션 제목: “트레이스 생성”withTrace() 함수를 사용하여 트레이스를 생성할 수 있습니다. 또는 getGlobalTraceProvider().createTrace()를 사용하여 새 트레이스를 수동으로 생성한 후 withTrace()에 전달할 수 있습니다.
현재 트레이스는 Node.js AsyncLocalStorage 또는 각 환경에 해당하는 폴리필을 통해 추적됩니다. 따라서 동시 실행 환경에서도 자동으로 작동합니다.
스팬 생성
섹션 제목: “스팬 생성”createTaskSpan(), createTurnSpan(), createGenerationSpan(), createFunctionSpan() 등 다양한 create*Span() 메서드를 사용하여 스팬을 생성할 수 있습니다. 이에 대응하는 withTaskSpan() 및 withTurnSpan() 등의 헬퍼는 콜백을 감싸는 스팬을 생성하고 수명 주기를 관리합니다. 일반적으로 스팬을 수동으로 생성할 필요는 없습니다. 사용자 정의 스팬 정보를 추적하기 위한 createCustomSpan() 함수도 제공됩니다.
스팬은 자동으로 현재 트레이스의 일부가 되며, 가장 가까운 현재 스팬 아래에 중첩됩니다. 현재 스팬은 Node.js AsyncLocalStorage 또는 각 환경에 해당하는 폴리필을 통해 추적됩니다.
민감한 데이터
섹션 제목: “민감한 데이터”일부 스팬은 잠재적으로 민감한 데이터를 수집할 수 있습니다.
createGenerationSpan()은 LLM 생성의 입력/출력을 저장하고, createFunctionSpan()은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로, RunConfig.traceIncludeSensitiveData를 통해 해당 데이터의 수집을 비활성화할 수 있습니다.
OpenAI 트레이싱 익스포터
섹션 제목: “OpenAI 트레이싱 익스포터”지원되는 서버 런타임에서는 기본 트레이싱 설정만으로도 OpenAI로 내보내기가 수행됩니다. 트레이스 내보내기에 OPENAI_API_KEY와 다른 인증 정보를 사용해야 하는 경우 setTracingExportApiKey()를 사용하세요.
사용자 정의 수집 동작이 필요한 경우 OpenAITracingExporter를 직접 인스턴스화하고 setTraceProcessors(...) 또는 addTraceProcessor(...)로 등록하세요. 이 익스포터는 apiKey, endpoint, organization, project, maxRetries, baseDelay, maxDelay를 지원합니다.
기본 프로세서를 교체한 후 나중에 배치 프로세서와 함께 기본 OpenAI 익스포터를 복원하려면 setDefaultOpenAITracingExporter()를 호출하세요.
사용자 정의 트레이싱 프로세서
섹션 제목: “사용자 정의 트레이싱 프로세서”트레이싱의 상위 수준 아키텍처는 다음과 같습니다:
- 초기화 시 트레이스 생성을 담당하는 전역
TraceProvider를 생성하며,getGlobalTraceProvider()를 통해 접근할 수 있습니다. TraceProvider에BatchTraceProcessor를 설정합니다. 이 프로세서는 트레이스/스팬을OpenAITracingExporter로 일괄 전송하며, 익스포터는 스팬과 트레이스를 OpenAI 백엔드로 일괄 내보냅니다.
이 기본 설정을 사용자 정의하여 다른 백엔드나 추가 백엔드로 트레이스를 보내거나 익스포터 동작을 수정하려면 두 가지 방법이 있습니다:
addTraceProcessor()를 사용하면 트레이스와 스팬이 준비되는 대로 이를 수신하는 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 트레이스를 OpenAI 백엔드로 전송하는 것 외에 자체적인 처리를 수행할 수 있습니다.setTraceProcessors()를 사용하면 기본 프로세서를 자체 트레이스 프로세서로 교체할 수 있습니다. 이 경우 OpenAI 백엔드로 전송하는TracingProcessor를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다.