---
title: OpenAI Agents API
product: vercel
url: /docs/sandbox/ecosystem/openai-agents-api
canonical_url: "https://vercel.com/docs/sandbox/ecosystem/openai-agents-api"
last_updated: 2026-09-17
type: conceptual
prerequisites:
  - /docs/sandbox/ecosystem
  - /docs/sandbox
related:
  - /docs/sandbox
  - /docs/queues
  - /docs/sandbox/concepts/persistent-sandboxes
  - /docs/cli
  - /docs/sandbox/ecosystem/openai-sdk
summary: Connect OpenAI Agents API sessions to Vercel Sandbox for isolated code execution and persistent workspace files.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# OpenAI Agents API

Use [Vercel Sandbox](/docs/sandbox) as the execution environment for
[OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview)
sessions. OpenAI manages the agent loop and session state. Sandbox gives each
session an isolated workspace to run commands and read and write files.

The [sample application](https://github.com/vercel-labs/openai-agents-api-vercel)
hosts the interface and API routes on Vercel. Signed OpenAI webhooks and
[Vercel Queues](/docs/queues) coordinate Sandbox creation and reconnection.

## How it works

1. Your application creates an OpenAI session with a self-hosted environment
   and submits a task.
2. OpenAI sends a signed webhook when the session needs an executor.
3. The webhook handler places the session ID on a Vercel Queue.
4. A Queue consumer reads the current session state and creates or resumes its
   named [persistent sandbox](/docs/sandbox/concepts/persistent-sandboxes).
5. `codex exec-server` connects outbound from the Sandbox to OpenAI. The agent
   runs commands in the workspace and streams its response to your application.

## Prerequisites

Before deploying the sample, you need:

- An OpenAI project with Agents API access and permission to create an
  application key and an environment key for the same user or service account
  in the same organization and project
- `api.webhooks.write` permission in that OpenAI project to register the
  webhook, or someone with that permission to register it for you
- A Vercel project with Sandbox and Queues access
- Node.js 24 or later and the [Vercel CLI](/docs/cli) for local setup

The application key manages OpenAI sessions. The environment key connects the
executor and is the only OpenAI credential passed into the Sandbox. Keep the
application key and webhook signing secret in your application server.

## Get started

Follow [Build an agent with OpenAI Agents API on
Vercel](/kb/guide/openai-agents-api-vercel) to configure the credentials,
deploy the sample, and register its webhook. After registration, add the
issued signing secret to the Vercel project and redeploy.

Test the deployed app by asking the agent to write a file, then read it in a
follow-up task. Deleting the session through the sample also deletes its
Sandbox.

For a function-calling loop that your application runs through the Responses
API, see the [OpenAI SDK integration](/docs/sandbox/ecosystem/openai-sdk).


---

[View full sitemap](/docs/sitemap)