Building an agent with OpenAI Agents SDK and Vercel Sandbox

This guide walks through building an agent that analyzes data inside an isolated Vercel Sandbox microVM using the OpenAI Agents SDK. The agent gets shell access to run commands, read files, and return insights, all inside an ephemeral Firecracker microVM with no access to your host filesystem, credentials, or network.

Copy link to headingHow it works

1. Define: create a SandboxAgent with the built-in Shell capability
2. Sandbox: spin up an isolated Vercel Sandbox microVM with workspace files
3. Run: the agent plans and executes shell commands, with all side effects contained in the sandbox

Your orchestration logic (model calls, tool routing) runs locally or on your server. Only the shell commands execute inside the microVM.

Copy link to headingPrerequisites

• Python 3.10+
• A Vercel account with Sandbox access
• An OpenAI API key

Copy link to headingSetup

Create a working directory and set up credentials:

mkdir sandbox-agent-demo && cd sandbox-agent-demo

Create a .env.local file with your Vercel and OpenAI credentials:

OPENAI_API_KEY=sk-... 

VERCEL_TOKEN=your_access_token 
VERCEL_TEAM_ID=team_xxx 
VERCEL_PROJECT_ID=prj_xxx

• VERCEL_TOKEN: create an access token at vercel.com/account/tokens
• VERCEL_TEAM_ID: found under Team Settings > General (starts with team_)
• VERCEL_PROJECT_ID: found under Project Settings > General (starts with prj_)

Install the Python dependencies:

pip install "openai-agents[vercel]" python-dotenv

The vercel extra pulls in the Vercel Python SDK automatically. python-dotenv loads the .env.local credentials into the environment.

Copy link to headingGive an agent shell access

The SandboxAgent class combines a standard agent with sandbox capabilities. The built-in Shell capability gives your agent a tool to run commands inside the sandbox.

Create an agent.py file and load credentials:

touch agent.py

Add the imports at the top of the file:

import asyncio

from dotenv import load_dotenv
load_dotenv(".env.local")

from agents import ModelSettings, Runner
from agents.extensions.sandbox import (
    VercelSandboxClient,
    VercelSandboxClientOptions,
)
from agents.run import RunConfig
from agents.sandbox import (
    Manifest, SandboxAgent, SandboxRunConfig,
)
from agents.sandbox.capabilities import Shell
from agents.sandbox.entries import File

Define a manifest with sample data and create a SandboxAgent with the Shell capability. Setting tool_choice="required" ensures the agent runs commands rather than guessing:

manifest = Manifest(
    entries={
        "sales.csv": File(
            content=(
                b"region,q1_revenue\n"
                b"north,120000\n"
                b"south,95000\n"
                b"east,110000\n"
                b"west,88000\n"
            ),
        ),
    },
)

agent = SandboxAgent(
    name="analyst",
    model="gpt-5.4",
    instructions=(
        "Analyze the workspace files "
        "and answer questions concisely."
    ),
    default_manifest=manifest,
    capabilities=[Shell()],
    model_settings=ModelSettings(
        tool_choice="required",
    ),
)

Create a sandbox session and run the agent. The SandboxRunConfig binds the agent to the session so tool calls execute inside the microVM:

async def main():
    client = VercelSandboxClient()
    session = await client.create(
        manifest=manifest,
        options=VercelSandboxClientOptions(
            timeout_ms=120_000,
        ),
    )

    run_config = RunConfig(
        sandbox=SandboxRunConfig(session=session),
        tracing_disabled=True,
    )

    try:
        async with session:
            result = await Runner.run(
                agent,
                "Which region had the highest "
                "Q1 revenue?",
                run_config=run_config,
            )
            print(result.final_output)
    finally:
        await client.delete(session)

asyncio.run(main())

The agent receives a shell tool and automatically gets instructions about the workspace layout. It can run commands like cat sales.csv or awk one-liners to answer questions.

Copy link to headingConfigure sandbox options

VercelSandboxClientOptions controls how the microVM is provisioned:

options = VercelSandboxClientOptions(
    timeout_ms=270_000,
    runtime="python3.12",
    resources={"vcpus": 2},
    env={"MY_SECRET": "s3cret"},
    exposed_ports=(3000, 8080),
)

• timeout_ms: how long the sandbox stays alive (default 270s)
• runtime: the sandbox runtime, for example python3.12 or node22
• resources: compute resources like {"vcpus": 2} (2 vCPUs = 4GB RAM)
• env: environment variables injected into the sandbox
• exposed_ports: ports forwarded from the sandbox to a public HTTPS endpoint
• workspace_persistence: "tar" (default) archives the workspace as a tarball, "snapshot" uses Vercel's native snapshot API for faster restore

Copy link to headingStream agent responses

Use Runner.run_streamed to see the agent's output as it works, rather than waiting for the full response:

from openai.types.responses import ResponseTextDeltaEvent

stream_result = Runner.run_streamed(
    agent,
    "Summarize the sales data.",
    run_config=run_config,
)

async for event in stream_result.stream_events():
    if (
        event.type == "raw_response_event"
        and isinstance(
            event.data, ResponseTextDeltaEvent
        )
    ):
        print(event.data.delta, end="", flush=True)
print()

Copy link to headingWhy Vercel Sandbox

• Isolation: each agent runs in its own Firecracker microVM with no access to your host machine
• Egress control: restrict outbound traffic to specific domains using network policies, preventing data exfiltration
• Fast boot: sandboxes start in milliseconds, so you can create one per request
• Snapshots: cache expensive setup (package installs, repo clones) and skip it on subsequent runs
• Workspace files: seed the sandbox with data via Manifest before the agent runs
• Built-in capabilities: Shell gives the agent command execution without manual tool wiring

Copy link to headingNext steps

• Deploy the OpenAI Agents SDK template to get a working sandbox agent on Vercel in one click

Copy link to headingResources

• Vercel Sandbox docs: runtime options, networking policies, exposed ports, persistence, and resource limits
• Vercel Python SDK: lower-level sandbox control, blob storage, OIDC tokens, and runtime cache
• OpenAI Agents SDK docs: multi-agent workflows, tools, guardrails, streaming, and tracing