Skip to content

Building an agent with OpenAI Agents SDK and Vercel Sandbox

Learn how to build an agent with with OpenAI Agents SDK and Vercel Sandbox

Knowledge Base/AI
3 min read
Last updated April 25, 2026

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.

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.

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

Was this helpful?

supported.

Read related documentation

Explore more Vercel Sandbox guides