트레이싱

Agents SDK에는 기본 제공 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트(LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 정의 이벤트 포함)를 포괄적으로 수집합니다. Traces dashboard를 사용하면 개발 및 프로덕션 환경에서 워크플로를 디버그하고, 시각화하고, 모니터링할 수 있습니다.

내보내기 루프 수명 주기

지원되는 서버 런타임에서는 트레이스가 일정 간격으로 내보내집니다. Cloudflare Workers를 포함한 일부 런타임에서는 트레이싱 자체는 활성화되어 있어도 자동 내보내기 루프를 사용할 수 없습니다. 이러한 환경에서는 런타임이 종료되기 전에 대기 중인 트레이스를 내보낼 수 있도록 요청 수명 주기의 일부로 getGlobalTraceProvider().forceFlush()를 호출해야 합니다.

이 지침은 브라우저에는 적용되지 않습니다. 브라우저에서는 기본적으로 트레이싱이 비활성화되어 있기 때문입니다.

예를 들어 Cloudflare Worker에서는 코드를 try/catch/finally 블록으로 감싸고 waitUntil과 함께 forceFlush()를 사용해 워커가 종료되기 전에 트레이스가 내보내지도록 해야 합니다.

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(String(error), { status: 500 });
    } finally {
      // make sure to flush any remaining traces before exiting
      ctx.waitUntil(getGlobalTraceProvider().forceFlush());
    }
  },
};

트레이스와 스팬

Traces는 하나의 “워크플로”에 대한 단일 end-to-end 작업을 나타냅니다. Traces는 Spans로 구성됩니다. Traces는 다음 속성을 가집니다:
- workflow_name: 논리적인 워크플로 또는 앱입니다. 예: “Code generation” 또는 “Customer service”
- trace_id: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 trace_<32_alphanumeric>이어야 합니다
- group_id: 선택적 그룹 ID로, 같은 대화의 여러 트레이스를 연결할 때 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다
- disabled: True이면 트레이스가 기록되지 않습니다
- metadata: 트레이스의 선택적 메타데이터입니다
Spans는 시작 시간과 종료 시간을 갖는 작업을 나타냅니다. Spans는 다음을 가집니다:
- started_at 및 ended_at 타임스탬프
- trace_id: 속한 트레이스를 나타냄
- parent_id: 이 Span의 부모 Span을 가리킴(있는 경우)
- span_data: Span에 대한 정보입니다. 예를 들어 AgentSpanData에는 에이전트 정보가, GenerationSpanData에는 LLM 생성 정보가 포함됩니다

기본 트레이싱

기본적으로 SDK는 다음을 트레이싱합니다:

전체 run() 또는 Runner.run()은 Trace로 감싸집니다
에이전트가 실행될 때마다 AgentSpan으로 감싸집니다
LLM 생성은 GenerationSpan으로 감싸집니다
함수 도구 호출은 각각 FunctionSpan으로 감싸집니다
가드레일은 GuardrailSpan으로 감싸집니다
핸드오프는 HandoffSpan으로 감싸집니다

기본적으로 트레이스 이름은 “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 또는 각 환경의 폴리필을 통해 추적됩니다. 따라서 동시성에서도 자동으로 동작합니다.

스팬 생성

다양한 create*Span()(예: createGenerationSpan(), createFunctionSpan() 등) 메서드로 스팬을 생성할 수 있습니다. 일반적으로는 스팬을 수동으로 만들 필요가 없습니다. 사용자 정의 스팬 정보를 추적하기 위한 createCustomSpan() 함수도 제공됩니다.

스팬은 자동으로 현재 트레이스에 포함되며, Node.js AsyncLocalStorage 또는 각 환경의 폴리필로 추적되는 가장 가까운 현재 스팬 하위에 중첩됩니다.

민감한 데이터

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

createGenerationSpan()은 LLM 생성의 입력/출력을 저장하고, createFunctionSpan()은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로, RunConfig.traceIncludeSensitiveData를 통해 해당 데이터 캡처를 비활성화할 수 있습니다.

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()를 사용하면 기본 프로세서를 사용자 정의 트레이스 프로세서로 교체할 수 있습니다. 이 경우, 이를 수행하는 TracingProcessor를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다