--- title: Run Python code securely with AI SDK and Vercel Sandbox description: Add an `executeCode` tool to your AI SDK agent with the `ai-sdk-tool-code-execution` package to run Python 3.13 inside an isolated Vercel Sandbox. url: "https://vercel.com/kb/guide/python-ai-sdk-vercel-sandbox" published: 2026-06-29 last_updated: 2026-06-29 authors: Ben Sabic install_vercel_plugin: npx plugins add vercel/vercel-plugin --- 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: **pnpm** ```bash pnpm i ai-sdk-tool-code-execution ai ``` **npm** ```bash npm i ai-sdk-tool-code-execution ai ``` **yarn** ```bash yarn add ai-sdk-tool-code-execution ai ``` **bun** ```bash bun add 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. ### 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: ```bash 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: ```typescript 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: **pnpm** ```bash pnpm i @ai-sdk/tui ``` **npm** ```bash npm i @ai-sdk/tui ``` **yarn** ```bash yarn add @ai-sdk/tui ``` **bun** ```bash bun add @ai-sdk/tui ``` Create a `ToolLoopAgent` with the `executeCode` tool and pass it to `runAgentTUI`: ```typescript 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`: ```bash 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: ```plaintext ? 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`: ```typescript 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. ## More Vercel Sandbox guides - [Private enterprise agents on Vercel](/kb/guide/private-enterprise-agents-vercel): Design private enterprise agents that call internal APIs and databases with Vercel Functions, Secure Compute, AI Gateway, Workflows, and Vercel Connect. - [Run recurring security reviews with deepsec on Vercel](/kb/guide/deepsec-reviews-on-vercel): Learn how to run periodic security scans on your code with deepsec. Set up deepsec to review GitHub repositories and deliver findings to GitHub and Slack using Vercel Connect, Workflows, Sandbox, and AI Gateway. - [How Vercel Sandbox duration and persistence work](/kb/guide/vercel-sandbox-duration-and-persistence): Session duration and persistence are two separate controls in Vercel Sandbox. The timeout option keeps a single run alive for up to 24 hours, while snapshots and persistent sandboxes carry state across runs for long-running agents and pipelines.