PRIMERO: Usa la habilidad principal neon para obtener una visión general de Neon, comenzar a usar Neon, las mejores prácticas de desarrollo y más.

Si la habilidad neon no está instalada, obténla desde https://neon.com/docs/ai/skills/neon/SKILL.md o instálala con:

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

Neon AI Gateway

Esta es una función beta pública, actualmente disponible en us-east-2 y eu-central-1.

El Neon AI Gateway es la capa de inferencia de LLM integrada en tu rama de Neon: una API y una credencial de Neon te dan acceso a modelos de frontera y de código abierto de muchos proveedores (Anthropic, OpenAI, Google, Meta y más), todos alojados y potenciados por Databricks. El catálogo cambia con el tiempo, así que trata /v1/models y la página de modelos de Neon como la fuente de verdad en lugar de una lista fija de proveedores. Tu SDK existente de OpenAI/Anthropic/Gemini funciona con solo cambiar la URL base.

Usa esta habilidad para ayudar al usuario a enviar llamadas de modelo a través del gateway, conectarlo con el SDK de IA o Mastra, y cambiar de proveedor sin reescribir código. Entrega una solicitud de inferencia funcional, un agente configurado o una respuesta precisa de la documentación oficial de Neon.

Cuándo Usarlo

Recurre al AI Gateway siempre que una aplicación o agente necesite llamar a un LLM y el usuario prefiera no gestionar los proveedores de modelos por sí mismo:

Una credencial en lugar de muchas cuentas de proveedores. Una sola credencial de Neon alcanza todo el catálogo de modelos en todos los proveedores que Databricks aloja. Sin facturación separada de OpenAI / Anthropic / Google, ni claves o registros que aprovisionar y rotar.
Cambia de modelos sin reescribir código. El endpoint unificado es compatible con OpenAI y funciona con todos los modelos del catálogo: cambia un campo model para moverte entre Claude, GPT y Gemini. Los SDKs estándar (OpenAI, Anthropic, google-genai) funcionan con solo un cambio en la URL base.
La IA sigue a tus ramas. Cada rama tiene su propio endpoint de gateway, con el mismo linaje que tu base de datos. Las solicitudes de IA de una rama de vista previa/CI están aisladas a esa rama, el mismo aislamiento que ya tiene tus datos, lo que hace que los entornos de vista previa, CI y agente sean autocontenidos.
Sin infraestructura adicional, y ya está al lado de tus datos. El gateway vive dentro de tu proyecto de Neon (y se inyecta automáticamente en Neon Functions), se ejecuta en la misma infraestructura de Databricks que sirve billones de tokens al mes, y soporta streaming (SSE) de forma nativa.

Si el usuario ya tiene una integración profunda con un solo proveedor y no le interesa la ramificación de Neon o el enrutamiento multi-modelo, un SDK de proveedor directo está bien, pero en el momento en que quiera una credencial, portabilidad de modelos o IA aislada por rama, esta es la razón para usarlo.

Qué Hace

Una API para todos los modelos — Modelos de frontera y de código abierto detrás de un solo endpoint, direccionados por su ID de catálogo (ej. claude-sonnet-4-6, gpt-5-mini, gemini-3-flash).
SDKs estándar, un cambio de URL — SDK de OpenAI y SDK de IA (rutas compatibles con OpenAI MLflow/Responses), SDK de Anthropic (Mensajes nativos), google-genai (Gemini nativo).
Aislado por rama — Cada rama obtiene su propio host de gateway; la credencial de Neon autoriza solicitudes para esa rama y sus descendientes.
Streaming — Los eventos enviados por el servidor funcionan en todos los endpoints sin configuración adicional.

Disponibilidad

Verifica estos requisitos previos antes de configurar cualquier cosa:

El AI Gateway es una función beta pública actualmente disponible en us-east-2 y eu-central-1. El acceso a modelos fundacionales requiere un plan de Neon de pago. Confirma que el proyecto del usuario esté en una de estas regiones.

Habilitación del gateway: plan y control del catálogo de modelos

El AI Gateway está controlado por credenciales en lugar de ser un paso de aprovisionamiento, pero dos límites de plan/beta lo controlan: uno bloquea el aprovisionamiento, el otro solo reduce el catálogo, y la CLI muestra cada uno:

Plan gratuito → el aprovisionamiento está bloqueado. neon config apply / deploy y neon checkout se niegan a habilitar el gateway en un plan gratuito (el gateway no puede servir solicitudes allí), con un error amigable de "actualiza a un plan de pago, o elimina preview.aiGateway". Un neon config plan de prueba y neon env pull no aprovisionan, por lo que solo advierten. Por lo tanto: para usar el gateway, la cuenta del proyecto debe tener un plan de Neon de pago.
Plan de pago con un catálogo de modelos reducido. En un plan de pago, el gateway se aprovisiona y sirve, pero durante la beta una cuenta puede comenzar con un catálogo recortado: algunos modelos emblemáticos (ej. Anthropic Opus, OpenAI Codex / *-pro) faltan en GET /v1/models. Esto es esperado; neon env pull (y la extracción de env incorporada en apply / deploy / checkout) advierte y enlaza al usuario a la página del AI Gateway de su rama en la Consola de Neon (https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway) para solicitar acceso a más modelos. Verifica qué está realmente disponible para la rama leyendo /v1/models (consulta la sección de modelos a continuación) en lugar de asumir el catálogo completo.

Al ayudar a un usuario a depurar "el gateway no funciona" o "falta un modelo", usa /v1/models más el plan de la cuenta para distinguir estos dos casos: un plan gratuito bloquea el aprovisionamiento por completo, mientras que un catálogo reducido en un plan de pago solo necesita una solicitud de acceso al modelo.

Configuración

El gateway es parte de neon.ts (consulta la habilidad neon para el flujo de trabajo basado en ramas y los conceptos básicos de neon.ts). Habilítalo bajo preview.aiGateway:

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

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

neon deploy   # aprovisiona el gateway en la rama vinculada

Infraestructura como Código de Neon (`neon.ts`)

El conmutador preview.aiGateway anterior es parte de neon.ts, el archivo de infraestructura como código de Neon: un archivo TypeScript declara el gateway junto con todos los demás servicios de la rama, bajo control de versiones (consulta la habilidad neon para la referencia completa). Reconcilíalo contra una rama al estilo Terraform:

neon config status   # imprime la configuración activa de la rama (¿está el gateway encendido?)
neon config plan     # diff de prueba de lo que cambiaría apply
neon config apply    # habilita el gateway en la rama (neon deploy es un alias)

El gateway está aislado por rama: cada rama obtiene su propio host de gateway. Cuando hay un neon.ts presente, neon checkout aplica la política al crear una rama, por lo que una rama nueva de vista previa/CI se crea con el gateway ya habilitado. Al hacer checkout de una rama existente, no se reconcilia: ejecuta neon deploy para aplicar los cambios. El aprovisionamiento (config apply / deploy), link y checkout también extraen las credenciales del gateway de la rama a tu .env.local, por lo que las ejecuciones locales usan el mismo gateway de rama que la función desplegada (sin necesidad de env pull manual).

Variables de Entorno

Cuando preview.aiGateway está habilitado, Neon inyecta las credenciales del gateway como variables de entorno marca Neon. Dentro de una Neon Function desplegada, se inyectan automáticamente; localmente, neon env pull las escribe en .env/.env.local (o usa neon-env run -- <cmd> para inyectarlas en tiempo de ejecución sin un archivo):

Variable	Significado
`NEON_AI_GATEWAY_TOKEN`	Token de portador del gateway (una credencial de Neon, `nt_live_...`)
`NEON_AI_GATEWAY_BASE_URL`	Host del gateway de la rama desnudo (`scheme://host`, sin ruta — sin `/ai-gateway`): `https://<branch-id>-api.ai.<region>.aws.neon.tech`

Neon inyecta solo estas dos variables — no establece OPENAI_API_KEY / OPENAI_BASE_URL. El @neon/ai-sdk-provider y Mastra con neon/<model> leen NEON_AI_GATEWAY_* directamente (sin configuración); para el SDK de OpenAI simple / @ai-sdk/openai, construye el apiKey + baseURL del cliente a partir de ellas (se muestra a continuación), o establece tus propias OPENAI_* manualmente (env pull deja las vars del usuario intactas).

NEON_AI_GATEWAY_BASE_URL es el host desnudo: tú agregas la ruta del dialecto (que es exactamente lo que el @neon/ai-sdk-provider hace por ti). Las rutas bajo el host son:

/v1 — unificado, compatible con Chat Completions de OpenAI; recomendado por defecto, funciona con todos los proveedores (/v1/chat/completions).
/openai/v1 — API de Responses de OpenAI (requerida para variantes gpt-5-…-codex y gpt-5-5-pro); el proveedor @ai-sdk/openai usa la API de Responses por defecto (/openai/v1/responses).
/anthropic — Mensajes nativos de Anthropic (pensamiento extendido, almacenamiento en caché de prompts). Dale esta URL base al SDK de Anthropic y él mismo agregará /v1/messages, por lo que la ruta completa de la solicitud es /anthropic/v1/messages.
/gemini — generateContent nativo de Gemini. Dale esta URL base a google-genai y él mismo agregará /v1beta/models/<model>:generateContent, por lo que la ruta completa de la solicitud es /gemini/v1beta/models/<model>:generateContent.

Así que ${NEON_AI_GATEWAY_BASE_URL}/v1 es el endpoint de chat-completions y ${NEON_AI_GATEWAY_BASE_URL}/openai/v1 el endpoint de Responses de OpenAI (ambos agregados por ti); para los dialectos nativos de Anthropic y Gemini, le das al SDK la base más corta /anthropic o /gemini y él agrega el resto. Consulta Uso con SDKs Simples (Bajo Nivel) a continuación.

Para acceso tipificado y validado a las credenciales inyectadas, pasa el mismo objeto de configuración de neon.ts a parseEnv de @neon/env — devuelve un espacio de nombres env.aiGateway (apiKey, baseUrl) derivado de tu configuración.

Construir Agentes con el SDK de IA de Vercel (Recomendado)

El SDK de IA de Vercel es la forma recomendada de llamar al gateway y construir agentes desde TypeScript: un conjunto de primitivas (generateText, streamText, llamada a herramientas, salida estructurada) para todos los modelos del catálogo, con streaming de primera clase para las respuestas largas de agente que Neon Functions está diseñada para alojar.

El proveedor dedicado @neon/ai-sdk-provider lee NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN del entorno inyectado con configuración cero y enruta cada modelo al mejor endpoint (Anthropic → Messages, OpenAI/Codex → Responses, todo lo demás → MLflow). En una Neon Function que transmite texto y genera imágenes, solo elige un modelo del catálogo:

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

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

Una sola finalización es el mismo proveedor con generateText:

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

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

Prefiere @neon/ai-sdk-provider sobre el openai() simple de @ai-sdk/openai: Neon inyecta solo NEON_AI_GATEWAY_*, no OPENAI_*, por lo que openai() no detectará el gateway desde el entorno por sí solo. Si usas @ai-sdk/openai, configúralo explícitamente con createOpenAI({ apiKey: process.env.NEON_AI_GATEWAY_TOKEN, baseURL: ${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1 }).

Para construir un agente — un modelo que llama a herramientas en un bucle y luego responde — agrega tools y un presupuesto stopWhen. El bucle se ejecuta en el proceso, por lo que en una Neon Function no se corta por tiempos de espera 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: "¿Cuántas tareas pendientes tengo y cuál es la más antigua?",
  tools: {
    listTodos: tool({
      description: "Lista las tareas pendientes del usuario.",
      inputSchema: z.object({}), // SDK de IA v5+: `inputSchema`, no `parameters`
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // deja que el modelo llame a herramientas y luego resuma
});

Para un agente completo del SDK de IA desplegado como una Neon Function (streaming, llamada a herramientas, generación de imágenes, persistencia), consulta la habilidad neon-functions en references/ai-sdk.md.

Construir Agentes con Mastra (Recomendado)

Mastra es el framework recomendado cuando quieres agentes con baterías incluidas — memoria incorporada, herramientas, flujos de trabajo y trazado — con el modelo aún apuntando al gateway. Con @mastra/core 1.47+, usa una cadena mágica neon/<model>; Mastra lee NEON_AI_GATEWAY_BASE_URL y NEON_AI_GATEWAY_TOKEN del entorno (inyectados por neon deploy cuando preview.aiGateway está habilitado). Usa parseEnv solo para otros servicios declarados (ej. env.postgres.databaseUrl para la memoria de @mastra/pg):

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:
    "Eres un asistente personal cálido y conciso con memoria a largo plazo.",
  model: "neon/claude-haiku-4-5",
  memory, // tu almacén de memoria de Mastra, ej. @mastra/pg en env.postgres.databaseUrl
});

Uso con SDKs Simples (Bajo Nivel)

Cuando no necesitas un framework de agente — una sola finalización, una integración existente con un SDK de proveedor o funciones nativas del proveedor — llama al gateway con los SDKs simples. Neon inyecta las variables NEON_AI_GATEWAY_* (no OPENAI_*), así que establece apiKey + baseURL del cliente a partir de ellas. Para el dialecto de Responses de 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`,
});

const response = await client.responses.create({
  model: "gpt-5-3-codex",
  input: "Hola",
});

console.log(response.output_text);

Para el dialecto de Chat Completions de 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}/v1`,
});

const chatCompletion = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Hola" }],
});

console.log(chatCompletion.choices[0].message.content);

Para Anthropic SDK nativo:

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`,
});

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hola" }],
});

console.log(response.content[0].text);

Para Google Gemini SDK nativo:

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`,
});

const response = await ai.models.generateContent({
  model: "gemini-3-flash",
  contents: "Hola",
});

console.log(response.text);

Listado de Modelos / `/v1/models`

GET /v1/models devuelve el catálogo completo de modelos para la rama del gateway, con la estructura estándar de OpenAI (cada modelo tiene un id, created, owned_by). Trata esto como la fuente de verdad del catálogo, no el README de este proyecto ni la documentación del proveedor. Algunos modelos con nombre son alias de los modelos subyacentes de Anthropic / OpenAI / Google; consulta /v1/models para ver qué alias están activos y solicita el acceso a modelos desde la Consola de Neon para desbloquear más.

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

Nota del catálogo reducido. Durante la beta, una cuenta puede tener un catálogo más pequeño de forma predeterminada: los modelos demandados (Anthropic Opus, -pro y -codex de OpenAI) pueden faltar hasta que el usuario solicite acceso desde la página del AI Gateway de su rama en la Consola de Neon. Siempre verifica con /v1/models.

Proveedor de Modelos de Código Abierto (`@neon/ai-sdk-provider`)

El SDK de TipoScript @neon/ai-sdk-provider del gateway expone una función neon() que es un proveedor de modelos completo (LanguageModelV1) que se conecta al SDK de IA de Vercel (ai). Está empaquetado de forma independiente en @neon/ai-sdk-provider (no en @neon/core ni en otro lugar). Lee NEON_AI_GATEWAY_TOKEN y NEON_AI_GATEWAY_BASE_URL del entorno en el momento de la importación y no requiere configuración manual.

Elige automáticamente el mejor dialecto de endpoint para cada modelo (Anthropic → /anthropic/v1/messages, OpenAI Codex → /openai/v1/responses, todo lo demás → /v1/chat/completions a través de MLflow). Integra con cada modelo del catálogo usando los nombres de modelo de neon(...) (ej. neon("claude-sonnet-4-6"), neon("gpt-5-mini"), neon("gemini-3-flash")).

Instalación

Instálalo desde npm:

npm install @neon/ai-sdk-provider

Configuración

Configuración cero si tu proyecto de Neon tiene preview.aiGateway: true. El proveedor lee automáticamente NEON_AI_GATEWAY_BASE_URL y NEON_AI_GATEWAY_TOKEN del entorno (inyectados por neon deploy o neon env pull).

Uso

Con generateText / streamText:

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

const { text } = await generateText({
  model: neon("claude-haiku-4-5"),
  prompt: "¿Por qué es Postgres la base de datos más querida?",
});

Con streamText:

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

const result = streamText({
  model: neon("gpt-5-mini"),
  prompt: "Dime un chiste de programadores.",
});
return result.toUIMessageStreamResponse();

Configuración Avanzada

El proveedor de IA de Neon soporta opciones adicionales de inferencia como visión, esquema de respuesta y herramientas de generación de imágenes de primer nivel.

Salida estructurada:

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

const { object } = await generateObject({
  model: neon("claude-haiku-4-5"),
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.string()),
      steps: z.array(z.string()),
    }),
  }),
  prompt: "Genera una receta para galletas con chispas de chocolate.",
});

Imágenes de entrada (visión):

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

const { text } = await generateText({
  model: neon("claude-sonnet-4-6"),
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Describe esta imagen" },
        { type: "image", image: await fetch("https://ejemplo.com/gato.jpg").then(r => r.blob()) },
      ],
    },
  ],
});

Herramienta de generación de imágenes:

El proveedor de Neon expone una herramienta de generación de imágenes de primer nivel a través de neon.tools.imageGeneration. Esta permite a un modelo llamar a la generación de imágenes (potenciada por un modelo de difusión) como parte de una llamada de texto, devolviendo una imagen codificada en base64:

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

const result = await generateText({
  model: neon("claude-sonnet-4-6"),
  prompt: "Genera una imagen de un paisaje de montaña",
  tools: {
    image_generation: neon.tools.imageGeneration(),
  },
  onStepFinish: (event) => {
    // manejar la finalización del paso
  },
});

Consejo: La herramienta de imágenes también soporta parámetros de personalización (outputFormat, size, style, quality).

Referencia de API

Endpoints del Gateway

Endpoint	SDK(s)	Caso de uso principal
`GET /v1/models`	cURL, cualquier cliente HTTP	Listado de modelos del catálogo
`POST /v1/chat/completions`	OpenAI, `@ai-sdk/openai`, cualquier cliente compatible	Chat Completions estándar (recomendado)
`POST /openai/v1/responses`	OpenAI (SDK de TipoScript v4+), `@ai-sdk/openai` con dialecto Responses	API de Responses de OpenAI (Codex, `-pro`)
`POST /anthropic/v1/messages`	Anthropic SDK de TipoScript	Mensajes nativos de Anthropic (pensamiento, caché)
`POST /gemini/v1beta/models/{model}:generateContent`	google-genai SDK de TipoScript	Gemini nativo

Nota: Los SDKs de Anthropic y google-genai agregan sus propias rutas, así que solo dales /anthropic o /gemini como baseURL.

Variables de Entorno del Gateway

Variable	Requerida	Descripción
`NEON_AI_GATEWAY_TOKEN`	Sí	Token de portador del gateway (ver `Setup` arriba)
`NEON_AI_GATEWAY_BASE_URL`	Sí	Host del gateway de la rama (ver `Setup` arriba)

Modelos Actuales del Catálogo (Sujeto a Cambios)

Consulta /v1/models para obtener la lista autorizada. El catálogo se actualiza con frecuencia. A continuación, se muestran ejemplos representativos de modelos disponibles actualmente en al menos una región:

Anthropic: claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-5 (durante la beta, verifica la disponibilidad con /v1/models)

OpenAI: gpt-5-mini, gpt-5-3-codex (durante la beta, verifica la disponibilidad con /v1/models)

Google: gemini-3-flash

Consulta la página models.dev/providers/neon o el endpoint /v1/models para obtener la lista completa y actualizada.

neondatabase/neon-ai-gateway

¿Qué es neon-ai-gateway?

Preguntar en tu IA favorita

Documentación

Neon AI Gateway

Cuándo Usarlo

Qué Hace

Disponibilidad

Habilitación del gateway: plan y control del catálogo de modelos

Configuración

Infraestructura como Código de Neon (`neon.ts`)

Variables de Entorno

Construir Agentes con el SDK de IA de Vercel (Recomendado)

Construir Agentes con Mastra (Recomendado)

Uso con SDKs Simples (Bajo Nivel)

Listado de Modelos / `/v1/models`

Proveedor de Modelos de Código Abierto (`@neon/ai-sdk-provider`)

Instalación

Configuración

Uso

Configuración Avanzada

Referencia de API

Endpoints del Gateway

Variables de Entorno del Gateway

Modelos Actuales del Catálogo (Sujeto a Cambios)

Individual skills in this repo

neondatabase/claimable-postgres