트레이싱

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

내보내기 루프 라이프사이클

대부분의 환경에서는 트레이스가 정기적으로 자동 내보내기됩니다. 브라우저 또는 Cloudflare Workers에서는 이 기능이 기본적으로 비활성화됩니다. 대기열에 너무 많은 트레이스가 쌓이면 내보내기되지만, 정기적으로 내보내기되지는 않습니다. 대신 코드 라이프사이클의 일부로 getGlobalTraceProvider().forceFlush() 를 사용해 수동으로 트레이스를 내보내야 합니다.

예를 들어, Cloudflare Worker에서는 코드를 try/catch/finally 블록으로 감싸고, 종료 전에 트레이스가 내보내지도록 waitUntil 과 함께 강제 플러시를 사용해야 합니다.

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

기본 트레이싱

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

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

기본적으로 트레이스 이름은 “에이전트 워크플로”입니다. 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 를 통해 해당 데이터 캡처를 비활성화할 수 있습니다.

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

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

초기화 시 전역 TraceProvider 를 생성합니다. 이는 트레이스 생성을 담당하며 getGlobalTraceProvider() 를 통해 접근할 수 있습니다.
TraceProvider 를 BatchTraceProcessor 로 구성하여, 배치로 트레이스/스팬을 OpenAITracingExporter 에 전송하고, 이는 배치로 OpenAI 백엔드에 스팬과 트레이스를 내보냅니다.

기본 설정을 사용자 지정하여 다른 백엔드로 트레이스를 전송하거나 추가 백엔드를 사용하거나, 익스포터 동작을 변경하려면 다음 두 가지 옵션이 있습니다:

addTraceProcessor() 는 트레이스와 스팬이 준비될 때 이를 수신할 수 있는 추가 트레이스 프로세서를 추가할 수 있게 합니다. 이를 통해 OpenAI 백엔드로 트레이스를 보내는 것과 더불어 자체 처리를 수행할 수 있습니다.
setTraceProcessors() 는 기본 프로세서를 사용자 지정 트레이스 프로세서로 교체 할 수 있게 합니다. 이 경우 OpenAI 백엔드로 트레이스가 전송되지 않으며, 그렇게 하려면 해당 작업을 수행하는 TracingProcessor 를 포함해야 합니다.