Build an agentic app in FastAPI with OpenAI Agents API and Vercel Sandbox

This FastAPI template answers questions about public GitHub repositories using OpenAI Agents API and Vercel Sandbox. The OpenAI Agents API lets you create agent sessions, submit tasks, and stream progress as the agent works. This template uses the OpenAI Agents API through its Python SDK.

Vercel Sandbox provides Linux microVMs that you can create and manage from your application. A sandbox provides an agent with an isolated environment in which it can read files and run commands.

A user supplies a repository, a Git ref, and a question such as “What framework and package manager does this project use?” The app clones the repository into a sandbox, lets the agent inspect it, and returns an answer with supporting evidence.

In this guide, you'll connect an OpenAI Agents API session to Vercel Sandbox, run the template locally, and deploy the FastAPI app to Vercel.

Deploy the template now, or follow the steps below to build it.

Repository Q&A app with OpenAI Agents API

A FastAPI app that answers questions about GitHub repositories using Vercel Sandbox and OpenAI Agents API, with streamed progress and downloadable evidence.

Deploy Template

Copy link to headingQuick start with an AI coding agent

Agent Prompt

Help me set up and deploy the repository agent from https://github.com/vercel-labs/openai-agents-api-fastapi. Read README.md, AGENTS.md, ARCHITECTURE.md, and .env.example before making changes. Use Python 3.11 or later and a virtual environment. Install the dependencies listed in requirements.txt and requirements-dev.txt. Read the [OpenAI Agents API public beta SDK docs](https://developers.openai.com/api/docs/guides/agents-api/overview) before implementing or making suggestions. Help me configure OPENAI_API_KEY and a separate restricted OPENAI_EXECUTOR_API_KEY using the documented permissions. The application defines its agent inline for each session; no AGENT_ID is needed. Explain how to obtain missing credentials without putting secrets in chat or tracked files. Link a Vercel project with Sandbox access and run vercel env pull .env.local for local authentication. Follow the README to start FastAPI locally. Preserve the bounded repository inspection, separation of application and executor keys, and cleanup of sessions and sandboxes. Run the existing tests and lint checks. Check /api/health, then submit a focused question about a public GitHub repository with a valid ref. Verify the answer, session and sandbox IDs, and RESULT.md, evidence.json, and events.jsonl downloads. Configure both OpenAI keys in Vercel, deploy a preview, and repeat the verification. Report the deployment URL and any remaining setup requirements.

This guide covers the core implementation. The AI assistant prompt above covers all the details your coding agent needs, and you can see the full implementation in the template repository.

Copy link to headingVercel Plugin

Optionally, install the Vercel Plugin for Vercel-specific guidance in your coding agent. It provides product context, skills, and commands for working with Vercel, including Vercel Sandboxes and deployments.

Terminal

npx plugins add vercel/vercel-plugin

Copy link to headingPrerequisites

Before you begin, make sure you have:

Python 3.11 or later and Git installed.
Node.js and npm to install the Vercel CLI: npm install -g vercel.
A Vercel account and a project with Sandbox access.
An OpenAI organization and project. You'll create separate application and executor keys during local setup.
A public GitHub repository to inspect.

Copy link to headingHow it works

The app is a single FastAPI project that serves the browser interface and handles each inspection through POST /api/inspect:

FastAPI validates the repository URL, Git ref, and question, then creates a self-hosted Agents API session.
The Vercel Sandbox SDK creates a sandbox and clones the selected repository into /vercel/sandbox.
The app installs Codex in the sandbox and starts codex exec-server. The executor connects outbound to the OpenAI Agents API using the session's environment ID.
FastAPI submits the question and streams progress and available answer text to the browser using server-sent events.
The agent writes an answer and structured evidence. FastAPI collects the files, deletes the API session while the executor is connected, stops the sandbox, and returns the result.

Architecture

Browser → FastAPI → Agents API session
             │              ↕
             └────→ Vercel Sandbox
                      Codex executor + cloned repository

Each question gets its own session and sandbox. The prompt asks the agent to use at most eight short commands, leave the checkout unchanged, and avoid dependency installation, builds, and network requests during inspection. The sandbox's network policy separately limits outbound connections to the services needed for cloning, installing Codex, and connecting the executor.

The result includes three downloads: RESULT.md for the answer, evidence.json for inspected files, commands, and limitations, and events.jsonl for API events captured by FastAPI. The app keeps these in the response rather than saving them to a database.

Copy link to headingSteps

Copy link to heading1. Set up the project

Clone the template repository and install its dependencies in a virtual environment:

Terminal

git clone https://github.com/vercel-labs/openai-agents-api-fastapi.git
cd openai-agents-api-fastapi
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt -r requirements-dev.txt

On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell.

The template already includes the complete application. The application is organized into these files:

File	Purpose
`sandbox_agent/main.py`	Serves the page and inspection endpoint
`sandbox_agent/runner.py`	Creates sessions, streams events, and cleans up resources
`sandbox_agent/vercel_sandbox.py`	Creates the sandbox and starts the executor
`sandbox_agent/prompt.py`	Defines the inspection instructions and output files
`sandbox_agent/artifacts.py`	Collects the answer, evidence, and event log
`app.py`	Exports the application for Vercel

Copy link to heading2. Integrate OpenAI Agents API

In sandbox_agent/runner.py, the session setup follows this pattern inside the asynchronous inspection handler:

sandbox_agent/runner.py

from openai import AsyncOpenAI

from sandbox_agent.config import get_settings
from sandbox_agent.prompt import build_agent_instructions

# Inside the asynchronous inspection handler.
settings = get_settings()
client = AsyncOpenAI(
    api_key=settings.openai_api_key,
    base_url=settings.agents_api_url,
    max_retries=0,
    timeout=settings.session_create_timeout_seconds,
)

session = await client.beta.agents.sessions.create(
    agent={
        "model": settings.agent_model,
        "instructions": build_agent_instructions(),
        "reasoning": {"effort": settings.agent_reasoning_effort},
        "text": {"verbosity": "low"},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/vercel/sandbox",
    },
)

environment = session.environment
if environment.type != "self_hosted":
    raise RuntimeError(
        f"Expected self-hosted environment, got {environment.type}"
    )

environment_id = environment.id
remote_url = environment.remote_url

The environment ID connects this session to the executor you'll start in the next step. It is separate from both the Agents API session ID and the Vercel Sandbox ID.

settings.agents_api_url defaults to https://api.openai.com/v1, while remote_url comes from the session response and must remain unchanged.

build_agent_instructions() defines the agent's role and tells it to treat repository contents as evidence, never as instructions. build_inspection_prompt() adds the user's question, the command budget, and the required output paths under /tmp/sandbox-agent.

Inside the inspection handler, build the prompt from the validated request:

sandbox_agent/runner.py

from sandbox_agent.prompt import build_inspection_prompt

prompt = build_inspection_prompt(
    repo_url=request.repo_url,
    ref=request.ref,
    question=request.question,
)

Here, request is the validated inspection request containing the repository URL, Git ref, and question. The resulting prompt is what the later input=prompt sends to the agent.

Once the sandbox executor has started, submit the prompt through client.beta.agents.sessions.stream(session.id, input=prompt) as an async context manager. This opens the stream before sending the input:

sandbox_agent/runner.py

from sandbox_agent.sse import encode_sse

text_parts = {}

async with client.beta.agents.sessions.stream(
    session.id,
    input=prompt,
    timeout=settings.stream_no_progress_timeout_seconds,
) as events:
    async for event in events:
        if event.type == "agent.session.turn.output_text.delta":
            key = (event.item_id, event.output_index, event.content_index)
            text_parts[key] = text_parts.get(key, "") + event.delta
            yield encode_sse("answer_delta", {"delta": event.delta})
        elif event.type == "agent.session.turn.output_text.done":
            key = (event.item_id, event.output_index, event.content_index)
            text_parts[key] = event.text

streamed_answer = "".join(text_parts.values())

output_text.done events replace the matching content part because deltas may be absent. The complete handler also captures events, checks executor health while opening and consuming the stream, handles failures, and collects artifacts. It requires a completed root-agent turn and a final idle session with no run error before reporting success.

By default, the handler stops waiting after 45 seconds without an event or when the inspection reaches its 150-second limit. The final answer is read from RESULT.md when available, with streamed text as a fallback.

Copy link to heading3. Integrate managed compute with the Sandbox SDK

The template uses the Python Sandbox SDK included in the vercel package. In sandbox_agent/vercel_sandbox.py, create a sandbox from the validated repository URL and Git ref: