neondatabase/neon-ai-gateway

PRIMEIRO: Use o skill pai neon para uma visão geral do Neon, introdução ao Neon, melhores práticas de desenvolvimento e mais.

Se o skill neon não estiver instalado, busque-o em https://neon.com/docs/ai/skills/neon/SKILL.md ou instale-o com:

npx skills add neondatabase/agent-skills --skill neon

Neon AI Gateway

Este é um recurso de beta público, atualmente disponível em us-east-2 e eu-central-1.

O Neon AI Gateway é a camada de inferência LLM integrada à sua branch Neon: uma única API e uma credencial Neon dão acesso a modelos de fronteira e open-source de muitos provedores (Anthropic, OpenAI, Google, Meta e mais), todos hospedados e alimentados pela Databricks. O catálogo muda com o tempo, então considere /v1/models e a página models.dev Neon como fonte da verdade, em vez de uma lista fixa de provedores. Seu SDK existente (OpenAI/Anthropic/Gemini) funciona apenas alterando a URL base.

Use este skill para ajudar o usuário a enviar chamadas de modelo através do gateway, integrá-lo ao AI SDK ou Mastra, e trocar de provedores sem reescrever código. Entregue uma requisição de inferência funcional, um agente configurado ou uma resposta precisa da documentação oficial do Neon.

Quando Usar

Recorra ao AI Gateway sempre que um aplicativo ou agente precisar chamar um LLM e o usuário preferir não gerenciar provedores de modelo:

• Uma credencial em vez de várias contas de provedor. Uma única credencial Neon alcança todo o catálogo de modelos em cada provedor que a Databricks hospeda. Sem contas separadas do OpenAI / Anthropic / Google, cobranças, chaves ou cadastros para provisionar e rotacionar.
• Troque modelos sem reescrever código. O endpoint unificado é compatível com OpenAI e funciona com todos os modelos do catálogo — altere um campo model para mudar entre Claude, GPT e Gemini. SDKs padrão (OpenAI, Anthropic, google-genai) funcionam com apenas uma alteração na URL base.
• AI segue suas branches. Cada branch tem seu próprio endpoint de gateway, com o mesmo escopo de linhagem do seu banco de dados. Requisições de IA de uma branch de preview/feature são isoladas para essa branch — o mesmo isolamento que seus dados já têm — o que torna preview, CI e ambientes de agente autocontidos.
• Sem infraestrutura extra, e já está perto dos seus dados. O gateway reside dentro do seu projeto Neon (e é injetado automaticamente no Neon Functions), executa na mesma infraestrutura Databricks que serve trilhões de tokens por mês, e suporta streaming (SSE) pronto para uso.

Se o usuário já tem uma integração profunda com um único provedor e não tem interesse no branching Neon ou roteamento multi-modelo, um SDK de provedor direto é suficiente — mas no momento em que quiser uma credencial, portabilidade de modelo ou IA com escopo de branch, esta é a razão para usá-lo.

O Que Faz

• Uma API para todos os modelos — Modelos de fronteira e open-source atrás de um único endpoint, endereçados pelo seu ID de catálogo (ex.: claude-sonnet-4-6, gpt-5-mini, gemini-3-flash).
• SDKs padrão, uma mudança de URL — SDK OpenAI e AI SDK (rotas OpenAI-compatíveis MLflow/Responses), SDK Anthropic (Messages nativo), google-genai (Gemini nativo).
• Com escopo de branch — Cada branch recebe seu próprio host de gateway; a credencial Neon autoriza requisições para essa branch e suas descendentes.
• Streaming — Eventos enviados pelo servidor funcionam em todos os endpoints sem configuração extra.

Disponibilidade

Verifique estas pré-condições antes de configurar qualquer coisa:

O AI Gateway é um recurso de beta público atualmente disponível em us-east-2 e eu-central-1. O acesso a modelos de base requer um plano Neon pago. Confirme se o projeto do usuário está em uma dessas regiões.

Habilitando o gateway: plano e bloqueio de catálogo de modelos

O AI Gateway é bloqueado por credencial, em vez de uma etapa de provisionamento, mas dois limites de plano/beta o bloqueiam — um impede o provisionamento, o outro apenas reduz o catálogo — e a CLI mostra cada um:

• Plano Gratuito → provisionamento bloqueado. neon config apply / deploy e neon checkout recusam habilitar o gateway em um plano Gratuito (o gateway não pode servir requisições lá), com um erro amigável "faça upgrade para um plano pago, ou remova preview.aiGateway". Um neon config plan simulado e neon env pull não provisionam, então apenas avisam. Portanto: para usar o gateway a conta do projeto deve estar em um plano Neon pago.
• Plano pago com catálogo de modelos reduzido. Em um plano pago o gateway provisiona e serve, mas durante o beta uma conta pode começar com um catálogo reduzido — alguns modelos emblemáticos (ex.: Anthropic Opus, OpenAI Codex / *-pro) estão ausentes de GET /v1/models. Isso é esperado; neon env pull (e o env pull embutido em apply / deploy / checkout) avisa e linka o usuário para a página do AI Gateway da sua branch no Console Neon (https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway) para solicitar acesso a mais modelos. Verifique o que está realmente disponível para a branch lendo /v1/models (veja a seção de modelos abaixo) em vez de assumir o catálogo completo.

Ao ajudar um usuário a depurar "o gateway não está funcionando" ou "um modelo está faltando", use /v1/models mais o plano da conta para distinguir esses dois casos — um plano Gratuito bloqueia o provisionamento completamente, enquanto um catálogo reduzido em um plano pago só precisa de uma solicitação de acesso a modelo.

Configuração

O gateway faz parte do neon.ts (veja o skill neon para o fluxo de trabalho baseado em branch e conceitos básicos do neon.ts). Habilite-o sob preview.aiGateway:

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  preview: {
    aiGateway: true,
  },
});

neon deploy   # provisiona o gateway na branch vinculada

Neon Infraestrutura como Código (neon.ts)

A opção preview.aiGateway acima faz parte do neon.ts, o arquivo de infraestrutura como código do Neon — um arquivo TypeScript declara o gateway junto com todos os outros serviços da branch, no controle de versão (veja o skill neon para a referência completa). Reconcilie-o contra uma branch da maneira Terraform:

neon config status   # exibe a configuração ativa da branch (o gateway está ativo?)
neon config plan     # diff simulado do que apply mudaria
neon config apply    # habilita o gateway na branch (neon deploy é um alias)

O gateway tem escopo de branch: cada branch recebe seu próprio host de gateway. Quando um neon.ts está presente, neon checkout aplica a política ao criar uma branch, então uma nova branch de preview/CI já vem com o gateway habilitado. Fazer checkout de uma branch existente não a reconcilia — execute neon deploy para aplicar alterações. O provisionamento (config apply / deploy), link e checkout também puxam as credenciais do gateway da branch para o .env.local local, então execuções locais atingem o mesmo gateway da branch que a função implantada (sem necessidade de env pull manual).

Variáveis de Ambiente

Quando preview.aiGateway está habilitado, o Neon injeta as credenciais do gateway como variáveis de ambiente marcadas como Neon. Dentro de uma Neon Function implantada elas são injetadas automaticamente; localmente, neon env pull as escreve em .env/.env.local (ou use neon-env run -- <cmd> para injetar em tempo de execução sem arquivo):

Variável	Significado
NEON_AI_GATEWAY_TOKEN	Token bearer do gateway (uma credencial Neon, nt_live_...)
NEON_AI_GATEWAY_BASE_URL	Host do gateway da branch puro (scheme://host, sem caminho — sem /ai-gateway): https://<branch-id>-api.ai.<region>.aws.neon.tech

O Neon injeta apenas essas duas variáveis — ele não define OPENAI_API_KEY / OPENAI_BASE_URL. O @neon/ai-sdk-provider e neon/<model> do Mastra leem NEON_AI_GATEWAY_* diretamente (configuração zero); para o SDK OpenAI puro / @ai-sdk/openai, construa o apiKey + baseURL do cliente a partir delas (mostrado abaixo), ou defina seus próprios OPENAI_* manualmente (env pull deixa variáveis definidas pelo usuário intactas).

NEON_AI_GATEWAY_BASE_URL é o host puro — você anexa o caminho do dialeto você mesmo (que é exatamente o que o @neon/ai-sdk-provider faz por você). As rotas sob o host são:

• /v1 — unificado, compatível com Chat Completions do OpenAI; padrão recomendado, funciona com todos os provedores (/v1/chat/completions).
• /openai/v1 — API Responses do OpenAI (necessária para variantes gpt-5-…-codex e gpt-5-5-pro); o provedor @ai-sdk/openai usa a API Responses por padrão (/openai/v1/responses).
• /anthropic — Messages nativo do Anthropic (pensamento estendido, cache de prompt). Dê ao SDK Anthropic esta URL base e ele anexa /v1/messages sozinho, então o caminho completo da requisição é /anthropic/v1/messages.
• /gemini — generateContent nativo do Gemini. Dê ao google-genai esta URL base e ele anexa /v1beta/models/<model>:generateContent sozinho, então o caminho completo da requisição é /gemini/v1beta/models/<model>:generateContent.

Portanto ${NEON_AI_GATEWAY_BASE_URL}/v1 é o endpoint de chat-completions e ${NEON_AI_GATEWAY_BASE_URL}/openai/v1 o endpoint Responses do OpenAI (ambos anexados por você); para os dialetos nativos Anthropic e Gemini você entrega ao SDK a base mais curta /anthropic ou /gemini e ele anexa o resto. Veja Uso com SDKs Puros abaixo.

Para acesso tipado e validado às credenciais injetadas, passe o mesmo objeto de configuração do neon.ts para parseEnv do @neon/env — ele retorna um namespace env.aiGateway (apiKey, baseUrl) derivado da sua configuração.

Construa Agentes com o Vercel AI SDK (Recomendado)

O Vercel AI SDK é a maneira recomendada de chamar o gateway e construir agentes a partir do TypeScript: um conjunto de primitivas (generateText, streamText, chamada de ferramentas, saída estruturada) sobre todos os modelos do catálogo, com streaming de primeira classe para as longas respostas de agente que o Neon Functions foi feito para hospedar.

O dedicado @neon/ai-sdk-provider lê NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN do ambiente injetado com configuração zero e roteia cada modelo para o melhor endpoint (Anthropic → Messages, OpenAI/Codex → Responses, todo o resto → MLflow). Em uma Neon Function que faz streaming de texto e gera imagens, basta escolher um modelo do catálogo:

import { neon } from "@neon/ai-sdk-provider";
import { streamText } from "ai";

const result = streamText({
  model: neon("gpt-5-mini"), // or claude-sonnet-4-6, gemini-3-flash, ...
  messages,
  tools: {
    image_generation: neon.tools.imageGeneration({
      outputFormat: "jpeg",
      size: "1024x1024",
    }),
  },
});
return result.toUIMessageStreamResponse();

Uma única conclusão usa o mesmo provedor com generateText:

import { neon } from "@neon/ai-sdk-provider";
import { generateText } from "ai";

const { text } = await generateText({
  model: neon("claude-haiku-4-5"), // or gpt-5-3-codex, gemini-3-flash, ...
  prompt: "Resuma o Postgres para mim.",
});

Prefira @neon/ai-sdk-provider ao openai() puro do @ai-sdk/openai: Neon injeta apenas NEON_AI_GATEWAY_*, não OPENAI_*, então openai() não capturará o gateway do ambiente sozinho. Se você usar @ai-sdk/openai, configure-o explicitamente com createOpenAI({ apiKey: process.env.NEON_AI_GATEWAY_TOKEN, baseURL: ${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1 }).

Para construir um agente — um modelo que chama ferramentas em um loop e depois responde — adicione tools e um orçamento stopWhen. O loop roda em processo, então em uma Neon Function ele não é interrompido por timeouts estilo lambda:

import { neon } from "@neon/ai-sdk-provider";
import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";

const { text } = await generateText({
  model: neon("claude-sonnet-4-6"),
  prompt: "Quantos afazeres em aberto eu tenho, e qual é o mais antigo?",
  tools: {
    listTodos: tool({
      description: "Lista os afazeres em aberto do usuário.",
      inputSchema: z.object({}), // AI SDK v5+: `inputSchema`, não `parameters`
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // deixa o modelo chamar ferramentas, depois resume
});

Para um agente completo do AI SDK implantado como Neon Function (streaming, chamada de ferramentas, geração de imagem, persistência), veja o skill neon-functions em references/ai-sdk.md.

Construa Agentes com Mastra (Recomendado)

Mastra é o framework recomendado quando você quer agentes com tudo incluído — memória embutida, ferramentas, workflows e rastreamento — com o modelo ainda apontado para o gateway. Com @mastra/core 1.47+, use uma string mágica neon/<model>; Mastra lê NEON_AI_GATEWAY_BASE_URL e NEON_AI_GATEWAY_TOKEN do ambiente (injetados por neon deploy quando preview.aiGateway está habilitado). Use parseEnv apenas para outros serviços declarados (ex.: env.postgres.databaseUrl para @mastra/pg memory):

import { Agent } from "@mastra/core/agent";
import { parseEnv } from "@neon/env";
import config from "../neon";

const env = parseEnv(config);

export const personalAssistant = new Agent({
  id: "personal-assistant",
  name: "personal-assistant",
  instructions:
    "Você é um assistente pessoal caloroso e conciso com memória de longo prazo.",
  model: "neon/claude-haiku-4-5",
  memory, // seu armazenamento de memória Mastra, ex.: @mastra/pg em env.postgres.databaseUrl
});

Uso com SDKs Puros (Nível Mais Baixo)

Quando você não precisa de um framework de agente — uma única conclusão, uma integração existente com SDK de provedor, ou recursos nativos do provedor — chame o gateway com os SDKs puros. O Neon injeta as variáveis NEON_AI_GATEWAY_* (não OPENAI_*), então defina o apiKey + baseURL do cliente a partir delas. Para o dialeto Responses do OpenAI (/openai/v1):

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

Para chamar um modelo de um projeto React (cliente web) ou de fora do ecossistema Neon, use esses mesmos valores:

// Exemplo: aplicação React
const response = await fetch(
  `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.NEON_AI_GATEWAY_TOKEN}`,
    },
    body: JSON.stringify({
      model: "gpt-5-mini",
      messages: [{ role: "user", content: "Oi" }],
    }),
  }
);

Exemplos de dialetos

Anthropic SDK (nativo, usa a rota /anthropic):

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/anthropic`,
});

O SDK anexa /v1/messages sozinho, então o caminho da requisição é …/anthropic/v1/messages.

Gemini SDK (google-genai):

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/gemini`,
});

O SDK anexa v1beta/models/<model>:generateContent sozinho, então o caminho da requisição é /gemini/v1beta/models/<model>:generateContent.

Liste Modelos e Verifique Disponibilidade

Sempre verifique o catálogo dinâmico: o catálogo muda, algumas ações (como upgrade de plano) expandem o catálogo de uma branch desbloqueando modelos conforme o acesso é concedido. Use o token da sua branch no endpoint /v1/models para ver o que está disponível:

curl -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  "${NEON_AI_GATEWAY_BASE_URL}/v1/models"

O array retornado contém os modelos liberados para essa branch. Se um modelo esperado estiver faltando, o usuário pode solicitar acesso via Console Neon:

1. Acesse https://console.neon.tech/app/projects//branches//ai-gateway
2. Clique em "Gerenciar Acesso a Modelos" (ou botão similar)
3. Solicite os modelos desejados

O Console também mostra o plano atual, região e status do gateway.

Casos de Uso Comuns

Compreenda estes padrões para guiar o usuário de forma eficiente.

Quero compartilhar inferência de IA com uma branch de preview

O gateway tem escopo de branch, então a branch de preview tem seu próprio endpoint. As variáveis de ambiente (NEON_AI_GATEWAY_TOKEN, NEON_AI_GATEWAY_BASE_URL) são injetadas pela Neon Function daquela branch, exatamente como as credenciais do banco de dados — sem codificação fixa.

Para tornar o gateway disponível em uma nova branch de preview:

neon checkout -b preview/my-feature && neon deploy

O gateway é provisionado automaticamente. Para uma branch já existente:

git checkout my-existing-branch && neon deploy

Se você precisa depurar se o gateway está ativo na branch: neon config status mostra a configuração ao vivo.

Quero mudar de Claude para GPT sem reescrever código

Com o @neon/ai-sdk-provider, troque o argumento model:

import { neon } from "@neon/ai-sdk-provider";

// Antes: Claude
const model = neon("claude-sonnet-4-6");

// Depois: GPT
const model = neon("gpt-5-mini");

Com o Mastra, troque a string neon/<model>:

// Antes
model: "neon/claude-haiku-4-5",
// Depois
model: "neon/gpt-5-mini",

Com SDKs puros, troque o campo model no corpo da requisição e opcionalmente o dialeto da URL:

const body = JSON.stringify({
  model: "claude-sonnet-4-6",
  // ou "gpt-5-mini"
  messages: [{ role: "user", content: "Hello" }],
});

Quero chamar ferramentas (tool calling) via gateway

Use a ferramenta de chamada de ferramentas do AI SDK — o gateway a suporta de forma nativa quando o modelo a suporta:

import { neon } from "@neon/ai-sdk-provider";
import { generateText, tool } from "ai";

const result = await generateText({
  model: neon("claude-sonnet-4-6"),
  prompt: "Qual é o clima em Tóquio?",
  tools: {
    getWeather: tool({
      description: "Busca o clima atual para uma cidade",
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => fetchWeather(city),
    }),
  },
});

Com Mastra, defina ferramentas como métodos na classe do agente ou passe-as via tools na definição. A string mágica neon/<model> suporta chamada de ferramentas nativamente.

Quero usar modelos de geração de imagens

Modelos de imagem (ex.: dall-e-3, imagen) estão disponíveis através do método neon.tools.imageGeneration no AI SDK:

import { neon } from "@neon/ai-sdk-provider";

const result = await generateText({
  model: neon("gpt-5-mini"),
  tools: {
    generate_image: neon.tools.imageGeneration({
      outputFormat: "jpeg",
      size: "1024x1024",
      quality: "hd",
    }),
  },
  prompt: "Crie uma imagem de uma paisagem montanhosa serena",
});

Alternativamente, use a API Rest diretamente: POST para /v1/chat/completions com o modelo de imagem apropriado e o formato de conteúdo multimodal.

Referência de ID de Modelo do Catálogo

Para referência, aqui estão IDs de modelo comuns (sempre verifique /v1/models para a lista atual):

Provedor	Modelo	ID do Catálogo	Dialeto
Anthropic	Claude Sonnet 4.6	claude-sonnet-4-6	v1
Anthropic	Claude Haiku 4.5	claude-haiku-4-5	v1
OpenAI	GPT 5 Mini	gpt-5-mini	v1
OpenAI	GPT 5 3 Codex	gpt-5-3-codex	/openai/v1
OpenAI	GPT 5 5 Pro	gpt-5-5-pro	/openai/v1
Google	Gemini 3 Flash	gemini-3-flash	v1
Meta	Llama 4 Maverick	llama-4-maverick	v1

Solução de Problemas

"Gateway não está funcionando"

1. Verifique a região — gateway disponível apenas em us-east-2 e eu-central-1. Confirme a região do projeto via Console Neon ou neon config status.
2. Verifique o plano — requer plano pago. Execute neon config plan para ver se o provisionamento está bloqueado.
3. Verifique as variáveis de ambiente — dentro de uma Neon Function, console.log(process.env.NEON_AI_GATEWAY_BASE_URL, process.env.NEON_AI_GATEWAY_TOKEN). Localmente, certifique-se de que neon env pull foi executado.
4. Teste o endpoint /v1/models com a credencial da branch (veja acima) para ver se o gateway responde.

"Modelo X não está disponível"

1. Verifique /v1/models — o modelo pode não estar no catálogo atual.
2. Verifique o dialeto correto — alguns modelos exigem /openai/v1 (ex.: Codex).
3. Um plano pago pode ter um catálogo reduzido durante o beta; solicite acesso via Console Neon (veja "Liste Modelos e Verifique Disponibilidade" acima).

"A chamada do SDK retorna erro de autenticação"

Confirme se você está usando NEON_AI_GATEWAY_TOKEN como apiKey (não OPENAI_API_KEY). Se estiver usando @neon/ai-sdk-provider, ele lida com isso automaticamente. Para SDKs puros, certifique-se de que baseURL está definida corretamente (veja dialetos acima).

"A chamada do streaming não funciona"

O gateway suporta SSE nativamente — nenhuma configuração extra necessária. Se o cliente não estiver recebendo eventos, certifique-se de que o cliente suporta streaming (ex.: stream: true no corpo do OpenAI SDK) e que a rede permite conexões longas.

Segurança e Limites

O gateway é protegido pelo token bearer da branch; um token comprometido concede acesso aos modelos para aquela branch. Limites de taxa são aplicados por conta; durante o beta, há limites suaves de requisições que podem ser aumentados mediante solicitação. Consulte a documentação do Console Neon para limites atuais.

Perguntas Frequentes

O gateway funciona com SDKs de outros provedores?

Sim — qualquer SDK compatível com OpenAI pode usar o gateway apontando sua base URL para ${NEON_AI_GATEWAY_BASE_URL}/v1. SDKs Anthropic e google-genai nativos também são suportados com seus dialetos específicos.

Preciso de uma conta separada na Databricks?

Não — a Databricks hospeda a infraestrutura, mas você não precisa de uma conta Databricks separada. Tudo é gerenciado através do seu projeto Neon.

Quanto custa?

O gateway em si (durante o beta) não tem custo extra além do plano Neon pago. Modelos individuais podem ter custos de inferência associados; verifique a página de preços do provedor de modelo para detalhes.

Como removo o gateway de uma branch?

Defina preview.aiGateway: false no neon.ts e execute neon deploy ou neon config apply. Isso desprovisiona o gateway para aquela branch.