타이핑스크립트로 OpenAI 에이전트 SDK 시작하기

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

개발 툴

대상자

• JavaScript/TypeScript 개발자
• 중급~고급 수준의 프론트엔드/풀스택 개발자
• AI 에이전트 개발에 관심 있는 개발자

핵심 요약

• OpenAI Agents SDK는 @openai/agents 패키지로, LLM 기반 AI 에이전트를 구축하는 데 사용됨
• Agent는 instructions, model, tools 3가지 핵심 구성 요소를 포함하며, handoffs로 다른 에이전트와 협업 가능
• Guardrails는 입력/출력 검증을 위한 병렬 실행 기능으로, tool API에 needsApproval 옵션으로 적용 가능
• TypeScript 지원으로 JS 생태계 개발자에게 유리하며, zod 라이브러리와 연동하여 타입 정의 가능

섹션별 세부 요약

1. SDK 소개 및 배경

• OpenAI는 초기 Python 지원에서 TypeScript 버전 추가로 JavaScript 생태계에 적합한 에이전트 프레임워크 제공
• JS/TS 개발자에게 "스택 전환 없이 개발" 가능성을 강조
• @openai/agents 패키지 사용 시 npm install 명령어로 설치 가능

2. Agent 정의 및 구성

• Agent 클래스는 name, instructions, model, tools 속성을 포함
• instructions는 시스템 프롬프트로, model은 o4-mini 등 OpenAI 모델 선택 가능
• 예시:

const agent = new Agent({
  name: 'Haiku Agent',
  instructions: 'Always respond in haiku form.',
  model: 'o4-mini',
})

3. Context 사용법

• run() 메서드에 전달되는 context 객체는 에이전트 상태 및 공유 서비스(예: DB 연결) 저장
• UserContext 인터페이스로 타입 정의 가능
• 예시:

const result = await run(agent, 'Find me new running shoes', {
  context: {
    uid: 'abc',
    isProUser: true,
    fetchPurchases: async () => []
  }
})

4. Handoffs와 협업

• handoff() 함수로 다른 에이전트에 작업 위임 가능
• 예: 결제/환불 전용 에이전트 분리

const triageAgent = Agent.create({
  handoffs: [billingAgent, handoff(refundAgent)]
})

5. Guardrails 기능

• Input Guardrail은 사용자 입력 검증, Output Guardrail은 에이전트 출력 검증
• tool API에서 needsApproval 옵션으로 인간 승인 요청 가능
• 예:

const sendEmail = tool({
  needsApproval: async (_ctx, { subject }) => subject.includes('spam')
})

6. 설치 및 실행 단계

• 사전 요구사항: Node.js, npm/pnpm, OpenAI API 키
• 설치 명령어:

npm init -y
pnpm install @openai/agents zod

• 실행 예시:

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

7. 확장성과 예제

• zod 라이브러리를 사용한 타입 정의 지원
• handoffs를 통해 writer/planner 에이전트와 협업 가능
• Agent Initializr과 Agent Playground를 통해 빠르게 프로토타입 개발 가능

결론

• OpenAI Agents SDK는 guardrails, human-in-the-loop, handoffs 기능으로 안정적이고 확장 가능한 AI 에이전트 개발 가능
• 타겟 개발자: JS/TS 생태계 사용자, 단일 모델 제공자 선호자
• 추천: GitHub 예제 코드와 Agent Initializr 템플릿 활용하여 프로덕션 레벨 백엔드 구축
• 참고 자료: SDK 문서, GitHub 예제, LangGraph vs. LlamaIndex 비교 문서 확인