Como rodar a OpenAI Agents API no Vercel sem manter VM ligada

A Vercel anunciou no dia 10 de setembro de 2026 uma integração entre a OpenAI Agents API e sua infraestrutura serverless. A ideia central é simples de explicar e chata de implementar sozinho: a OpenAI hospeda o loop do agente e mantém o estado da sessão, enquanto a Vercel entrega o que falta pra isso virar um produto de verdade, um ambiente isolado pra executar código (Sandbox), processamento durável de eventos (Queues) e uma arquitetura que escala pra zero, sem VM viva 24/7 esperando request.

Pra quem constrói agente que roda ferramenta, lê e escreve arquivo e continua uma tarefa em cima da instrução anterior, esse é exatamente o pedaço espinhoso. Vou destrinchar o que muda no seu código e montar o caminho que eu seguiria pra colocar isso de pé.

O que a OpenAI faz e o que a Vercel faz

A divisão de responsabilidades é o coração da coisa. Vale separar antes de escrever qualquer linha:

O ponto que muda o jogo pro dev serverless: a Vercel descreve isso como scale-to-zero architecture without long-lived virtual machines. Ou seja, você não paga uma máquina rodando o tempo inteiro pra segurar o estado do agente, porque quem segura o estado é a OpenAI, e o sandbox sobe por sessão.

Por que webhook assinado + fila, e não só uma função

Aqui está a decisão de arquitetura mais importante e a que costuma quebrar quando a gente improvisa. O loop do agente roda do lado da OpenAI e é assíncrono e potencialmente longo. A OpenAI comunica os eventos ("o sandbox precisa subir", "execute isso", "a sessão terminou") via webhooks assinados.

A tentação é processar o webhook direto numa route handler e chamar o sandbox ali mesmo. O problema:

• Webhook precisa responder rápido, senão a OpenAI reprocessa e você duplica trabalho.
• Operação de sandbox (subir ambiente, rodar código) pode demorar mais que o timeout aceitável de um webhook.
• Se a função falha no meio, você perde o evento.

É pra isso que entra a Vercel Queues: o webhook só valida a assinatura e enfileira; um consumer processa o evento de forma durável, com retry. A Vercel chama isso de durable processing of sandbox lifecycle events, e é a parte que você não quer reimplementar na mão.

O caminho que eu seguiria

A Vercel publicou um step-by-step guide e uma sample application no changelog. Abaixo, o esqueleto de como eu montaria o fluxo, com as peças que a integração exige. Trate os nomes de pacote/handler como o roteiro conceitual, não como API final, confira sempre contra o guia oficial e a sample.

1. Pré-requisitos

• Conta na Vercel com Fluid Compute habilitado (a base do modelo serverless de longa duração da plataforma).
• Acesso à OpenAI Agents API e uma API key.
• Vercel Sandbox e Vercel Queues disponíveis no projeto.
• Node em versão LTS atual e o Vercel CLI.

npm i -g vercel@latest
vercel login
npx create-next-app@latest meu-agente
cd meu-agente

2. Configurar as variáveis de ambiente

# .env.local
OPENAI_API_KEY=sk-...
OPENAI_WEBHOOK_SECRET=whsec_...   # pra validar a assinatura do webhook

O OPENAI_WEBHOOK_SECRET é o que garante que o evento veio mesmo da OpenAI. Nunca processe o payload sem validar a assinatura, é a sua fronteira de segurança.

3. Receber o webhook e enfileirar (não processar direto)

// app/api/openai-webhook/route.ts
import { NextResponse } from 'next/server'
import { enqueue } from '@/lib/queue' // consumer da Vercel Queues

export async function POST(req: Request) {
  const signature = req.headers.get('openai-signature') ?? ''
  const body = await req.text()

  // 1) validar assinatura antes de qualquer coisa
  if (!verifySignature(body, signature, process.env.OPENAI_WEBHOOK_SECRET!)) {
    return new NextResponse('invalid signature', { status: 401 })
  }

  // 2) enfileirar e responder rápido
  await enqueue('sandbox-lifecycle', JSON.parse(body))
  return NextResponse.json({ received: true })
}

O handler faz o mínimo: valida e enfileira. Responder 200 rápido evita reprocessamento da OpenAI.

4. Consumir o evento e operar o Sandbox

// consumer da fila
import { Sandbox } from '@vercel/sandbox'

export async function handleLifecycle(event: SandboxEvent) {
  // sandbox persistente por sessão do agente
  const sandbox = await Sandbox.get(event.sessionId)
    ?? await Sandbox.create({ sessionId: event.sessionId })

  if (event.type === 'tool.run_code') {
    const result = await sandbox.exec(event.command)
    await reportBack(event.sessionId, result) // devolve pra OpenAI continuar o loop
  }
}

O detalhe que a Vercel destaca: o workspace é persistente entre instruções de follow-up. Se o usuário manda "agora ajusta aquele arquivo que você criou", os arquivos ainda estão lá, porque o sandbox está atrelado à sessionId, não a uma request.

Como verificar que deu certo

Depois do deploy (vercel deploy), o teste de fumaça que eu faria:

1. Rastreie o webhook. No dashboard da Vercel, veja se o endpoint recebeu o POST e respondeu 200. Se aparecer 401, sua validação de assinatura está errada, provavelmente o corpo foi parseado antes de verificar (assinatura precisa do raw body).
2. Confira a fila. Em Observability/Queues, o evento tem que sair de pending pra processed. Se ficar reprocessando, seu consumer está falhando silenciosamente.
3. Persistência. Rode duas instruções em sequência na mesma sessão criando e depois lendo um arquivo. Se a segunda não enxerga o arquivo, o sessionId não está batendo entre as chamadas.

Onde isso costuma quebrar

Os tropeços mais prováveis nesse tipo de integração, e como eu atacaria cada um:

• Assinatura inválida (401): quase sempre é o body. Frameworks que fazem req.json() automático consomem/normalizam o payload; use o raw body pra verificar a assinatura.
• Evento duplicado: webhook idempotente é obrigatório. Guarde o ID do evento e ignore repetidos, senão o mesmo comando roda duas vezes no sandbox.
• Sandbox "sumiu": se você criar sandbox por request em vez de por sessão, perde o estado. A chave é sempre resolver pelo sessionId.
• Timeout no webhook: se você processar o sandbox dentro do handler do webhook em vez de enfileirar, vai estourar. A fila existe justamente pra isso.

O que isso muda pro dev BR

O ganho real não é "agora dá pra fazer agente", isso já dava. É que a parte cara de operar, VM viva segurando estado, orquestração de execução isolada e durabilidade de eventos, sai do seu backlog. Pra times pequenos, que é a maioria por aqui, isso significa colocar um agente que executa código em produção sem manter infraestrutura ligada 24 horas, pagando por sessão em vez de por máquina ociosa.

O custo, que o changelog não detalha, mora em dois lugares: a Agents API da OpenAI (loop e estado do lado deles) e o Sandbox/Queues/Fluid Compute do lado Vercel. Antes de mandar pra produção, meça o custo por sessão em cenário real, porque scale-to-zero resolve ociosidade, mas não a conta de uma sessão longa executando muita ferramenta.

O ponto de partida oficial é o changelog da Vercel, com o step-by-step e a sample app linkados. Vale clonar a sample antes de escrever a sua, é mais rápido entender a divisão de responsabilidades vendo o código rodando do que montando do zero.

Fonte: Vercel Changelog