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.

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.

• Python 3.11+
• The Vercel CLI installed (npm i -g vercel)
• A Vercel account with Sandbox access
• An OpenAI API key

Create a working directory, link a Vercel project, and pull credentials:

mkdir sandbox-agent-demo && cd sandbox-agent-demo
npm i -g vercel
vercel link
vercel env pull

When prompted, select Create a new project. vercel env pull creates a .env.local file containing a VERCEL_OIDC_TOKEN that the Vercel SDK reads automatically.

Add your OpenAI API key to the same file:

echo 'OPENAI_API_KEY=sk-...' >> .env.local

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.

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.

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

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()

• 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

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

• 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