Vercel AI SDK: a run_code tool and a sandbox session
@shotcup/ai-sdk connects Shotcup to the Vercel AI SDK in two ways: shotcupTool() is a run_code tool that runs the JavaScript a model writes in a fresh sandbox, and createShotcupSandbox() is a sandbox session over a saved sandbox, for agents that keep files between steps.
The package is not published to npm yet, and neither is the shotcup SDK it builds on. Until they are, a plain tool that calls the REST API does the same job (below). Once they are:
bun add @shotcup/ai-sdk shotcup aiA run_code tool
import { generateText } from "ai";
import { createClient } from "shotcup";
import { shotcupTool } from "@shotcup/ai-sdk";
const shotcup = createClient({ apiKey: process.env.SHOTCUP_API_KEY });
const { text } = await generateText({
model,
tools: { run_code: shotcupTool({ client: shotcup }) },
prompt: "Compute the first 20 Fibonacci numbers and write them to /out/fib.json.",
});The model sends code (run as /main.js) or files with an entry, and may ask for engine switches or private artifact links. A file is text, base64 for binary inputs such as images, or { path, url } to import an https file. The tool answers with the run's status, stdout and stderr (clipped to maxOutputChars, 16,000 characters by default), the exit code, the paths the run changed, the files under /out (inline when small, otherwise by link) and the run's metrics. When the code used a construct the language profile leaves out, hint says what to write instead, and hint.fix carries the repair when it is mechanical, so the model can fix its code in its next step.
shotcupTool() takes these options besides client:
| Option | What it does |
|---|---|
sandboxId | Runs every call in that saved sandbox, so files stay between calls; without it every call is a fresh, disposable run |
description | Replaces the tool's description, which tells the model what the sandbox can do |
engine, fonts | Default engine switches (the model may send its own) and catalogue fonts for every run |
deterministic, timeoutMs | The run's clock and its time limit; runs are deterministic by default |
tools, toolHandlers | Functions the model's code may call, below |
onInterrupt | Receives a paused run's continuation, below |
maxOutputChars | How much stdout, stderr and inline file content goes back to the model |
The AI SDK's abortSignal cancels the run.
Code mode with your own tools
In code mode the model's program calls your tools as functions instead of the model calling them one turn at a time. Give the tool toolHandlers, and the program calls them as tools.<name>(...); dotted names become nested objects. Each call is answered live by your handler while the run is going:
const runCode = shotcupTool({
client: shotcup,
description:
"Runs JavaScript (ES modules, arrow functions, const/let, for...of) in a Shotcup sandbox. " +
"Call await tools.crm.listCustomers({ segment }) and await tools.billing.getInvoices({ since }) " +
"for data; print a short answer and write larger results under /out.",
toolHandlers: {
crm: { listCustomers: async (query) => crm.customers(query) },
billing: { getInvoices: async (query, { signal }) => billing.invoices(query, { signal }) },
},
});The model only knows about these functions if you tell it, in the tool's description or in the system prompt. A handler that declares one more parameter than the script passes gets a context with a signal that aborts when the run ends. The rows your handlers return stay in the sandbox; only what the program prints or writes goes back to the model.
A call to a declaration in tools with approval: true pauses the run instead of calling a handler. Without toolHandlers, a call to any declared tool pauses it too, except the built-in echo. The tool result then has status: "interrupted" and interrupt with the pending calls, so the model sees what is waiting. It never contains the run's continuation token, because the tool result is the model's context. The token goes to your onInterrupt option instead, with the AI SDK's toolCallId, the run's id and a resume function, before the tool result returns:
const runCode = shotcupTool({
client: shotcup,
tools: [{ name: "payments.refund", approval: true }],
onInterrupt: async ({ toolCallId, runId, requests, token }) => {
await approvals.save({ toolCallId, runId, requests, token });
},
});Keep the token out of the conversation. Once someone has decided, shotcup.runs.resume(runId, token, results) continues the run from any process. Without onInterrupt nothing can resume the run, and the tool result tells the model so. Durable code mode explains pausing and resuming.
A sandbox session
createShotcupSandbox() implements the AI SDK's experimental sandbox session (Experimental_SandboxSession) over a Shotcup saved sandbox:
import { createShotcupSandbox } from "@shotcup/ai-sdk";
const sandbox = createShotcupSandbox({ client: shotcup, create: { name: "agent workspace" } });
await sandbox.writeTextFile({ path: "/main.js", content: 'console.log("hi")' });
const { exitCode, stdout } = await sandbox.run({ command: "shotcup run /main.js" });
await sandbox.delete();The session reads and writes the sandbox's files, text or binary, and runs an entry module. A Shotcup sandbox has no shell: run({ command }) accepts shotcup run <entry> (or just the entry's absolute path) with the switches --compat, --ast, --vitest and --canvas, and refuses anything else with an error that says so, so an agent that tries ls or npm test learns what to do instead. A run is one shot: spawn wraps run, and kill only discards the output. run returns the exit code, stdout and stderr; lastRun() returns the whole last run, with a paused run's token, so keep it out of what you hand the model. mounts mounts drives into every run of the session.
Until the package is published
An AI SDK tool that calls the REST API directly:
import { tool } from "ai";
import { z } from "zod";
export const runCode = tool({
description:
"Runs JavaScript (ES modules, arrow functions, const/let, for...of; no npm, no Node APIs besides fs) " +
"in a fresh Shotcup sandbox. Write results under /out.",
inputSchema: z.object({ code: z.string() }),
execute: async ({ code }, { abortSignal }) => {
const response = await fetch("https://shotcup.dev/api/v1/runs", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SHOTCUP_API_KEY}`,
"Content-Type": "application/json",
// optional: tells Shotcup the run came from this guide
"X-Shotcup-Integration": "ai-sdk-guide",
},
body: JSON.stringify({ code }),
signal: abortSignal,
});
const data = await response.json();
if (!response.ok) return { error: data.error };
const { status, error, stdout, stderr, hint, artifacts } = data.run;
return { status, error, stdout, stderr, hint, artifacts: artifacts.map(({ path, url }) => ({ path, url })) };
},
});The quickstart has the rest of the request and the answer.
This page as Markdown: /docs/ai-sdk.md