OpenAI Agents SDK TypeScript

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는 소수의 기본 구성 요소로 이루어져 있습니다.

에이전트: 지침과 도구를 갖춘 LLM
샌드박스 에이전트: 에이전트에 격리된 파일 시스템 작업 공간, 셸 명령어, 파일 편집, 스냅샷, 샌드박스 세션 상태를 결합
실시간 에이전트: 도구, 가드레일, 핸드오프, 대화 기록을 활용하는 저지연 음성 상호작용을 지원
Agents as tools / 핸드오프: 에이전트가 특정 작업을 다른 에이전트에 위임할 수 있도록 지원
가드레일: 에이전트 입력의 유효성을 검사

TypeScript와 결합된 이러한 기본 구성 요소는 도구와 에이전트 간의 복잡한 관계를 표현하고, 필요할 때 에이전트에 실제 작업 공간을 제공하며, 가파른 학습 곡선 없이 실용적인 애플리케이션을 구축할 수 있을 만큼 강력합니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버깅하며 평가할 수 있는 기본 제공 트레이싱이 포함되어 있으며, 애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다.

Agents SDK 사용 이유

SDK는 다음 두 가지 핵심 설계 원칙을 따릅니다.

사용할 가치가 있을 만큼 충분한 기능을 제공하면서도 빠르게 배울 수 있도록 기본 구성 요소를 최소화합니다.
별도 설정 없이도 원활하게 작동하지만, 동작을 원하는 대로 세밀하게 맞춤 설정할 수 있습니다.

SDK의 주요 기능은 다음과 같습니다.

에이전트 루프: 도구 호출을 처리하고 결과를 LLM에 다시 전달하며 작업이 완료될 때까지 계속 실행하는 기본 제공 에이전트 루프
샌드박스 실행: 작업 공간이 필요한 경우 격리된 파일 시스템 작업 공간, 셸 명령어, 파일 편집, 스냅샷, 샌드박스 세션 상태를 활용하여 에이전트 실행
실시간 에이전트: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등의 기능을 활용하여 저지연 음성 상호작용 구축
TypeScript 우선: 새로운 추상화를 배울 필요 없이 TypeScript의 기본 언어 기능을 사용하여 에이전트를 오케스트레이션하고 연결
Agents as tools / 핸드오프: 여러 에이전트 간의 작업을 조율하고 위임하는 강력한 메커니즘
가드레일: 에이전트 실행과 병렬로 입력 유효성 검사와 안전성 검사를 수행하고, 검사를 통과하지 못하면 즉시 실패 처리
함수 도구: 자동 스키마 생성과 Zod 기반 유효성 검사를 통해 모든 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 외 프로바이더 사용	모델
출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토	실행 결과
저지연 실시간 에이전트 구축	빠른 시작