OpenAI Agents SDK FastAPI Starter is a boilerplate project from Vercel Labs that combines FastAPI, the OpenAI Agents SDK, and Vercel Sandbox to run an agent with shell access to an ephemeral microVM per request. It accepts a JSON prompt via POST /api/run and returns the agent's text answer after the agent inspects sample sales data with shell commands. It targets Vercel's Python runtime (3.12) and is managed with uv.
What is the OpenAI Agents SDK FastAPI Starter?
This is a minimal FastAPI application that runs the OpenAI Agents SDK inside Vercel Sandbox microVMs on Vercel's Python runtime. It takes a POST request with an input string and produces a text response generated by an agent that executes shell commands against bundled sample data. The project is published under the MIT license and maintained by Vercel Labs.
Key Features
- Isolated sandbox per request — every POST /api/run spins up a fresh Vercel Sandbox microVM pre-loaded with sample data (sales.csv) and tears it down after the response.
- Shell-capable agent — the SandboxAgent gets a Shell tool so it can write and run shell commands to answer questions like "Which region grew the most?".
- FastAPI app with two endpoints — GET /api/health returns status and whether OPENAI_API_KEY is configured; POST /api/run accepts an input field and runs the agent.
- Environment variable driven — requires OPENAI_API_KEY, VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID; optional OPENAI_DEFAULT_MODEL defaults to gpt-4.1-mini; optional OPENAI_BASE_URL enables AI Gateway.
- Vercel AI Gateway ready — supports pointing to https://ai-gateway.vercel.sh/v1 and using MultiProvider with openai_prefix_mode="model_id" so gateway keys work with the Agents SDK.
- Local development workflow — uses
uv sync and uv run uvicorn app:app --reload --host 127.0.0.1 --port 8000 for a hot-reloading demo.
- One-command Vercel deploy — running
vercel detects app.py and installs dependencies from pyproject.toml automatically.
Who should use this template?
- Python developers building agent-based APIs — skip the plumbing for combining FastAPI with the OpenAI Agents SDK and get a working shell-tool agent in minutes.
- Vercel users who want isolated compute per request — use the Sandbox integration to give agents temporary shell access without managing a long-lived server.
- Prototypers of data-analysis agents — the bundled sales.csv lets you test prompts that require real command-line work before adding your own datasets.
What can you do with it?
- Prototype an agent that answers questions about a CSV — send a prompt like "Which region grew the most?" and receive an answer backed by shell commands run inside the sandbox.
- Route requests through Vercel AI Gateway — set OPENAI_BASE_URL to https://ai-gateway.vercel.sh/v1 and use the provided MultiProvider configuration to leverage gateway features (caching, rate limiting, observability) with the Agents SDK.
- Extend the agent with your own tools and data — replace sales.csv with your datasets or add new capabilities to the SandboxAgent while keeping the same request/response flow.
How does it work?
- A client sends POST /api/run with an input string.
- The FastAPI app creates a fresh Vercel Sandbox microVM that includes sample data.
- A SandboxAgent with the Shell tool receives the prompt, writes scripts, and runs them to find the answer.
- The sandbox is destroyed immediately after the response is returned.
FAQ
What environment variables do I need to set?
You must set OPENAI_API_KEY, VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID. OPENAI_API_KEY can be a regular OpenAI key or a Vercel AI Gateway key. VERCEL_TOKEN comes from https://vercel.com/account/tokens, and the team and project IDs are found in your Vercel dashboard.
Can I run this without a Vercel account?
No. Vercel Sandbox creation requires a valid VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID, so a Vercel account is mandatory for the sandbox to start.
What is the default model?
If OPENAI_DEFAULT_MODEL is not set, the agent falls back to gpt-4.1-mini. You can override it by setting OPENAI_DEFAULT_MODEL to any model your API key can access, or by omitting model in the request body to use the default.
Does this work with the Vercel AI Gateway?
Yes. Create an AI Gateway key, set it as OPENAI_API_KEY, set OPENAI_BASE_URL to https://ai-gateway.vercel.sh/v1, and add a RunConfig with model_provider that uses openai_prefix_mode="model_id" so the provider prefix isn't stripped.
Why is the response slow?
The README notes that sandbox creation and agent runs can take several seconds. For heavy workloads, you may need to enable Fluid Compute or switch to Vercel Workflow for durable multi-step execution.
