A TypeScript package that provides a code execution tool for the AI SDK. Execute Python code in a sandboxed environment using Vercel Sandbox.

pnpm add ai-sdk-tool-code-execution

• A Vercel account with access to Vercel Sandbox (available in Beta on all plans)
• Vercel CLI installed
• A Vercel OIDC token for authentication

From your project directory, link to a new or existing Vercel project:

vercel link

Download your Vercel OIDC token:

vercel env pull

This creates a .env.local file with your VERCEL_OIDC_TOKEN that the SDK uses to authenticate with Vercel Sandbox.

Note: Development tokens expire after 12 hours. Run vercel env pull again when your token expires.

If using Vercel AI Gateway, add your API key to .env.local:

AI_GATEWAY_API_KEY=your_api_key_here

import { executeCode } from "ai-sdk-tool-code-execution";
import { generateText, gateway } from "ai";

const result = await generateText({
  model: gateway("openai/gpt-4o-mini"),
  prompt: "What is 5 + 5 minus 84 cubed?",
  tools: {
    executeCode: executeCode(),
  },
});

console.log(result.text);

The executeCode tool allows your AI agent to run Python 3.13 code in a Vercel Sandbox environment. The agent can perform calculations, data processing, and other computational tasks safely in an isolated environment.

Configure the tool with optional parameters:

type CodeExecutionToolOptions = {
  debug?: boolean;
};

Example with debug enabled:

const result = await generateText({
  model: gateway("openai/gpt-4o-mini"),
  prompt: "Calculate the factorial of 10",
  tools: {
    executeCode: executeCode({ debug: true }),
  },
});

When debug is enabled, you'll see detailed logs of code execution in your terminal.

This package uses Vercel Sandbox to execute Python code in an ephemeral, isolated environment. Each code execution:

1. Creates a new sandbox with Python 3.13 runtime
2. Executes your code using python3 -c
3. Captures stdout, stderr, and exit codes
4. Automatically stops the sandbox after execution

• Python 3.13 runtime: Code runs in Vercel Sandbox's python3.13 image
• Not a REPL: You must use print() to see output. Bare expressions produce no output
• Isolated execution: Each sandbox runs in a secure, ephemeral environment on Amazon Linux 2023
• Authentication required: Requires a valid Vercel OIDC token
• Resource limits: See Vercel Sandbox pricing and limits

If you cannot use VERCEL_OIDC_TOKEN, you can authenticate with access tokens. Set these environment variables:

VERCEL_TEAM_ID=your_team_id_here
VERCEL_PROJECT_ID=your_project_id_here
VERCEL_TOKEN=your_access_token_here

Find your team ID, project ID, and create an access token in your Vercel dashboard.

Test the tool with the included test script:

pnpm test

Build the package:

pnpm build

Update the version in package.json, then publish:

pnpm publish

The package automatically builds before publishing.

.
├── src/
│   ├── tools/
│   │   └── execute-code.ts   # Code execution tool implementation
│   ├── index.ts              # Tool exports
│   └── test.ts               # Test script
├── dist/                     # Build output (generated)
├── package.json
├── tsconfig.json
└── README.md

Track your sandbox usage in the Vercel dashboard:

1. Go to your project
2. Click the AI tab
3. Click Sandboxes to view execution history and URLs

View compute usage across all projects in the Usage tab of your dashboard.

• Vercel Sandbox documentation
• Vercel Sandbox examples
• Vercel Sandbox SDK reference

ISC