openai-agents-js

왜 중요한가

• 실무 기준으로는 실사용 orchestration은 Python뿐 아니라 Node/TS 생태계에서도 중요하다.
• 이 SDK는 JS/TS 쪽에서 Agent, run, handoff, guardrail, realtime 같은 실행 표면을 공식적으로 정리한다.
• Node 22+, Bun, Deno를 겨냥해 웹 서비스나 internal tooling에 붙이기 쉬운 방향을 취한다.

핵심 관찰

• 로컬 Windows 환경에서 repo를 직접 clone했다.
• README 기준 공식 지원 환경은 Node.js 22+, Deno, Bun이었다.
• npm view @openai/agents 기준 최신 버전은 0.8.3이었다.
• repo는 monorepo 구조였고 agents, agents-core, agents-extensions, agents-openai, agents-realtime 패키지로 나뉘어 있었다.
• examples도 agent-patterns, handoffs, memory, realtime, tools, customer-service, research-bot 등으로 넓게 구성돼 있었다.
• parallelization.ts 예제를 보면 Agent, run, withTrace, extractAllTextOutput가 기본 실행 표면으로 보였다.
• 별도 temp 디렉터리에서 npm init -y 후 npm install @openai/agents zod를 실제 실행했고 설치는 정상 완료됐다.
• 이어서 require('@openai/agents')로 export 표면을 확인했더니 Agent, handoff, extractAllTextOutput, defineOutputGuardrail, shellTool, applyPatchTool, realtime 등 주요 API가 실제로 노출됐다.
• new Agent({ name: 'Assistant', instructions: 'Be brief' }) 생성도 정상 동작했다.
• API 키가 없어 실제 run() 호출과 모델 응답은 검증하지 않았다.
• publish tarball은 작지만, 실제 package는 내부 workspace package를 묶는 얇은 façade 구조였다.

해석

openai-agents-js는 JS/TS 환경에서 handoff, guardrail, sessions, tracing, realtime을 포함한 멀티에이전트 orchestration SDK다.

누구에게 도움이 되나

• 프론트엔드/풀스택 팀: Node/TS 프로젝트에 agent workflow를 직접 붙이는 실험
• 플랫폼팀: realtime, tool, handoff가 필요한 JS 기반 orchestration layer 구현
• AI 제품팀: 웹 앱이나 internal bot에 agent execution 레이어 탑재

어디에 바로 써볼 수 있나

• JS/TS 멀티에이전트 orchestration 표면과 Python판 비교 연구
• Node 기반 내부 도구나 웹 서비스에 agent workflow를 붙이는 프로토타입
• OpenClaw 바깥 TS 생태계의 orchestration/guardrail 표면을 비교 참고
• Node/TS 프로젝트에 agent workflow를 직접 붙이는 실험
• realtime, tool, handoff가 필요한 JS 기반 orchestration layer 구현
• 웹 앱이나 internal bot에 agent execution 레이어 탑재

주요 출처

• repo
• README
• docs
• npm

공식 repo / docs

• repo
• README
• docs

주의점

• 실제 운영은 API 비용, tracing, approval, tool safety 설계가 따로 필요하다.
• 오늘 검증은 install/import 표면까지였고, 실제 run 호출은 API 키 없이 확인하지 못했다.
• Node 22 이상 요구사항 때문에 기존 환경에서는 바로 쓰기 어려울 수 있다.
• 따라서 곧바로 production보다 프로토타입과 구조 학습용으로 먼저 보는 편이 안전하다.

다음에 볼 포인트

• 세션 메모리와 장기 메모리의 범위 분리가 더 명시적인 제품 기본값으로 굳어지는지 볼 것.
• skills, orchestration, writable memory를 어떤 정책 경계로 나누는지 비교할 것.