OpenAI Agents SDK TypeScript

빠른 시작

단 몇 분 만에 첫 에이전트를 만들 수 있습니다

시작하기

Text Agent

import { Agent, run } from '@openai/agents';

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

const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);

console.log(result.finalOutput);

Voice Agent

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';

const agent = new RealtimeAgent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
});

// Automatically connects your microphone and audio output in the browser via WebRTC.
const session = new RealtimeSession(agent);
await session.connect({
  apiKey: '<client-api-key>',
});

개요

TypeScript용 OpenAI Agents SDK는 아주 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 해줍니다. 이는 이전 에이전트 실험인 Swarm의 프로덕션급 업그레이드이며, Python 버전도 제공됩니다. Agents SDK는 매우 작은 기본 구성 요소 집합을 제공합니다:

• Agents: instructions와 tools를 갖춘 LLM
• Handoffs: 에이전트가 특정 작업을 다른 에이전트에 위임하도록 허용
• Guardrails: 에이전트 입력을 검증할 수 있도록 지원

TypeScript와 결합하면, 이 기본 구성 요소만으로도 tools와 에이전트 간의 복잡한 관계를 표현할 수 있으며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트의 흐름을 시각화하고 디버그할 수 있도록 하는 기본 제공 트레이싱이 포함되어 있으며, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다.

Agents SDK를 사용하는 이유

SDK의 핵심 설계 원칙은 두 가지입니다:

1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 학습할 수 있도록 기본 구성 요소는 최소화
2. 기본 설정만으로도 충분히 잘 동작하되, 내부 동작을 정확히 원하는 대로 커스터마이즈 가능

SDK의 주요 기능은 다음과 같습니다:

• Agent loop: tools 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 루프를 처리하는 기본 제공 에이전트 루프
• TypeScript 우선: 새로운 추상화 학습 없이, 내장 언어 기능으로 에이전트를 오케스트레이션하고 체이닝
• Handoffs: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능
• Guardrails: 에이전트와 병렬로 입력 검증과 체크를 실행하고, 실패 시 조기 중단
• 함수 도구: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 tool로 전환
• 트레이싱: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, 증류 도구를 사용할 수 있게 하는 기본 제공 트레이싱
• 실시간 에이전트: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 포함한 강력한 음성 에이전트 구축

설치

npm install @openai/agents zod@3

Hello World 예제

Hello World

import { Agent, run } from '@openai/agents';

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

const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

(실행 시 OPENAI_API_KEY 환경 변수를 설정하세요)

export OPENAI_API_KEY=sk-...