OpenAI Agents SDK TypeScript
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을 프로덕션 환경에 적합하게 업그레이드한 SDK이며, Python 버전도 제공됩니다. Agents SDK는 소수의 기본 구성 요소로 이루어져 있습니다:
- 에이전트: 지침과 도구를 갖춘 LLM
- 샌드박스 에이전트: 에이전트에 격리된 파일 시스템 작업 공간, 셸 명령, 파일 편집, 스냅샷, 샌드박스 세션 상태를 결합한 구성 요소
- 음성 에이전트: 도구, 가드레일, 핸드오프, 대화 기록을 활용한 저지연 음성 상호작용을 지원하는 에이전트
- Agents as tools 및 핸드오프: 에이전트가 특정 작업을 다른 에이전트에 위임할 수 있게 하는 구성 요소
- 가드레일: 에이전트에 전달되는 입력을 검증할 수 있게 하는 구성 요소
이러한 기본 구성 요소를 TypeScript와 함께 사용하면 도구와 에이전트 간의 복잡한 관계를 표현하고, 에이전트에 필요한 실제 작업 공간을 제공하며, 많은 학습 부담 없이 실용적인 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 트레이싱 기능이 내장되어 있어 에이전트 흐름을 시각화하고 디버깅할 수 있을 뿐 아니라, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수도 있습니다.
Agents SDK의 장점
섹션 제목: “Agents SDK의 장점”SDK는 두 가지 핵심 설계 원칙을 따릅니다:
- 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 기본 구성 요소를 최소화하여 빠르게 배울 수 있도록 합니다.
- 기본 설정만으로도 잘 작동하면서, 세부 동작을 원하는 대로 맞춤 설정할 수 있도록 합니다.
SDK의 주요 기능은 다음과 같습니다:
- 에이전트 루프: 내장된 에이전트 루프가 도구 호출을 처리하고, 결과를 LLM에 다시 전달하며, 작업이 완료될 때까지 반복합니다.
- 샌드박스 실행: 작업 공간이 필요한 경우, 격리된 파일 시스템 작업 공간, 셸 명령, 파일 편집, 스냅샷, 샌드박스 세션 상태를 갖춘 환경에서 에이전트를 실행합니다.
- 음성 에이전트: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등의 기능으로 저지연 음성 상호작용을 구축합니다.
- TypeScript 우선: 새로운 추상화를 배울 필요 없이 TypeScript의 기본 언어 기능으로 에이전트를 오케스트레이션하고 연결합니다.
- Agents as tools 및 핸드오프: 여러 에이전트 간에 작업을 조율하고 위임하는 강력한 메커니즘을 제공합니다.
- 가드레일: 에이전트 실행과 병렬로 입력 검증 및 안전성 검사를 수행하고, 검사를 통과하지 못하면 즉시 실패 처리합니다.
- 함수 도구: 자동 스키마 생성과 스키마 기반 검증을 통해 모든 TypeScript 함수를 도구로 변환합니다.
- MCP 서버 도구 호출: 내장 연동 기능을 통해 MCP 서버의 도구를 함수 도구와 함께 에이전트에 제공합니다.
- 세션: 에이전트 루프 내에서 작업 컨텍스트를 유지하는 영속적 메모리 계층을 제공합니다.
- 휴먼인더루프 (HITL): 에이전트 실행 과정에 사람이 참여할 수 있는 내장 메커니즘을 제공합니다.
- 트레이싱: 워크플로를 시각화, 디버깅, 모니터링하는 내장 트레이싱을 제공하며, OpenAI의 평가, 파인튜닝, 증류 도구 모음을 지원합니다.
npm install @openai/agents zodSDK에는 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 코드 예제
섹션 제목: “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-...시작 안내
섹션 제목: “시작 안내”먼저 하나의 경로를 선택해 처음부터 끝까지 작동하도록 구현한 다음, 심화 가이드를 살펴보세요.
경로 선택
섹션 제목: “경로 선택”수행하려는 작업은 알지만 어떤 페이지에서 설명하는지 모를 때 이 표를 참고하세요.
| 목표 | 시작 안내 |
|---|---|
| 첫 텍스트 에이전트를 구축하고 한 번의 전체 실행 확인 | 빠른 시작 |
| 함수 도구, 호스티드 툴 또는 agents as tools 추가 | 도구 |
| 에이전트에 격리된 파일 시스템과 셸 작업 공간 제공 | 빠른 시작 |
| 핸드오프와 관리자 방식 오케스트레이션 중 선택 | 에이전트 오케스트레이션 |
| 턴 간 메모리 유지 | 에이전트 실행 및 세션 |
| OpenAI 모델, 웹소켓 전송 또는 OpenAI 외 제공자 사용 | 모델 |
| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토 | 실행 결과 |
| 저지연 음성 에이전트 구축 | 빠른 시작 |