# Run Python code securely with AI SDK and Vercel Sandbox **Author:** Ben Sabic --- The [ai-sdk-tool-code-execution](https://ai-sdk.dev/resources/tools/code-execution) package gives your AI SDK agent an `executeCode` tool that runs Python 3.13 inside an isolated [Vercel Sandbox](https://vercel.com/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](https://vercel.com/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. ## Prerequisites Before you begin, make sure you have: - A [Vercel account](https://vercel.com/signup) - Node.js 20 or later - [Vercel CLI](https://vercel.com/docs/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. ## How it works 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. ## Steps ### 1\. Install the package Install `ai-sdk-tool-code-execution` alongside the AI SDK `ai` package: 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. ### 2\. Link your project and pull credentials The tool authenticates with Vercel Sandbox using a [Vercel OIDC token](https://vercel.com/docs/sandbox/concepts/authentication#vercel-oidc-token-recommended). 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. ### 3\. Add the executeCode tool to your agent 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](https://vercel.com/ai-gateway/models). `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. ### 4\. Test the agent in your terminal 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: 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. ### 5\. Enable debug logging (optional) 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. ## Best practices ### Use print() to return values from the tool 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. ### Keep credentials current in local development 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`. ### Choose a model that fits the task 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. ## Troubleshooting ### Authentication errors when running locally 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. ### The terminal UI won't start with your agent `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`](http://agent.stream)`()` directly instead. ### The agent returns no computed answer 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. ### Empty output from the tool 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. ## Resources and next steps - Read the [AI SDK terminal UI documentation](https://ai-sdk.dev/docs/agents/terminal-ui) for display options and more. - Read the [Vercel Sandbox documentation](https://vercel.com/docs/sandbox) to learn about runtimes, timeouts, and network controls. - Review [Vercel Sandbox pricing and limits](https://vercel.com/docs/sandbox/pricing) before running larger workloads. - Follow [Build AI agents with AI Gateway and AI SDK](https://vercel.com/kb/guide/ai-gateway-and-ai-sdk) to build the surrounding agent from scratch. - See the [ai-sdk-tool-code-execution package](https://www.npmjs.com/package/ai-sdk-tool-code-execution) on npm for the latest options. --- [View full KB sitemap](/kb/sitemap.md)