OpenAI Agents

OpenAI Agents

에이전트 워크플로우를 만들 때 OpenAI Agents를 쓴다면, 한 줄의 코드로 추적·평가를 시작할 수 있어요. OpenAI Agents는 에이전트 스웜, 핸드오프, 도구 사용으로 에이전트 워크플로우를 만드는 가벼운 프레임워크입니다. Confident AI의 OpenTelemetry 네이티브 추적 SDK인 confident-trace에서 init()을 호출하면 에이전트, 도구, 핸드오프, 가드레일이 그대로 유지된 채 추적됩니다.

출처: 문서

본문

개요

OpenAI Agents는 에이전트 스웜, 핸드오프, 도구 사용으로 에이전트 워크플로우를 만드는 가벼운 프레임워크입니다. Confident AI는 한 줄의 코드로 OpenAI Agents 워크플로우를 추적·평가할 수 있게 해 줘요 — Confident AI의 OpenTelemetry 네이티브 추적 SDK인 confident-trace에서 init()을 호출하면, 에이전트·도구·핸드오프·가드레일이 그대로 유지됩니다.

실행 밖의 직접 openai 클라이언트 호출과 도구 안에서 하는 프로바이더 호출은 이 통합이 아니라 OpenAI 통합이 추적해요. 둘 다 같은 init() 호출로 활성화되므로, 두 번 설정할 필요는 없어요.

Runtime Requirements Setup
Python Python 3.10+, openai-agents, confident-trace[openai-agents] extra Call init() before agent runs
TypeScript Node.js 22+, @openai/agents >=0.17.0 <0.18 Call init() and launch your entry point with the preload

자동 계측

의존성 설치

confident-trace를 OpenAI Agents SDK와 함께 설치하는 명령을 실행하세요.

Python

pip install 'confident-trace[openai-agents]' openai-agents

openai-agents extra는 프레임워크가 아니라 Agents SDK용 OpenTelemetry 브리지를 설치해요 — 그래서 openai-agents도 함께 설치하는 거죠. extra 없이는 모델 호출은 여전히 추적되지만, 에이전트·도구·핸드오프 스팬이 없어요.

TypeScript

tsx는 TypeScript 소스를 직접 실행할 때만 필요해요.

npm install confident-trace '@openai/agents@>=0.17.0 <0.18'
npm install -D tsx

yarn add confident-trace '@openai/agents@>=0.17.0 <0.18'
yarn add -D tsx

API 키 설정

Confident AI Project API key를 받아 OpenAI 키와 함께 환경 변수로 설정하세요.

export CONFIDENT_API_KEY="<your-confident-project-key>"
export OPENAI_API_KEY="<your-openai-key>"

EU 리전이거나 자체 호스팅 배포라면, 트레이스가 우리 US 서버로 가지 않도록 CONFIDENT_OTEL_ENDPOINT도 설정하세요 — init() 구성을 참고하세요.

OpenAI Agents 계측

에이전트를 실행하기 전에 init()을 한 번 호출하세요. Agents SDK를 자동으로 감지해 트레이싱을 훅해 줘요 — 코드에 등록할 트레이스 프로세서는 없습니다.

Python

from agents import Agent, Runner
from confident_trace import init, shutdown

init()
agent = Agent(name="Assistant", instructions="You are a helpful assistant")

try:
    result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
    print(result.final_output)
finally:
    shutdown()

TypeScript

import { init } from "confident-trace";
import { Agent, run } from "@openai/agents";

const runtime = init();
const agent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant",
});

try {
  const result = await run(agent, "Write a haiku about recursion in programming.");
  console.log(result.finalOutput);
} finally {
  await runtime.shutdown();
}

TypeScript에는 한 가지가 더 필요합니다. Node가 @openai/agents를 로드할 때 SDK가 훅할 수 있도록 엔트리포인트를 confident-trace/register preload로 실행하세요. init()은 export를, preload는 계측을 처리합니다 — 둘 다 필요해요.

preload 없이 init()을 호출하면 설정 경고가 나오고 스팬이 없어요. 반대로 preload만 있고 init()이 없으면 스팬은 만들어지지만 아무것도 내보내지지 않습니다.

장기 실행 서버에서는 시작 시 init()을 한 번, 정상 종료 시 활성 실행·스트림이 끝난 뒤 shutdown()을 한 번 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

OpenAI Agents 실행

스크립트를 실행해 트레이스를 Confident AI로 보내세요.

Python

python main.py

TypeScript

# Running TypeScript source directly
node --import tsx --import confident-trace/register src/index.ts

# Running compiled JavaScript
node --import confident-trace/register dist/index.js

이걸 평소 시작 명령으로 만들려면 package.json scripts에 추가하세요.

{
  "scripts": {
    "start": "node --import confident-trace/register dist/index.js",
    "dev": "node --import tsx --import confident-trace/register src/index.ts"
  }
}

완료 ✅. Confident AI 프로젝트에서 Observatory를 열어 트레이스와 워크플로우·에이전트·모델 스팬을 확인하세요.

트레이스가 안 보이면 99.99% 프로그램이 스팬을 보낼 기회가 생기기 전에 종료됐기 때문이에요. 종료 전에 반드시 shutdown()(장기 실행 프로세스에선 flush())을 호출하세요 — 트러블슈팅 페이지를 참고하세요.

무엇이 포착되나

통합은 Agents SDK의 네이티브 트레이싱 객체를 스팬으로 변환하고 부모 관계를 유지해서, Observatory의 트레이스 트리가 실행과 일치해요.

Span type Captured data
Workflow The root of each Runner execution
Agent One agent span per agent that participates in the run, including after handoffs
Model (LLM) One LLM span per model request, with messages and token usage
Function tool One tool span per tool execution, with input parameters and output
Handoff, guardrail, turn, custom The remaining SDK span kinds, kept in their original position in the tree

일반·스트리밍 Runner 실행을 모두 지원하며, 에이전트 간 핸드오프나 가드레일이 발동하는 실행도 포함됩니다.

Python

Python 브리지는 OpenInference instrumentor라서, 스팬이 재작성되지 않고 원래 OpenInference 속성으로 전달됩니다 — 어떻게 내보내지는지는 OpenInference 페이지를 참고하세요. 알아 두면 좋은 몇 가지가 있어요.

  • 콘텐츠 정책 — Confident의 콘텐츠 제한·삭제는 이 스팬에 적용되지 않아요. 필요하면 init() 전에 OpenInference의 TraceConfig 또는 환경 설정으로 캡처를 구성하세요.
  • SDK 프로세서 — Agents SDK 자체의 프로세서(기본 exporter 포함)가 설치된 채로 남습니다. RunConfig(tracing_disabled=True)는 여전히 프레임워크 스팬을 꺼요.
  • 프로바이더 스팬 — 실행 밖의 직접 openai 클라이언트 호출과 도구 안의 프로바이더 호출은 자체 Confident LLM 스팬을 받아요.

TypeScript

  • 모델 스팬 — 정규화된 텍스트·도구 메시지와 사용량. 세부 사항은 생성·응답 콜백을 내보내는 모델 구현에 달려 있어요.
  • 핸드오프·가드레일·턴 스팬 — custom으로 타입 지정됨. 네이티브 스팬 유형은 스팬에 계속 사용 가능해요.
  • 제외됨 — 오디오 페이로드, 자격 증명, 임의 트레이스 메타데이터, 오류 텍스트.

Confident의 자체 마스킹 제어에 더해, SDK 자체가 상류에서 모델·도구 콘텐츠를 수집하는 것을 멈추길 원하면 Runner의 traceIncludeSensitiveData: false를 설정하세요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. Runner.run_sync() / run()이 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

Python

from confident_trace import init, trace_context
from agents import Agent, Runner

init()

agent = Agent(name="Assistant", instructions="Be concise.")

with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
    customer_id="customer-7",
):
    result = Runner.run_sync(agent, "Explain OpenTelemetry in one sentence.")

TypeScript

import { init, traceContext } from "confident-trace";
import { Agent, run } from "@openai/agents";

init();

const agent = new Agent({ name: "Assistant", instructions: "Be concise." });

const result = await traceContext(
  {
    tags: ["support"],
    metadata: { release: "2026-09" },
    userId: "user-42",
    customerId: "customer-7",
  },
  () => run(agent, "Explain OpenTelemetry in one sentence."),
);

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

OpenAI Agents 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 OpenAI Agents 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

Python

from confident_trace import init, turn

init()

with turn("support-turn", thread_id="chat-42"):
    context = Runner.run_sync(agent, "Find the relevant account details.")
    answer = Runner.run_sync(agent, f"Summarize these details: {context.final_output}")

TypeScript

import { init, turn } from "confident-trace";

init();

const answer = await turn({ name: "support-turn", threadId: "chat-42" }, async () => {
  const context = await run(agent, "Find the relevant account details.");
  return run(agent, `Summarize these details: ${context.finalOutput}`);
});

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

트러블슈팅

Python

  • 트레이스 없음: 어떤 실행보다 먼저 init()이 실행되고, 프로세스가 shutdown()에 도달해 버퍼링된 스팬이 플러시되는지 확인하세요.
  • 모델 호출은 추적되는데 에이전트·도구·핸드오프 스팬이 없음: pip install 'confident-trace[openai-agents]'로 extra를 설치하고, 실행에 tracing_disabled가 설정되지 않았는지 확인하세요.
  • 중복 스팬: 같은 프로세스에 두 번째 OpenAI Agents instrumentor를 붙이지 마세요.
  • 불완전한 스트림: shutdown() 전에 스트리밍 실행을 소진하거나 취소하세요. 그렇지 않으면 스팬이 최종 출력 없이 끝나요.
  • 스팬이 다른 exporter로 감: init() 전에 자체 tracer 프로바이더로 구성된 instrumentor는 계속 그쪽으로 보내요. 전역 프로바이더를 사용하거나, 같은 것을 init(tracer_provider=...)에 전달하세요. 기존 OpenTelemetry 프로바이더를 참고하세요.

TypeScript

  • 트레이스 없음: 어떤 실행보다 먼저 init()이 실행되고, 시작 명령에 --import confident-trace/register가 포함되며, shutdown()에 도달해 버퍼링된 스팬이 플러시되는지 확인하세요. runtime.getInstrumentationStatus()가 훅이 붙었는지 알려 줘요.
  • 중복 스팬: 같은 프로세스에 두 번째 OpenAI Agents instrumentor를 붙이지 마세요.
  • 불완전한 스트림: shutdown() 전에 스트리밍 실행을 소진하거나 취소하세요. 그렇지 않으면 스팬이 최종 출력 없이 끝나요.

일반적인 문제는 트러블슈팅을 참고하세요.

OpenAI Agents 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. OpenAI Agents의 식별자는 Python에서 "openai_agents", TypeScript에서 "openai-agents"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

Python

from confident_trace import init
init(instrumentations=())
# Use ("openai_agents",) to opt in; omit "openai_agents" to disable it.

TypeScript

import { init } from "confident-trace";
init({ instrumentations: [] });
// Use ["openai-agents"] to opt in; omit "openai-agents" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

Online Evals

트레이스와 스팬이 Confident AI로 수집되는 실시간으로 평가를 돌려 프로덕션 AI 품질을 모니터링하세요.

Threads

다중 턴 에이전트 대화를 스레드로 묶고, 턴 입출력을 설정하며, 전체 대화를 하나의 단위로 평가하세요.

더 알아보기

  • OpenAI — 공식 OpenAI 클라이언트 추적
  • OpenInference — OpenInference 계측기로 스팬 만들기
  • Online Evals — 실시간 트레이스·스팬 평가