openai/openai-agents-js

openai/openai-agents-js

What it does LLM 호출, 도구 사용, 안전 규칙 적용, 에이전트 간 작업 인수인계, 대화 기록 유지가 가능한 멀티 에이전트 워크플로를 구축하기 위한 JavaScript/TypeScript SDK를 제공합니다. OpenAI API와 작동하며 제공자에 구애받지 않습니다.

How it works (core concepts)

• Agent – 지시, 도구, 가드레일, 인수인계를 설정한 LLM.
• Sandbox Agent – 파일 시스템 워크스페이스와 짝을 이루는 에이전트(베타). 오래 실행되는 작업에 사용.
• Realtime Agent – 브라우저에서의 음성 상호작용을 위한 저지연 에이전트.
• Agents as tools / Handoffs – 하위 작업을 다른 에이전트에 위임.
• Tools – 에이전트가 동작을 수행할 수 있는 함수, MCP 또는 호스팅된 도구.
• Guardrails – 입력과 출력에 대한 구성 가능한 안전 검사.
• Human in the loop – 실행 중에 사람을 참여시킬 수 있는 내장 방식.
• Sessions – 대화 기록 자동 관리.
• Tracing – 각 실행을 추적하여 디버깅 및 최적화에 사용.

Key features

• 텍스트, 샌드박스, 실시간 에이전트 유형.
• 도구 통합, 가드레일, 인수인계, 세션, 트레이스.
• Node.js ≥ 22, Deno, Bun에서 동작; Cloudflare Workers 실험적 지원.
• @openai/agents와 zod가 스키마 검증에 필요.

Supported environments

• Node.js 22 이상
• Deno
• Bun
• 실험적: nodejs_compat이 활성화된 Cloudflare Workers

Getting started

npm install @openai/agents zod

Text agent example

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);

Sandbox agent example (macOS/Linux)

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);

Realtime agent example (browser)

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Assistant', instructions: 'You are a helpful assistant.' });
const session = new RealtimeSession(agent);
await session.connect({ apiKey: '<client-api-key>' });

Set OPENAI_API_KEY for text/sandbox agents; for browser realtime agents obtain a short‑lived token from your server.

Limitations (as noted in README)

• Sandbox Agents는 베타 상태이며 Windows에서는 DockerSandboxClient 또는 호스팅된 샌드박스 클라이언트를 사용해야 합니다.
• Realtime agents는 브라우저/WebRTC 설정이 필요합니다.
• Cloudflare Workers 지원은 실험적이며 nodejs_compat이 필요합니다.
• README에는 성능 벤치마크나 설명된 기능을 넘어서는 프로덕션 준비 보장에 대한 언급이 없습니다.