OpenAI Agents SDK 타입스크립트

OpenAI Agents SDK

소수의 기본 구성요소로 텍스트, 샌드박스, 실시간 에이전트를 구축할 수 있습니다.

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 { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } },
);

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 함수를 도구로 변환합니다.
MCP 서버 도구 호출: 함수 도구와 함께 MCP 서버의 도구를 에이전트에 노출하는 연동 기능이 내장되어 있습니다.
세션: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 영구 메모리 계층입니다.
휴먼인더루프 (HITL): 여러 에이전트 실행 과정에 사람을 참여시키는 메커니즘이 내장되어 있습니다.
트레이싱: 워크플로를 시각화, 디버깅, 모니터링하는 트레이싱 기능이 내장되어 있으며, OpenAI의 평가, 파인튜닝, 증류 도구 모음을 지원합니다.

설치

npm install @openai/agents zod

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

시작 지점 선택

처음 사용하는 대부분의 사용자는 다음 진입점 중 하나만 선택하면 됩니다.

시작 항목	사용 시점	참고
`@openai/agents`	대부분의 텍스트, 샌드박스 또는 실시간 애플리케이션을 구축하는 경우	권장되는 기본 선택입니다. OpenAI 프로바이더 설정, `@openai/agents/sandbox`의 샌드박스 에이전트 API, `@openai/agents/realtime`의 실시간 API가 포함됩니다.
`@openai/agents-realtime`	독립형 Realtime 패키지만 필요한 경우	브라우저 전용 실시간 앱이나 더 좁은 패키지 경계가 필요한 경우에 유용합니다.
하위 수준 패키지(`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`)	하위 수준 구성, 사용자 지정 프로바이더 연결 또는 특정 연동이 필요한 경우	대부분의 신규 사용자는 구체적인 필요가 생길 때까지 이러한 패키지를 무시해도 됩니다.

Hello World 예제

텍스트 워크플로에는 일반 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);

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

import { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } },
);

console.log(result.finalOutput);

(이 코드를 실행하려면 OPENAI_API_KEY 환경 변수를 설정해야 합니다)

export OPENAI_API_KEY=sk-...

시작 지점

먼저 경로 하나를 선택하여 처음부터 끝까지 작동하도록 만든 다음, 더 자세한 가이드로 돌아오세요.

빠른 시작 첫 번째 텍스트 기반 에이전트를 구축하고 SDK의 핵심 워크플로를 학습합니다.

빠른 시작 에이전트에 파일, 셸 명령, 패치 또는 재개 가능한 샌드박스 상태가 필요한 경우 샌드박스 에이전트를 시작합니다.

빠른 시작 음성 상호작용을 구축하는 경우 실시간 에이전트로 시작합니다.

경로 선택

수행하려는 작업은 알고 있지만 이를 설명하는 페이지를 모를 때 다음 표를 사용하세요.

목표	시작 지점
첫 번째 텍스트 에이전트를 구축하고 전체 실행 과정 확인	빠른 시작
함수 도구, 호스티드 툴 또는 Agents as tools 추가	도구
에이전트에 격리된 파일 시스템 및 셸 작업공간 제공	빠른 시작
핸드오프와 관리자 방식의 오케스트레이션 중 선택	에이전트 오케스트레이션
턴 간 메모리 유지	에이전트 실행 및 세션
OpenAI 모델, WebSocket 전송 또는 OpenAI 이외의 프로바이더 사용	모델
출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토	실행 결과
지연 시간이 짧은 실시간 에이전트 구축	빠른 시작