Run Python code securely with AI SDK and Vercel Sandbox

The ai-sdk-tool-code-execution package gives your AI SDK agent an executeCode tool that runs Python 3.13 inside an isolated Vercel Sandbox. Models reason well but calculate poorly, so letting an agent run real code returns exact answers for math, data processing, and other computational tasks. Each sandbox is a secure, virtual machine that's created for a single run and then destroyed, so the code the model generates executes without touching your production systems.

This guide will walk you through installing the ai-sdk-tool-code-execution package, authenticating with Vercel Sandbox and AI Gateway, and adding the executeCode tool to an AI SDK agent. You'll then test the agent interactively in your terminal without building a UI, and turn on debug logging to inspect each execution.

Before you begin, make sure you have:

• A Vercel account
• Node.js 20 or later
• Vercel CLI installed (npm i -g vercel)
• AI SDK 7. The terminal UI used for testing ships with version seven, so install ai with pnpm add ai@latest if you're on an older release.
• An existing project, or an empty directory where you can run a script.

The executeCode tool runs as part of the AI SDK tool loop. When the model decides a prompt needs computation, it writes Python and calls the tool, which then:

1. Creates a fresh Vercel Sandbox with the python3.13 runtime.
2. Runs the code with python3 -c and captures stdout, stderr, and the exit code.
3. Returns the output to the model so it can finish its answer.
4. Stops the sandbox.

Because the sandbox is isolated and short-lived, code the model generates can't reach your filesystem, environment variables, or other workloads.

Install ai-sdk-tool-code-execution alongside the AI SDK ai package:

pnpm i ai-sdk-tool-code-execution ai

The ai package is the AI SDK core that provides generateText, the agent classes, and the tool loop. The ai-sdk-tool-code-execution package provides the executeCode tool.

The tool authenticates with Vercel Sandbox using a Vercel OIDC token.

Link your directory to a Vercel project, then download the token:

vercel link
vercel env pull

vercel env pull writes a .env.local file containing VERCEL_OIDC_TOKEN. The same token authenticates both the Vercel Sandbox and AI Gateway requests.

Development tokens are valid for 12 hours. When local requests start failing with an authentication error, run vercel env pull again to get a fresh token.

Pass executeCode to generateText to call the tool from a script or a request handler. Set stopWhen so the model can call the tool, read the result, and then write its final answer:

import { generateText, stepCountIs } from 'ai';
import { executeCode } from 'ai-sdk-tool-code-execution';

const { text } = await generateText({
  model: 'anthropic/claude-opus-4.8',
  prompt: 'What is 5 + 5 minus 84 cubed?',
  tools: {
    executeCode: executeCode(),
  },
  stopWhen: stepCountIs(5),
});

console.log(text);

Passing the model as a plain string routes the request through Vercel AI Gateway, which resolves the provider and authenticates with the OIDC token you already pulled. To use a different model, change the string to any supported model.

stepCountIs(5) lets the agent take up to five steps in a single call. Without it, generateText stops after the first tool call and never incorporates the result, so the model can't return a finished answer.

To try the tool interactively without building a UI, run it in the AI SDK terminal UI. The @ai-sdk/tui package renders prompts, streamed responses, and tool cards in your terminal, which is enough for local development and demos.

Install the terminal UI package:

pnpm i @ai-sdk/tui

Create a ToolLoopAgent with the executeCode tool and pass it to runAgentTUI:

import { runAgentTUI } from '@ai-sdk/tui';
import { ToolLoopAgent } from 'ai';
import { executeCode } from 'ai-sdk-tool-code-execution';

const agent = new ToolLoopAgent({
  model: 'anthropic/claude-opus-4.8',
  instructions:
    'You are a Python assistant. When a prompt needs calculation or data processing, write Python and run it with the executeCode tool. Always print results.',
  tools: {
    executeCode: executeCode(),
  },
});

await runAgentTUI({
  title: 'Python code runner',
  agent,
});

ToolLoopAgent manages the tool loop for you, so you don't set stopWhen the way you do for the one-shot generateText call in the previous step.

Run the script with your TypeScript runner. This example uses tsx:

npx tsx tui.ts

The terminal UI opens with a prompt. Type a question, press Enter, and watch the agent write Python, run it in the sandbox, and answer. Exact wording varies by model, but the value is correct:

? Python code runner
> What is 5 + 5 minus 84 cubed?

  executeCode   ran Python in Vercel Sandbox

5 + 5 minus 84 cubed equals -592,694.

Common controls:

• Enter submits a prompt
• Up and Down scroll the transcript
• Esc or Ctrl+C exits.

The executeCode tool creates and stops its own Vercel Sandbox on each call, so leave the sandbox option of runAgentTUI unset. That option is for the separate harness sandboxes that the terminal UI injects as experimental_sandbox, which this tool doesn't use.

Pass debug: true to print each execution to your terminal, including the Python the model generated and the sandbox output. This works whether you call the tool through generateText or a ToolLoopAgent:

tools: {
  executeCode: executeCode({ debug: true }),
},

Debug logging helps when the model's code fails and you want to see the exact stderr the sandbox returned.

The sandbox runs your code non-interactively with python3 -c, so a bare expression produces no output. The model must call print() to return a value. If results come back empty, confirm the generated code prints its result rather than leaving it as a final expression. Stating this in your agent instructions makes empty output less likely.

Both AI Gateway and Vercel Sandbox accept the VERCEL_OIDC_TOKEN from vercel env pull, and that token expires after 12 hours. For automated or shared environments where you can't refresh a personal token, authenticate AI Gateway with an AI_GATEWAY_API_KEY, and Vercel Sandbox with VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID.

Models with strong coding capabilities such as anthropic/claude-opus-4.8 tend to produce more reliable Python for computational prompts. Because switching models is a single string change, store the model ID in an environment variable so you can change it without editing application code.

If the sandbox or model request fails with an authentication error, your OIDC token has likely expired. Run vercel env pull to download a fresh VERCEL_OIDC_TOKEN, then run your script again.

runAgentTUI needs an agent it can run from free-form prompt input, so the agent must not require per-call options or use structured output. The executeCode setup in this guide meets that requirement. For agents that need fixed prompts, call options, or structured output, call agent.generate() or agent.stream() directly instead.

In a generateText call, confirm you set stopWhen: stepCountIs(5) or a higher limit. Without a multi-step stop condition, generateText returns after the first tool call and the model never sees the output. A ToolLoopAgent handles this on its own.

The sandbox returns only what your code prints. Make sure the model's Python uses print(). Enabling debug: true shows the generated code and the raw sandbox output so you can confirm what ran.

• Read the AI SDK terminal UI documentation for display options and more.
• Read the Vercel Sandbox documentation to learn about runtimes, timeouts, and network controls.
• Review Vercel Sandbox pricing and limits before running larger workloads.
• Follow Build AI agents with AI Gateway and AI SDK to build the surrounding agent from scratch.
• See the ai-sdk-tool-code-execution package on npm for the latest options.