OpenAI Agents SDK TypeScript

OpenAI Agents SDK

작은 수의 기본 구성 요소로 샌드박스, 텍스트, 음성 에이전트를 구축합니다.

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.5',
  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 { 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>',
});

개요

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 / 핸드오프: 여러 에이전트 간 작업을 조정하고 위임하기 위한 강력한 메커니즘
가드레일: 입력 검증과 안전성 검사를 에이전트 실행과 병렬로 수행하고, 검사를 통과하지 못하면 빠르게 실패 처리
함수 도구: 자동 스키마 생성과 Zod 기반 검증을 통해 모든 TypeScript 함수를 도구로 변환
MCP 서버 도구 호출: 함수 도구와 동일한 방식으로 작동하는 기본 제공 MCP 서버 도구 통합
세션: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 지속형 메모리 계층
휴먼인더루프 (HITL): 에이전트 실행 전반에 사람을 참여시키기 위한 기본 제공 메커니즘
트레이싱: 워크플로를 시각화, 디버그, 모니터링하기 위한 기본 제공 트레이싱으로, OpenAI 평가, 미세 조정, 증류 도구 제품군 지원 포함
실시간 에이전트: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등의 기능을 갖춘 강력한 음성 에이전트 구축

설치

npm install @openai/agents zod

SDK는 Zod v4를 필요로 하며, npm으로 zod를 설치하면 최신 v4 릴리스를 가져옵니다.

시작 지점 선택

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

Start with	Use it when	Notes
`@openai/agents`	대부분의 텍스트, 샌드박스 또는 음성 애플리케이션을 구축하는 경우	권장 기본값입니다. OpenAI provider 설정, `@openai/agents/sandbox` 아래의 샌드박스 에이전트 API, `@openai/agents/realtime` 아래의 음성 API가 포함됩니다.
`@openai/agents-realtime`	독립형 Realtime 패키지만 필요한 경우	브라우저 전용 음성 앱이나 더 좁은 패키지 경계를 원하는 경우에 유용합니다.
Lower-level packages (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`)	더 낮은 수준의 조합, 사용자 정의 provider 연결, 또는 특정 통합이 필요한 경우	대부분의 신규 사용자는 구체적인 필요가 생길 때까지는 이를 무시해도 됩니다.

Hello world 예제

에이전트가 파일시스템에서 작업해야 한다면 샌드박스 에이전트로 시작하세요. 워크플로에 샌드박스 작업공간이나 샌드박스 생명주기가 필요하지 않다면 일반 Agent를 계속 사용할 수도 있습니다.

Sandbox Agent
Without Sandbox

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.5',
  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 { 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-...

시작 안내

먼저 한 경로를 선택해 처음부터 끝까지 동작하게 만든 다음, 더 깊이 있는 가이드로 돌아오세요.

Quickstart 첫 번째 텍스트 기반 에이전트를 만들고 SDK의 핵심 워크플로를 배워보세요.

Voice Agents Quickstart 음성 상호작용을 구축하는 경우 Realtime 음성 경로로 시작하세요.

Sandbox agents 에이전트에 파일, 셸 명령, 패치 또는 재개 가능한 샌드박스 상태가 필요하다면 샌드박스 에이전트로 시작하세요.

경로 선택

무엇을 하고 싶은지는 알지만 어떤 페이지에서 설명하는지 모를 때 이 표를 사용하세요.

Goal	Start here
첫 번째 텍스트 에이전트를 만들고 하나의 완전한 실행을 확인	빠른 시작
함수 도구, 호스티드 툴 또는 Agents as tools 추가	도구
에이전트에 격리된 파일시스템 및 셸 작업공간 제공	Sandbox agents
핸드오프와 매니저 스타일 오케스트레이션 중 선택	에이전트 오케스트레이션
여러 턴에 걸쳐 메모리 유지	에이전트 실행 및 세션
OpenAI 모델, websocket 전송 또는 비OpenAI provider 사용	모델
출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토	실행 결과
지연 시간이 낮은 음성 에이전트 구축	빠른 시작