신뢰할 수 없는 JavaScript과 TypeScript 코드를 애플리케이션 접근 권한 없이 실행하고, 사람의 승인이 필요한 시점에 실행을 일시 중단할 수 있습니다.
에이전트가 도구를 조율하고 결과를 처리하기 위해 TypeScript 프로그램을 작성하는 일이 점점 늘고 있습니다. 이런 프로그램이 실제 애플리케이션과 맞닿는 순간, 어떤 단계는 인증이 필요하고 어떤 단계는 사람의 승인을 거쳐야 합니다.
eval로 해당 코드를 실행하면 주변 애플리케이션과 동일한 접근 권한을 갖게 됩니다. 시크릿이나 내부 서비스까지 그대로 노출되고, 이 경계 지점에서 실행을 일시 중단할 방법도 마땅치 않습니다.
오늘 Run SDK를 공개합니다. 신뢰할 수 없는 JavaScript와 TypeScript 코드를 애플리케이션이나 시스템에 직접 접근하지 못하도록 격리된 환경에서 실행하기 위한 패키지입니다. 애플리케이션은 제한된 호스트 함수만 외부에 노출하고, 인증이나 사람의 승인(human-in-the-loop)이 필요한 시점에 실행을 중단할 수 있습니다. 승인 여부가 결정되면 완료된 작업은 반복하지 않고 이어서 실행됩니다.
Run SDK는 워커 스레드 내부에서 새로운 QuickJS 컨텍스트를 생성하고, 그 안에서 JavaScript 또는 타입이 제거된 TypeScript를 평가합니다. Node.js나 네트워크로의 직접 경로는 없습니다.
애플리케이션은 hostFunctions를 통해 선택한 작업만 외부에 노출합니다. 이 함수들은 샌드박스 내부에서 전역으로 호출 가능한 일반 함수입니다.
이 예시에서 생성된 프로그램은 store.listOrders()만 인식합니다. 데이터베이스 클라이언트와 자격 증명은 애플리케이션 안에 그대로 유지됩니다.
함수 호출은 직렬화를 통해 샌드박스 경계를 넘습니다. 호스트 함수는 프로미스를 반환할 수 있으므로, 기존 서비스 클라이언트를 샌드박스에 넘기지 않고 이 인터페이스 뒤에 그대로 둘 수 있습니다.
플레이그라운드에서 직접 체험해볼 수 있습니다. 플레이그라운드에서 실행한 코드는 해당 페이지의 호스트 함수에만 접근할 수 있습니다.
Run SDK는 AI SDK의 코드 모드 도구 실행을 내부적으로 구동하는 모듈입니다. 에이전트에게 프로그램을 주면 작업 단위가 달라집니다. 모델이 한 번 응답할 때 여러 호출과 그 결과를 연결하는 로직을 한꺼번에 기술할 수 있습니다.
두 요청은 동시에 처리되고, 인보이스 필터링은 프로그램 내에서 로컬로 처리됩니다. 애플리케이션으로 돌아오는 것은 필요한 결과뿐입니다.
여러 내부 서비스를 넘나드는 에이전트에 특히 잘 맞습니다. 리서치 에이전트는 답하기 전에 검색 결과를 통합할 수 있고, 고객 지원 에이전트는 전체 결제 응답을 컨텍스트에 담지 않고도 계정을 조회할 수 있습니다.
같은 패키지로 코드 인터프리터나 고객이 직접 변환 로직을 정의하는 제품 기능도 구현할 수 있습니다. 어느 경우든 사용 가능한 데이터와 작업은 애플리케이션이 결정합니다.
호스트 함수는 주문 환불처럼 제품의 특정 행동에 대응할 때 가장 효과적입니다. orders.refund(id)를 노출하면 사용자와 주문을 확인할 명확한 지점이 생깁니다. 범용 요청 함수로 처리하면 이런 권한을 추론하기가 훨씬 어려워집니다.
인보이스를 조회하는 것과 환불을 실행하는 것은 성격이 다릅니다. 생성된 코드가 민감한 작업에 도달하면, 호스트 함수가 실행을 중단할 수 있습니다.
실행이 중단되면 결과에 서명된 토큰이 포함됩니다. 애플리케이션은 이 토큰을 승인 요청과 함께 저장해 두었다가, 결정이 도착하면 실행을 재개하는 데 사용할 수 있습니다.
재개 시에는 프로그램을 다시 실행하지만, 이미 완료된 호스트 함수 호출은 기록된 결과를 그대로 사용합니다. 중단 전에 완료된 호스트 함수 작업은 다시 실행되지 않으며, 중단된 함수는 승인 결과를 받아 그 시점부터 계속 진행됩니다.
이 메커니즘은 워크플로가 인증을 기다려야 할 때도 동일하게 작동합니다. 대기하는 동안의 처리는 애플리케이션이 담당하며, 워커는 계속 살아있지 않아도 됩니다.
샌드박스라도 무한 루프를 돌거나 지나치게 큰 결과를 만들어내는 코드에 대비해야 합니다. createRunner()로 공통 제한을 설정할 수 있습니다.
제한은 실행 단위로도 설정할 수 있습니다. 기본값은 QuickJS 힙과 호스트 경계를 오가는 값을 기준으로 하며, 애플리케이션은 워크로드에 맞게 더 엄격하게 조정할 수 있습니다.
각 호출마다 새로운 QuickJS 컨텍스트가 생성됩니다. 동적 평가는 비활성화되고 내장 프로토타입은 보호됩니다. 이 경계는 생성된 프로그램에 적용되며, 호스트 함수는 신뢰할 수 있는 애플리케이션 코드로 남아 자체적인 인가 확인을 수행해야 합니다.
Run SDK는 애플리케이션 내부에서 JavaScript 연산을 처리하는 용도로 설계되었습니다. 운영 체제, 패키지 설치, 프로세스 수준 격리가 필요한 워크로드에는 Vercel Sandbox를 사용하세요.
이 런타임의 첫 번째 버전은 just-bash 내부에 js-exec로 존재했으며, QuickJS를 기반으로 동작했습니다. 에이전트가 셸의 가상 파일시스템과 명령어 세트를 대상으로 TypeScript를 작성할 수 있도록 해주었습니다.
이 레이어를 Run SDK로 분리하고, Node.js 형태의 환경을 애플리케이션이 정의하는 호스트 함수로 대체했습니다. 기반 메커니즘은 eve에서 검증했으며, 에이전트가 생성한 TypeScript를 실제 도구에 실행하는 데 활용했습니다. 현재는 AI SDK의 코드 모드를 구동하고 있으며, 기존 AI SDK 도구들이 호스트 함수로 매핑되고 Run SDK가 샌드박스 실행을 담당합니다.
Run SDK는 Node.js 22.13 이상과 Bun을 지원합니다. 로컬 개발 환경에 pnpm 또는 다른 패키지 매니저가 설치되어 있어야 합니다.
