OpenAI Agents SDK TypeScript

빠른 시작

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

Text Agent
Voice 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);

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에는 매우 소수의 기본 구성 요소가 있습니다:

에이전트: instructions 와 tools 를 갖춘 LLM
Agents as tools / 핸드오프: 특정 작업에 대해 에이전트가 다른 에이전트에 위임할 수 있게 함
가드레일: 에이전트 입력을 검증할 수 있게 함

TypeScript와 결합하면, 이 기본 구성 요소들은 도구와 에이전트 간의 복잡한 관계를 표현하기에 충분히 강력하며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버깅하며, 평가하고 심지어 애플리케이션에 맞게 모델을 파인튜닝할 수 있게 해주는 트레이싱이 내장되어 있습니다.

Agents SDK를 사용하는 이유

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

사용할 가치가 있을 만큼 기능은 충분히 제공하되, 학습이 빠르도록 기본 구성 요소는 최소화
기본값만으로도 훌륭하게 작동하지만, 동작을 세밀하게 커스터마이즈 가능

SDK의 핵심 기능:

에이전트 루프: 도구 호출을 처리하고, 결과를 LLM에 다시 보내며, 작업이 완료될 때까지 반복하는 내장 에이전트 루프
TypeScript 우선: 새로운 추상화를 배울 필요 없이 네이티브 TypeScript 언어 기능으로 에이전트를 오케스트레이션하고 체이닝
Agents as tools / 핸드오프: 여러 에이전트 간의 작업 조정과 위임을 위한 강력한 메커니즘
가드레일: 에이전트 실행과 병렬로 입력 검증과 안전 점검을 수행하고, 점검에 실패하면 빠르게 종료
함수 도구: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증을 통해 도구로 전환
MCP 서버 도구 호출: 함수 도구와 동일한 방식으로 작동하는 내장 MCP 서버 도구 통합
세션: 에이전트 루프 내에서 작업 컨텍스트를 유지하는 영속적 메모리 레이어
휴먼인더루프 (HITL): 에이전트 실행 전반에서 사람을 개입시키는 내장 메커니즘
트레이싱: 워크플로를 시각화, 디버그, 모니터링하기 위한 내장 트레이싱과 OpenAI 제품군의 평가, 파인튜닝, 디스틸레이션 도구 지원
실시간 에이전트: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등 기능을 갖춘 강력한 음성 에이전트 구축

설치

npm install @openai/agents zod

SDK는 Zod v4가 필요합니다. npm으로 zod를 설치하면 최신 v4 릴리스를 가져옵니다.

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-...