PREMIEREMENT : Utilisez le skill parent neon pour un aperçu de Neon, la prise en main, les bonnes pratiques de développement Neon, et plus encore.
Si le skill neon n'est pas installé, récupérez-le depuis https://neon.com/docs/ai/skills/neon/SKILL.md ou installez-le avec :
npx skills add neondatabase/agent-skills --skill neon
Passerelle IA Neon
Il s'agit d'une fonctionnalité bêta publique, actuellement disponible dans us-east-2 et eu-central-1.
La Passerelle IA Neon est la couche d'inférence LLM intégrée à votre branche Neon : une seule API et un seul identifiant Neon vous donnent accès aux modèles frontière et open source de nombreux fournisseurs (Anthropic, OpenAI, Google, Meta, etc.), tous hébergés et propulsés par Databricks. Le catalogue évolue au fil du temps, donc traitez /v1/models et la page models.dev de Neon comme source de vérité plutôt qu'une liste fixe de fournisseurs. Votre SDK OpenAI/Anthropic/Gemini existant fonctionne en changeant uniquement l'URL de base.
Utilisez ce skill pour aider l'utilisateur à envoyer des appels de modèle via la passerelle, à l'intégrer avec l'AI SDK ou Mastra, et à changer de fournisseur sans réécrire le code. Fournissez une requête d'inférence fonctionnelle, un agent configuré ou une réponse précise issue de la documentation officielle de Neon.
Quand l'utiliser
Utilisez la Passerelle IA chaque fois qu'une application ou un agent a besoin d'appeler un LLM et que l'utilisateur préfère ne pas gérer lui-même les fournisseurs de modèles :
- Un seul identifiant au lieu de plusieurs comptes fournisseurs. Un seul identifiant Neon donne accès à l'ensemble du catalogue de modèles, tous fournisseurs confondus, hébergés par Databricks. Pas besoin de facturations, clés ou inscriptions séparées pour OpenAI / Anthropic / Google, ni de rotations.
- Changez de modèles sans réécrire. Le point d'accès unifié est compatible OpenAI et fonctionne avec tous les modèles du catalogue — changez simplement le champ
modelpour passer de Claude à GPT ou Gemini. Les SDK standard (OpenAI, Anthropic, google-genai) fonctionnent avec un simple changement de l'URL de base. - L'IA suit vos branches. Chaque branche a son propre point d'accès à la passerelle, avec la même portée que votre base de données. Les requêtes IA provenant d'une branche d'aperçu/fonctionnalité sont isolées à cette branche — la même isolation dont bénéficient déjà vos données — ce qui rend les environnements d'aperçu, CI et d'agents autonomes.
- Aucune infrastructure supplémentaire, et déjà à côté de vos données. La passerelle vit à l'intérieur de votre projet Neon (et est injectée automatiquement dans les Fonctions Neon), s'exécute sur la même infrastructure Databricks qui sert des billions de jetons par mois, et prend en charge le streaming (SSE) par défaut.
Si l'utilisateur a déjà une intégration profonde avec un seul fournisseur et n'est pas intéressé par le branching Neon ou le routage multi-modèle, un SDK fournisseur direct est suffisant — mais dès qu'il souhaite un seul identifiant, une portabilité des modèles ou une IA limitée à une branche, c'est la raison d'utiliser cette passerelle.
Ce qu'elle fait
- Une seule API pour tous les modèles — Modèles frontière et open source derrière un point d'accès unique, adressés par leur ID de catalogue (par exemple
claude-sonnet-4-6,gpt-5-mini,gemini-3-flash). - SDK standard, un changement d'URL — SDK OpenAI et AI SDK (routes OpenAI-compatibles MLflow/Responses), SDK Anthropic (Messages natifs), google-genai (Gemini natif).
- Limitée à une branche — Chaque branche obtient son propre hôte de passerelle ; l'identifiant Neon autorise les requêtes pour cette branche et ses descendants.
- Streaming — Les événements envoyés par le serveur fonctionnent sur tous les points d'accès sans configuration supplémentaire.
Disponibilité
Vérifiez ces préconditions avant de configurer quoi que ce soit :
La Passerelle IA est une fonctionnalité bêta publique actuellement disponible dans us-east-2 et eu-central-1. L'accès aux modèles de fondation nécessite un plan Neon payant. Confirmez que le projet de l'utilisateur se trouve dans l'une de ces régions.
Activation de la passerelle : plan et catalogue de modèles
La Passerelle IA est limitée par identifiant plutôt que par une étape de provisionnement, mais deux limites (plan/bêta) la contrôlent — l'une bloque le provisionnement, l'autre réduit uniquement le catalogue — et le CLI les signale :
- Plan gratuit → provisionnement bloqué.
neon config apply/deployetneon checkoutrefusent d'activer la passerelle sur un plan gratuit (la passerelle ne peut pas y servir de requêtes), avec une erreur amicale "passez à un plan payant, ou supprimezpreview.aiGateway". Unneon config planà sec etneon env pullne provisionnent pas, donc ils avertissent seulement. Donc : pour utiliser la passerelle, le compte du projet doit être sur un plan Neon payant. - Plan payant avec un catalogue de modèles réduit. Sur un plan payant, la passerelle provisionne et sert, mais pendant la bêta un compte peut commencer avec un catalogue réduit — certains modèles phares (par exemple Anthropic Opus, OpenAI Codex /
*-pro) sont absents deGET /v1/models. C'est normal ;neon env pull(et leenv pullintégré dansapply/deploy/checkout) avertit et redirige l'utilisateur vers la page de la Passerelle IA de sa branche dans la Console Neon (https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway) pour demander l'accès à plus de modèles. Vérifiez ce qui est réellement disponible pour la branche en lisant/v1/models(voir la section sur les modèles ci-dessous) plutôt que de supposer le catalogue complet.
Lorsque vous aidez un utilisateur à déboguer "la passerelle ne fonctionne pas" ou "un modèle manque", utilisez /v1/models ainsi que le plan du compte pour distinguer ces deux cas — un plan gratuit bloque complètement le provisionnement, tandis qu'un catalogue réduit sur un plan payant nécessite simplement une demande d'accès aux modèles.
Configuration
La passerelle fait partie de neon.ts (voir le skill neon pour le flux de travail basé sur les branches et les bases de neon.ts). Activez-la sous preview.aiGateway :
// neon.ts
import { defineConfig } from "@neon/config/v1";
export default defineConfig({
preview: {
aiGateway: true,
},
});
neon deploy # provisionne la passerelle sur la branche liée
Infrastructure en tant que code Neon (neon.ts)
Le bouton preview.aiGateway ci-dessus fait partie de neon.ts, le fichier d'infrastructure en tant que code de Neon — un seul fichier TypeScript déclare la passerelle à côté de tous les autres services de la branche, dans le contrôle de version (voir le skill neon pour la référence complète). Reconciliez-le avec une branche à la manière de Terraform :
neon config status # affiche la configuration en direct de la branche (la passerelle est-elle activée ?)
neon config plan # différence à sec de ce que apply changerait
neon config apply # active la passerelle sur la branche (neon deploy est un alias)
La passerelle est limitée à une branche : chaque branche a son propre hôte de passerelle. Lorsqu'un neon.ts est présent, neon checkout applique la politique lors de la création d'une branche, donc une nouvelle branche d'aperçu/CI démarre avec la passerelle déjà activée. L'extraction d'une branche existante ne la reconcilie pas — exécutez neon deploy pour appliquer les modifications. Le provisionnement (config apply / deploy), link et checkout extraient également les identifiants de la passerelle de la branche dans votre .env.local local, de sorte que les exécutions locales atteignent la même passerelle de branche que la fonction déployée (pas besoin de env pull manuel).
Variables d'environnement
Lorsque preview.aiGateway est activé, Neon injecte les identifiants de la passerelle en tant que variables d'environnement marquées Neon. À l'intérieur d'une Fonction Neon déployée, elles sont injectées automatiquement ; localement, neon env pull les écrit dans .env/.env.local (ou utilisez neon-env run -- <cmd> pour injecter à l'exécution sans fichier) :
| Variable | Signification |
|---|---|
NEON_AI_GATEWAY_TOKEN | Jeton porteur de la passerelle (un identifiant Neon, nt_live_...) |
NEON_AI_GATEWAY_BASE_URL | Hôte nu de la passerelle de la branche (scheme://host, sans chemin – pas de /ai-gateway) : https://<branch-id>-api.ai.<region>.aws.neon.tech |
Neon injecte uniquement ces deux variables — il ne définit pas
OPENAI_API_KEY/OPENAI_BASE_URL.@neon/ai-sdk-provideret Mastra'sneon/<model>lisentNEON_AI_GATEWAY_*directement (zéro configuration) ; pour le SDK OpenAI standard /@ai-sdk/openai, construisezapiKey+baseURLdu client à partir de celles-ci (montré ci-dessous), ou définissez vos propresOPENAI_*manuellement (env pulllaisse les variables définies par l'utilisateur intactes).
NEON_AI_GATEWAY_BASE_URL est l'hôte nu — vous ajoutez vous-même le chemin du dialecte (c'est exactement ce que @neon/ai-sdk-provider fait pour vous). Les routes sous l'hôte sont :
/v1— Unifié, compatible OpenAI Chat Completions ; recommandé par défaut, fonctionne avec tous les fournisseurs (/v1/chat/completions)./openai/v1— API Responses OpenAI (nécessaire pour les variantesgpt-5-…-codexetgpt-5-5-pro) ; le fournisseur@ai-sdk/openaiutilise l'API Responses par défaut (/openai/v1/responses)./anthropic— Messages Anthropic natifs (réflexion étendue, mise en cache des invites). Donnez cette URL de base au SDK Anthropic et il ajoute lui-même/v1/messages, donc le chemin de requête complet est/anthropic/v1/messages./gemini—generateContentGemini natif. Donnez cette URL de base à google-genai et il ajoute lui-même/v1beta/models/<model>:generateContent, donc le chemin de requête complet est/gemini/v1beta/models/<model>:generateContent.
Donc ${NEON_AI_GATEWAY_BASE_URL}/v1 est le point d'accès chat-completions et ${NEON_AI_GATEWAY_BASE_URL}/openai/v1 le point d'accès OpenAI Responses (tous deux ajoutés par vous) ; pour les dialectes Anthropic et Gemini natifs, vous donnez au SDK la base plus courte /anthropic ou /gemini et il ajoute le reste. Voir Utilisation avec les SDK standard (bas niveau) ci-dessous.
Pour un accès typé et validé aux identifiants injectés, passez le même objet de configuration neon.ts à parseEnv de @neon/env — il renvoie un espace de noms env.aiGateway (apiKey, baseUrl) dérivé de votre configuration.
Construire des agents avec l'AI SDK Vercel (Recommandé)
L'AI SDK Vercel est la méthode recommandée pour appeler la passerelle et construire des agents en TypeScript : un ensemble de primitives (generateText, streamText, appel d'outils, sortie structurée) pour tous les modèles du catalogue, avec un streaming de première classe pour les réponses longues d'agents que les Fonctions Neon sont conçues pour héberger.
Le @neon/ai-sdk-provider dédié lit NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN depuis les env injectés avec zéro configuration et achemine chaque modèle vers le meilleur point d'accès (Anthropic → Messages, OpenAI/Codex → Responses, tout le reste → MLflow). Sur une Fonction Neon qui diffuse du texte et génère des images, choisissez simplement un modèle du catalogue :
import { neon } from "@neon/ai-sdk-provider";
import { streamText } from "ai";
const result = streamText({
model: neon("gpt-5-mini"), // ou claude-sonnet-4-6, gemini-3-flash, ...
messages,
tools: {
image_generation: neon.tools.imageGeneration({
outputFormat: "jpeg",
size: "1024x1024",
}),
},
});
return result.toUIMessageStreamResponse();
Une simple complétion utilise le même fournisseur avec generateText :
import { neon } from "@neon/ai-sdk-provider";
import { generateText } from "ai";
const { text } = await generateText({
model: neon("claude-haiku-4-5"), // ou gpt-5-3-codex, gemini-3-flash, ...
prompt: "Résumez-moi Postgres.",
});
Préférez
@neon/ai-sdk-providerauopenai()nu de@ai-sdk/openai: Neon injecte uniquementNEON_AI_GATEWAY_*, pasOPENAI_*, doncopenai()ne récupérera pas la passerelle depuis l'env tout seul. Si vous utilisez@ai-sdk/openai, configurez-le explicitement aveccreateOpenAI({ apiKey: process.env.NEON_AI_GATEWAY_TOKEN, baseURL:${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1}).
Pour construire un agent — un modèle qui appelle des outils en boucle puis répond — ajoutez des tools et un budget stopWhen. La boucle s'exécute dans le processus, donc sur une Fonction Neon elle n'est pas interrompue par les délais d'attente de type 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: "Combien de tâches ouvertes ai-je, et quelle est la plus ancienne ?",
tools: {
listTodos: tool({
description: "Liste les tâches ouvertes de l'utilisateur.",
inputSchema: z.object({}), // AI SDK v5+ : `inputSchema`, pas `parameters`
execute: async () => db.select().from(todos),
}),
},
stopWhen: stepCountIs(5), // laissez le modèle appeler des outils, puis résumer
});
Pour un agent AI SDK complet déployé en tant que Fonction Neon (streaming, appel d'outils, génération d'images, persistance), consultez le skill neon-functions dans sa section references/ai-sdk.md.
Construire des agents avec Mastra (Recommandé)
Mastra est le framework recommandé lorsque vous souhaitez des agents prêts à l'emploi — mémoire intégrée, outils, workflows et traçage — avec le modèle toujours pointé vers la passerelle. Avec @mastra/core 1.47+, utilisez une chaîne magique neon/<model> ; Mastra lit NEON_AI_GATEWAY_BASE_URL et NEON_AI_GATEWAY_TOKEN depuis l'environnement (injectés par neon deploy lorsque preview.aiGateway est activé). Utilisez parseEnv uniquement pour les autres services déclarés (par exemple env.postgres.databaseUrl pour la mémoire @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:
"Vous êtes un assistant personnel chaleureux et concis avec une mémoire à long terme.",
model: "neon/claude-haiku-4-5",
memory, // votre stockage mémoire Mastra, par exemple @mastra/pg sur env.postgres.databaseUrl
});
Utilisation avec les SDK standard (bas niveau)
Lorsque vous n'avez pas besoin d'un framework d'agent — une seule complétion, une intégration SDK fournisseur existante ou des fonctionnalités natives du fournisseur — appelez la passerelle avec les SDK standard. Neon injecte les variables NEON_AI_GATEWAY_* (pas OPENAI_*), donc définissez apiKey + baseURL du client à partir de celles-ci. Pour le dialecte Responses d'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 completion = await client.responses.create({
model: "gpt-5-3-codex", // ID du catalogue
input: "Rédige un email de bienvenue pour un nouveau client.",
});
Pour le dialecte Chat Completions (/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 completion = await client.chat.completions.create({
model: "claude-sonnet-4-6",
messages: [{ role: "user", content: "Quelle est la capitale du Sénégal ?" }],
});
Pour le SDK 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`,
});
const message = await client.messages.create({
model: "claude-haiku-4-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Explique la réplication logique Postgres." }],
});
Pour le SDK Google Generative AI :
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: "Qu'est-ce que l'indexation partielle dans Postgres ?",
});
Liste des modèles
L'ID de modèle correct pour le point d'accès unifié n'est pas le nom du fournisseur — il s'agit d'un ID de catalogue normalisé (par exemple claude-sonnet-4-6, gpt-5-mini, gemini-3-flash). Récupérez toujours le catalogue en direct d'une branche plutôt que de coder en dur les ID :
curl -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
"${NEON_AI_GATEWAY_BASE_URL}/v1/models"
Important : Le catalogue peut être réduit pendant la bêta — voir Disponibilité ci-dessus. Si un modèle est absent, demandez l'accès via la page de la Passerelle IA de la branche dans la Console Neon (
https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway).
Règles de la requête d'inférence
- Utilisez l'AI SDK Vercel ou Mastra pour les agents. Pour les agents multi-outils avec streaming, préférez
@neon/ai-sdk-providerou la chaîne magiqueneon/<model>de Mastra. Un simplegenerateTextoustreamText(AI SDK) fonctionne en une seule ligne — préférez cela à la construction manuelle des appels SDK. Pour les intégrations SDK standard existantes, utilisez les extraits ci-dessus. - N'inventez pas les ID de modèle. Utilisez un ID de catalogue vérifié depuis
/v1/modelsou la pagemodels.devde Neon. Les ID courants incluentclaude-sonnet-4-6,claude-haiku-4-5,gpt-5-mini,gpt-5-3-codex,gemini-3-flash. Ne devinez pas les noms de modèle. - N'inventez pas les points d'accès. Les routes du dialecte sont fixes :
/v1(Chat Completions),/openai/v1(Responses),/anthropic(Messages natifs),/gemini(Gemini natif). Chaque SDK reçoit une base URL différente. Ne composez jamais de chemins arbitraires sousNEON_AI_GATEWAY_BASE_URL. - Confirmez la région avant le code. Vérifiez que le projet se trouve dans
us-east-2oueu-central-1; si ce n'est pas le cas, l'utilisateur doit déployer un nouveau projet dans une région prise en charge avant de configurer la passerelle. - Ne fournissez pas d'identifiants.
NEON_AI_GATEWAY_TOKENcontient un secret. Utilisez-le dans les extraits de code mais ne l'imprimez jamais, ne le connectez jamais et ne le renvoyez jamais comme réponse à l'utilisateur. - Déléguez au skill
neonpour le flux de travail des branches. Le provisionnement de la passerelle (preview.aiGateway),neon deploy,neon config *etneon checkoutsont documentés dans le skill parentneon.