OpenAI Agents SDK를 활용한 AI 에이전트 구축

The OpenAI Agents SDK (@openai/agents)는 TypeScript를 사용하여 에이전트형 앱 (agentic apps)을 개발하기 위한 OpenAI의 공식 프레임워크입니다. 이 SDK는 Agent (에이전트), tools (도구), handoffs (핸드오프), guardrails (가드레일), 그리고 run()에 의해 관리되는 **run loop (실행 루프)**라는 소수의 기본 요소 (primitives)를 제공합니다.

이 포스트는 Building AI agents with Vercel AI SDK 포스트에서 다루었던 것과 동일한 **support triage agent (고객 지원 분류 에이전트)**를 구축합니다. 고객 및 인보이스(invoices) 조회, 지식 베이스(knowledge base) 검색, 티켓 생성 또는 에스컬레이션(escalate) 기능을 수행하지만, Vercel의 툴 루프 대신 OpenAI SDK를 사용합니다.

더 낮은 수준의 API 접근 방식은 OpenAI Responses API 포스트를 참조하세요. Vercel AI SDK의 대안(generateText, stopWhen, stepCountIs)에 대해서는 Vercel AI SDK agents post를 참조하세요.

Prerequisites (사전 요구 사항)

• OpenAI 계정
• 생성된 API key
• 결제(billing) 활성화
• Node.js 버전 26
• @openai/agents 및 zod 설치 (npm i @openai/agents zod)
• 환경 변수에 OPENAI_API_KEY 설정

Mental model (멘탈 모델) - turns (턴)와 에이전트 루프

**turn (턴)**은 한 번의 모델 생성 (model generation)을 의미합니다. 해당 턴에서 모델은 다음 중 하나를 수행합니다:

• final output (최종 출력) 반환 (실행 종료)
• tool calls (도구 호출) 반환 (SDK가 이를 실행하고 결과를 가지고 다음 턴을 시작)
• 다른 에이전트로의 handoff (핸드오프) 요청 (제어권이 전환되고, 히스토리가 보존되며, 루프가 계속됨)

고객 지원 분류 에이전트의 전형적인 흐름: 사용자 질문 → 모델이 조회 도구 호출 (get_customer, get_invoice, search_knowledge_base) → 모델이 티켓을 생성하거나 에스컬레이션 수행 → 최종 답변.

maxTurns: 8은 8개의 개별 도구 호출이 아니라, "8턴 (8번의 모델 생성)" 후에 중단함을 의미합니다. 단일 턴에는 여러 개의 병렬 도구 호출이 포함될 수 있습니다.

maxTurns를 생략하면, SDK는 안전을 위해 기본값으로 10을 설정합니다.

Support triage scenario (고객 지원 분류 시나리오)

Example prompt (예시 프롬프트):

고객 cus_1042가 송장 inv_8891에 대해 이중 결제되었다고 말합니다. 어떻게 해야 하나요?

현실적인 체인 (chain):

1. get_customer - 플랜 등급, 열려 있는 티켓 수 확인
2. get_invoice - 금액, 상태, 결제 ID 확인
3. search_knowledge_base - 중복 결제 및 환불 정책 검색
4. create_support_ticket 또는 escalate_to_human - 조치 실행 또는 담당자에게 에스컬레이션 (escalation)

데모는 인메모리 픽스처 (in-memory fixtures: 고객, 송장, 지식 베이스 문서)를 사용하므로 데이터베이스 없이도 스크립트가 실행됩니다.

여러 도구 정의하기 (Defining multiple tools)

tool()과 Zod parameters를 사용하여 도구를 등록합니다. 명확한 description (설명) 값은 모델이 올바른 도구를 선택하는 데 도움을 줍니다.

import { tool } from '@openai/agents';
import { z } from 'zod';

...

결과를 생성하는 쓰기 도구 (write tools)를 추가합니다:

const createSupportTicket = tool({
  name: 'create_support_ticket',
  description: '고객 및 정책 컨텍스트를 수집한 후 지원 티켓을 생성합니다.',
...

execute에서 구조화된 객체 (structured objects)를 반환하세요. SDK는 다음 턴을 위해 이를 도구 결과 (tool results)로 직렬화합니다. 모델이 예외를 던지는 대신 복구할 수 있도록 명시적인 에러 (예: { found: false, error: '...' })를 반환하세요.

에이전트 실행하기 (Running an agent)

지침 (instructions)과 도구 (tools)를 포함하는 Agent를 정의한 다음, run()을 호출합니다:

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

const agent = new Agent({
...

도구 호출 (tool calling)을 지원하는 모델을 사용하세요.

maxTurns - 턴 수 제한하기

maxTurns(n)은 실행이 n번의 턴에 도달하면 중단됩니다. 제어되지 않는 루프와 무제한적인 API 비용 발생을 방지하기 위해 모든 프로덕션 에이전트에 이를 사용하세요. 제한을 초과하면 SDK는 MaxTurnsExceededError를 발생시킵니다.

사용 사례	권장 제한 (cap)
단일 도구 사용 후 답변	2
...

동일한 프롬프트에 대한 엄격한 제한 vs 완화된 제한:

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

// 모델이 더 많은 컨텍스트를 원하더라도 3턴 후에 중단됩니다
...

실행 내용 검사하기 (Inspecting runs)

결과에 포함된 newItems 배열에는 실행 과정에서의 도구 호출 (tool calls), 도구 출력 (tool outputs), 그리고 메시지들이 들어 있습니다. 디버깅을 위해 이를 활용하세요:

const result = await run(agent, prompt, { maxTurns: 8 });

for (const item of result.newItems) {
...

SDK는 트레이스 (traces)를 자동으로 생성합니다. 관련 실행(runs)들을 OpenAI Traces 대시보드에서 그룹화하려면 커스텀 Runner에 workflowName을 설정하세요.

핸드오프 (Handoffs)

멀티 에이전트 워크플로 (multi-agent workflows)를 위해서는 전문 에이전트들을 정의하고, Agent.create()와 handoffs를 사용하여 이들을 연결하세요. 이 포스트의 분류 (triage) 에이전트는 단일 에이전트로 유지되지만, 핸드오프 (handoffs)는 에이전트 간에 권한을 위임하는 SDK의 방식입니다 (마치 케이스를 결제 전문가에게 라우팅하는 것과 유사합니다):

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

const billingAgent = new Agent({
...

실행 (run)이 끝난 후, result.lastAgent를 확인하여 어떤 에이전트가 최종 출력을 생성했는지 확인하세요.

스트리밍 (Streaming)

stream: true를 전달하면 실행이 진행됨에 따라 이벤트를 수신할 수 있습니다:

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

const stream = await run(agent, prompt, { maxTurns: 8, stream: true });
...

텍스트는 점진적으로 스트리밍됩니다. 도구 호출 (tool calls)은 텍스트 세그먼트 사이에 run_item_stream_event 이벤트로 나타납니다.

프로덕션 참고 사항 (Production notes)

• 항상 maxTurns를 설정하세요 - 모니터링 없이 기본 제한 값에만 의존하지 마세요.
• 비용 (Cost) - 각 턴 (turn)은 또 다른 모델 호출입니다. 도구 사용량을 확인하려면 newItems 또는 스트림 이벤트를 검사하세요.
• 도구 오류 (Tool errors) - 모델이 재시도하거나 에스컬레이션 (escalate)해야 하는 경우, 예외를 던지는 (throw) 대신 execute에서 구조화된 에러를 반환하세요.
• 지침 (Instructions) - 정책 규칙은 사용자 프롬프트뿐만 아니라 instructions에 유지하세요.
• 트레이싱 (Tracing) - 멀티 턴 실행 (multi-turn runs)을 디버깅하려면 OpenAI Traces 대시보드를 사용하세요.
• 대안 (Alternatives) - 호스팅된 도구 (웹 검색, 코드 인터프리터 (code interpreter)), MCP 서버, 그리고 샌드박스 에이전트 (sandbox agents)는 공식 문서에서 다룹니다.

데모 (Demo)

각 섹션에 대한 실행 가능한 스크립트는 openai-agents-sdk-demo 폴더에 있습니다. 코드 데모를 통해 접속할 수 있습니다.