# Building an agent with OpenAI Agents SDK and Vercel Sandbox **Author:** Allen Zhou --- This guide walks through building an agent that analyzes data inside an isolated [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) microVM using the [OpenAI Agents SDK](https://developers.openai.com/api/docs/guides/agents). 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. ## How 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. ## Prerequisites - Python 3.10+ - A [Vercel account](https://vercel.com/signup) with Sandbox access - An [OpenAI API key](https://platform.openai.com/api-keys) ## Setup 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](https://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](https://pypi.org/project/vercel/) automatically. `python-dotenv` loads the `.env.local` credentials into the environment. ## Give 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. ## Configure 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 ## Stream 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()` ## Why 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](https://vercel.com/docs/vercel-sandbox), preventing data exfiltration - **Fast boot**: sandboxes start in milliseconds, so you can create one per request - [**Snapshots**](https://vercel.com/docs/vercel-sandbox): 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 ## Next steps - Deploy the [OpenAI Agents SDK template](https://vercel.com/templates/template/openai-agents-sdk-with-vercel-sandbox-fastapi) to get a working sandbox agent on Vercel in one click ## Resources - [Vercel Sandbox docs](https://vercel.com/docs/vercel-sandbox): runtime options, networking policies, exposed ports, persistence, and resource limits - [Vercel Python SDK](https://github.com/vercel/vercel-py): lower-level sandbox control, blob storage, OIDC tokens, and runtime cache - [OpenAI Agents SDK docs](https://developers.openai.com/api/docs/guides/agents): multi-agent workflows, tools, guardrails, streaming, and tracing --- [View full KB sitemap](/kb/sitemap.md)