트레이싱

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

내보내기 루프 수명 주기

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

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

예를 들어 Cloudflare Worker 에서는 워커가 종료되기 전에 trace 가 내보내지도록 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());
    }
  },
};

Trace 와 Span

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

기본 트레이싱

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

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

기본적으로 trace 이름은 “Agent workflow”입니다. withTrace를 사용하는 경우 이 이름을 설정할 수 있고, RunConfig.workflowName으로 이름과 기타 속성을 설정할 수도 있습니다.

또한 사용자 정의 trace 프로세서를 설정해 trace 를 다른 대상으로 전송할 수 있습니다(대체 대상 또는 보조 대상).

음성 에이전트 트레이싱

기본 OpenAI Realtime API 와 함께 RealtimeAgent 및 RealtimeSession을 사용하는 경우, RealtimeSession에서 tracingDisabled: true를 사용하거나 OPENAI_AGENTS_DISABLE_TRACING 환경 변수를 사용해 비활성화하지 않는 한 Realtime API 측에서 자동으로 트레이싱이 수행됩니다.

자세한 내용은 음성 에이전트 개요를 확인하세요.

상위 수준 Trace

때로는 여러 번의 run() 호출을 하나의 trace 에 포함하고 싶을 수 있습니다. 이 경우 전체 코드를 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()로 감싸져 있으므로, 개별 실행이 각각 두 개의 trace 를 생성하는 대신 전체 trace 의 일부가 됩니다

Trace 생성

withTrace() 함수를 사용해 trace 를 생성할 수 있습니다. 또는 getGlobalTraceProvider().createTrace()를 사용해 새 trace 를 수동으로 생성한 다음 withTrace()에 전달할 수 있습니다.

현재 trace 는 Node.js AsyncLocalStorage 또는 각 환경의 polyfill 을 통해 추적됩니다. 즉, 동시성 환경에서도 자동으로 작동합니다.

Span 생성

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

Span 은 자동으로 현재 trace 의 일부가 되며, Node.js AsyncLocalStorage 또는 각 환경의 polyfill 을 통해 추적되는 가장 가까운 현재 span 아래에 중첩됩니다.

민감한 데이터

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

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

OpenAI 트레이싱 내보내기 도구

지원되는 서버 런타임에서는 기본 트레이싱 설정이 이미 OpenAI 로 내보내기를 수행합니다. trace 내보내기에 OPENAI_API_KEY와 다른 자격 증명을 사용해야 하는 경우 setTracingExportApiKey()를 사용하세요.

사용자 정의 ingest 동작이 필요하다면 OpenAITracingExporter를 직접 인스턴스화하고 setTraceProcessors(...) 또는 addTraceProcessor(...)로 설치하세요. 이 exporter 는 apiKey, endpoint, organization, project, maxRetries, baseDelay, maxDelay를 지원합니다.

기본 프로세서를 교체한 뒤 나중에 배치 프로세서와 함께 기본 OpenAI exporter 를 복원하려면 setDefaultOpenAITracingExporter()를 호출하세요.

사용자 정의 트레이싱 프로세서

트레이싱의 상위 수준 아키텍처는 다음과 같습니다.

초기화 시 trace 생성 역할을 담당하는 전역 TraceProvider를 만들며, 이는 getGlobalTraceProvider()를 통해 접근할 수 있습니다
TraceProvider는 trace/span 을 배치로 OpenAITracingExporter에 전송하는 BatchTraceProcessor로 구성되며, 이 exporter 는 span 과 trace 를 배치 단위로 OpenAI 백엔드에 내보냅니다

이 기본 설정을 사용자 정의하여 trace 를 다른 또는 추가 백엔드로 보내거나 exporter 동작을 수정하려면 두 가지 옵션이 있습니다.

addTraceProcessor()를 사용하면 준비되는 즉시 trace 와 span 을 수신하는 추가 trace 프로세서를 더할 수 있습니다. 이를 통해 trace 를 OpenAI 백엔드로 보내는 것에 더해 자체 처리를 수행할 수 있습니다
setTraceProcessors()를 사용하면 기본 프로세서를 자신의 trace 프로세서로 대체할 수 있습니다. 이 경우, 이를 수행하는 TracingProcessor를 포함하지 않으면 trace 는 OpenAI 백엔드로 전송되지 않습니다