OpenAI Agents SDK TypeScript
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>',});
OpenAI Agents SDK for TypeScript는 아주 적은 추상화로 가벼우면서도 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 해줍니다. 이는 이전의 에이전트 실험작인 Swarm의 프로덕션 수준 업그레이드이며, Python 버전도 제공합니다. Agents SDK는 매우 작은 기본 구성 요소 집합을 가집니다:
- 에이전트: instructions와 tools를 갖춘 LLM
- 핸드오프: 특정 작업을 위해 다른 에이전트에 위임
- 가드레일: 에이전트 입력값을 검증
TypeScript와 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현하고, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트 플로우를 시각화하고 디버깅할 수 있는 트레이싱이 내장되어 있으며, 이를 평가하고 애플리케이션에 맞게 모델을 미세 조정할 수도 있습니다.
Agents SDK를 사용하는 이유
섹션 제목: “Agents SDK를 사용하는 이유”SDK의 설계 원칙은 다음 두 가지입니다:
- 사용할 가치가 있을 만큼 기능은 충분히 제공하되, 학습이 빠를 만큼 기본 구성 요소는 적게 유지
- 기본 설정만으로도 훌륭하게 동작하되, 동작 방식을 원하는 대로 커스터마이즈 가능
주요 기능은 다음과 같습니다:
- 에이전트 루프: 도구 호출, 결과를 LLM에 전달, LLM이 완료될 때까지 반복하는 루프 내장
- TypeScript 우선: 새로운 추상화를 배우지 않고도 언어 기능만으로 에이전트를 오케스트레이션하고 체이닝
- 핸드오프: 여러 에이전트를 조율하고 위임하는 강력한 기능
- 가드레일: 에이전트와 병렬로 입력 검증/체크를 수행하고 실패 시 조기 중단
- 함수 도구: 어떤 TypeScript 함수든 도구로 전환, 스키마 자동 생성과 Zod 기반 검증
- 트레이싱: 워크플로를 시각화·디버그·모니터링하고 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-...