Vercel AI SDK에 공식 Bash 도구 — 에이전트가 샌드박스 안에서 셸 명령으로 파일을 찾고 고쳐요
AI SDK 문서의 'Tools' 페이지에 공식 Bash 도구(@ai-sdk/tool-bash)가 실렸어요. 명령이 어디서 돌지는 샌드박스로 고르고, 아직 '실험(experimental)' 단계예요.
- AI SDK가 직접 만든(first-party) 도구 패키지 @ai-sdk/tool-bash가 나왔어요. experimental_createBashTool로 만든 도구를 tools: { bash }로 넣으면 모델이 Bash 명령으로 파일을 검색 · 분석 · 변환해요.
- 명령이 도는 곳은 샌드박스로 골라요: 메모리 안에서 도는 @ai-sdk/sandbox-just-bash, Vercel Sandbox용 @ai-sdk/sandbox-vercel, 또는 직접 만든 구현. 도구는 어느 쪽에도 직접 의존하지 않아요.
- GitHub 릴리스 기준 1.0.1(10월 20일, UTC)에서 '실험' 표시가 붙었고, 1.0.2(10월 21일)에서 명령별 timeout 옵션이 추가됐어요. Node.js 22.13 이상이 필요해요.
AI SDK로 에이전트를 만들고 있다면 파일 읽기 · 쓰기 · 검색 도구를 하나씩 직접 만드는 대신 Bash 도구 하나로 grep · cat 같은 명령을 맡겨 볼 수 있어요. 결과는 { stdout, stderr, exitCode }로 돌아와서, 실패해도 모델이 다시 시도할 수 있어요.
실제 PC 셸을 열어 주는 게 걱정이라면 메모리 안에서만 도는 just-bash 샌드박스로 먼저 시험해 볼 수 있어요. 문서에 따르면 명령이 어떤 파일에 닿을 수 있는지는 샌드박스가 정해요.
메모 · 표 파일을 샌드박스에 넣고 '요약해서 summary.txt로 저장해 줘'처럼 시키는 흐름이 문서 예제 그대로예요. 개발자와 함께 작은 내부 도구를 만들 때 출발점으로 볼 만해요.
1. Node.js 22.13 이상인지 확인하세요.
2. 설치(문서 그대로): pnpm add ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash
3. 문서의 Usage 예제처럼 createJustBashNetworkSandboxSession()으로 세션을 만들고, session.restricted()에 파일을 넣은 뒤 createBashTool({ sandbox })로 만든 bash를 generateText의 tools: { bash }에 넣으세요.
4. 오래 걸리는 명령이 걱정되면 createBashTool({ sandbox, timeout: 10_000 })처럼 timeout을 주세요(1.0.2부터).
5. Vercel Sandbox에서 돌리려면 문서의 'Vercel Sandbox' 칸 안내를 따르세요.
직접 만든 자동화 에이전트에 '폴더 안 파일 찾기 · 정리' 기능을 붙일 때, 도구를 여러 개 만들기 전에 Bash 도구 하나와 메모리 안 샌드박스로 먼저 시험해 보면 좋을 것 같아요. 다만 아직 실험 단계라 이름(experimental_)과 옵션이 바뀔 수 있으니, 바로 서비스에 넣기보다는 작은 내부 도구부터가 맞아 보여요.
Vercel의 AI SDK 문서 'Tools' 페이지에 Bash 도구(@ai-sdk/tool-bash)가 실렸어요. AI SDK가 직접 만든(first-party) 도구를 @ai-sdk/tool-* 패키지로 따로 설치해 쓰는 방식이에요. 문서는 이 도구들이 함수 호출(function calling)을 지원하는 어떤 모델과도 쓸 수 있다고 적었어요.
무엇을 하나
experimental_createBashTool로 만든 도구를 에이전트(스스로 도구를 써 가며 일하는 AI)에 넣으면, 모델이 Bash 명령으로 파일을 검색 · 분석 · 변환해요. 모델은 { command: string }으로 명령을 보내고 { stdout, stderr, exitCode }를 돌려받아요. 0이 아닌 종료 코드도 그대로 돌려줘서 모델이 실패를 보고 고칠 수 있게 했어요. generateText · streamText · ToolLoopAgent와 함께 써요.
명령은 어디서 도나 — 샌드박스
- @ai-sdk/sandbox-just-bash: 메모리 안(in-memory)에서 도는 환경. 문서 예제가 이걸 써요.
- @ai-sdk/sandbox-vercel: Vercel Sandbox. 이미 만든 Vercel Sandbox를 어댑터로 감싸 넘기거나,
createVercelNetworkSandboxSession()으로 관리형 세션을 만들 수 있어요. - 직접 만든 구현:
Experimental_SandboxSession을 구현해 바로 넘길 수 있어요.
문서에 따르면 도구 자체는 어느 실행 환경에도 직접 의존하지 않고, 명령이 닿을 수 있는 파일 · 쓸 수 있는 프로그램 · 네트워크 · 셸 상태 · 저장 유지는 넘겨준 샌드박스가 정해요. 같은 세션을 쓰는 도구끼리는 파일을 공유하고, 샌드박스를 만들고 지우는 건 호출하는 쪽 몫이에요.
설치와 옵션
문서의 설치 명령은 pnpm add ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash이고, Node.js 22.13 이상이 필요해요. 옵션은 네 가지예요.
sandbox(필수): 명령 실행 · 파일 작업에 쓸 세션workingDirectory: 명령마다 시작할 절대 경로(없으면 만들어요)maxOutputLength: 출력마다 남길 글자 수, 기본 30000. 자르는 건 실행이 끝난 뒤라 실행 메모리 · 시간을 줄이진 않아요.timeout: 명령마다 걸리는 제한 시간(밀리초). 기본값으로는 도구 차원 제한이 없어요. just-bash는 실행 중 취소되면 종료 코드 124를 돌려줘요.
언제 나왔나
GitHub 릴리스 1.0.1(10월 20일, UTC)에서 'Bash 도구를 실험(experimental)으로 표시'가 들어갔어요. 이어 1.0.2(10월 21일)에서 명령별 timeout 옵션이 추가됐어요. 별도의 공식 블로그 글이나 변경 기록(changelog) 글은 아직 찾지 못했어요.
참고로 Vercel은 올해 1월 7일 변경 기록에서 vercel-labs의 별도 패키지 bash-tool(bash · readFile · writeFile 도구)을 소개한 적이 있어요. 이번 건 그것과 별개로 AI SDK 본체 쪽에 들어온 공식 패키지예요.
