neon-ai-gateway

Par neondatabase · agent-skills

Une seule API et un seul credential pour les LLM frontier et open-source, intégrés à votre branche Neon et alimentés par Databricks. À utiliser lorsqu'un utilisateur souhaite appeler un LLM, ajouter de l'IA/chat/un agent à son application, router entre différents fournisseurs de modèles (OpenAI, Anthropic, Google/Gemini, Meta, Alibaba, DeepSeek), ou éviter de jongler avec des clés API et comptes fournisseurs séparés — en particulier s'il utilise déjà Neon et souhaite que les requêtes IA suivent les branches de son projet. Compatible avec l'OpenAI SDK, l'Anthropic SDK, google-genai, le Vercel AI SDK et Mastra en changeant uniquement la base URL. Les déclencheurs incluent « call an LLM », « add AI to my app », « chat completion », « model routing », « LLM proxy/gateway », « one API for all models », « use Claude/GPT/Gemini », « AI SDK », « Mastra agent », « Neon AI Gateway », et « log/rate-limit AI calls ».

npx skills add https://github.com/neondatabase/agent-skills --skill neon-ai-gateway

Neon AI Gateway

Il s'agit d'une fonctionnalité en bêta publique disponible uniquement dans us-east-2. Neon AI Gateway est la couche d'inférence LLM intégrée à votre branche Neon : une API et une seule credential Neon vous donnent accès aux modèles de pointe et open-source d'Anthropic, OpenAI, Google, Meta, Alibaba, DeepSeek et Databricks — alimentés par Databricks. Votre SDK OpenAI/Anthropic/Gemini existant fonctionne en changeant uniquement l'URL de base.

Utilisez cette skill pour aider l'utilisateur à envoyer des appels de modèle via la gateway, l'intégrer au SDK IA ou Mastra, et changer de fournisseur sans réécrire le code. Livrez une requête d'inférence fonctionnelle, un agent configuré, ou une réponse précise tirée de la documentation officielle de Neon.

Quand l'utiliser

Recourez à AI Gateway chaque fois qu'une application ou un agent doit appeler un LLM et que l'utilisateur préfère ne pas gérer les fournisseurs de modèles lui-même :

  • Une credential au lieu de plusieurs comptes de fournisseur. Une seule credential Neon accède au catalogue entier de modèles sur sept fournisseurs. Pas de facturation, de clés ou d'inscriptions séparées chez OpenAI / Anthropic / Google à provisionner et faire tourner.
  • Changer de modèle sans réécrire le code. L'endpoint unifié est compatible OpenAI et fonctionne avec chaque modèle du catalogue — changez un seul champ model pour passer entre Claude, GPT et Gemini. Les SDK standard (OpenAI, Anthropic, google-genai) fonctionnent avec juste un changement d'URL de base.
  • L'IA suit vos branches. Chaque branche a son propre endpoint gateway, limité à la même lignée que votre base de données. Les requêtes IA d'une branche de preview/feature sont isolées à cette branche — le même isolement que vos données — ce qui rend les environnements de preview, CI et agent autonomes.
  • Aucune infrastructure supplémentaire, et c'est déjà à côté de vos données. La gateway réside dans votre projet Neon (et s'injecte automatiquement dans Neon Functions), s'exécute sur la même infrastructure Databricks qui sert des trillions de tokens par mois, et supporte le streaming (SSE) dès le départ.

Si l'utilisateur a déjà une intégration monofournisseur approfondie et n'a pas d'intérêt pour le branchement Neon ou le routage multi-modèle, un SDK fournisseur direct convient — mais au moment où il veut une credential, la portabilité des modèles, ou l'IA limitée à la branche, voilà la raison de l'utiliser.

Ce qu'il fait

  • Une API pour tous les modèles — Modèles de pointe et open-source derrière un endpoint unique, adressés par leur ID de catalogue (par exemple claude-sonnet-4-6, gpt-5-mini, gemini-2-5-flash).
  • SDK standard, changement d'URL unique — SDK OpenAI et AI SDK (routes MLflow/Responses compatibles OpenAI), SDK Anthropic (Messages natif), google-genai (Gemini natif).
  • Limité à la branche — Chaque branche obtient son propre host gateway ; la credential Neon autorise les requêtes pour cette branche et ses descendants.
  • Streaming — Les événements envoyés par le serveur fonctionnent sur tous les endpoints sans configuration supplémentaire.

Configuration

La gateway fait partie de neon.ts (voir la skill neon pour le workflow branch-first 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 gateway sur la branche liée

Infrastructure en tant que code Neon (neon.ts)

Le toggle preview.aiGateway ci-dessus fait partie de neon.ts, le fichier d'infrastructure en tant que code de Neon — un fichier TypeScript déclare la gateway aux côtés de tous les autres services de branche, en contrôle de version (voir la skill neon pour la référence complète). Réconciliez-le avec une branche à la manière de Terraform :

neon config status   # affiche la config en direct de la branche (la gateway est-elle activée ?)
neon config plan     # dry-run diff de ce que apply changerait
neon config apply    # active la gateway sur la branche  (neon deploy est un alias)

La gateway est limitée à la branche : chaque branche obtient son propre host gateway. Quand un neon.ts est présent, neon checkout applique la politique au moment de créer une branche, donc une branche de preview/CI fraîche arrive avec la gateway déjà activée. Vérifier une branche existante ne la réconcilie pas — lancez neon deploy pour appliquer les changements. Le provisionnement (config apply / deploy), link et checkout tirent aussi les credentials de la gateway de la branche dans votre .env.local local, donc les exécutions locales frappent la même gateway de branche que la fonction déployée (pas besoin de env pull manuel).

Pour un accès typé et validé aux credentials injectées, passez le même objet de config à parseEnv depuis @neon/env — il retourne un namespace env.aiGateway (apiKey, baseUrl) dérivé de votre neon.ts.

Variables d'environnement

Quand preview.aiGateway est activé, Neon injecte les credentials de la gateway comme variables d'env de marque Neon. À l'intérieur d'une fonction Neon déployée elles s'injectent 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 Sens
NEON_AI_GATEWAY_TOKEN Token porteur de la gateway (une credential Neon, nt_live_...)
NEON_AI_GATEWAY_BASE_URL Host de branche gateway nu (scheme://host, pas de chemin — pas de /ai-gateway) : https://<branch-id>-api.ai.<region>.aws.neon.tech

Neon n'injecte que ces deux variables — il ne définit pas OPENAI_API_KEY / OPENAI_BASE_URL. Le @neon/ai-sdk-provider et le neon/<model> de Mastra lisent NEON_AI_GATEWAY_* directement (zéro config) ; pour le SDK OpenAI plain / @ai-sdk/openai, construisez le apiKey + baseURL du client à partir d'eux (montré ci-dessous), ou définissez vos propres OPENAI_* à la main (env pull laisse les variables définies par l'utilisateur intactes).

NEON_AI_GATEWAY_BASE_URL est le host nu — vous ajoutez vous-même le chemin du dialecte (ce que le @neon/ai-sdk-provider fait exactement pour vous). Les routes sous le host sont :

  • /v1 — unifié, compatible OpenAI Chat Completions ; défaut recommandé, fonctionne avec chaque fournisseur (/v1/chat/completions).
  • /openai/v1 — OpenAI Responses API (requis pour les variantes gpt-5-…-codex et gpt-5-5-pro) ; le provider @ai-sdk/openai utilise par défaut l'API Responses (/openai/v1/responses).
  • /anthropic/v1 — Messages Anthropic natifs (extended thinking, prompt caching) ; reflète le chemin réel de l'API Anthropic (/anthropic/v1/messages).
  • /ai-gateway/gemini/v1beta/... — Gemini natif generateContent (ce dialecte est toujours servi sous le préfixe hérité /ai-gateway/).

Ainsi ${NEON_AI_GATEWAY_BASE_URL}/v1 est l'endpoint chat-completions, ${NEON_AI_GATEWAY_BASE_URL}/openai/v1 l'endpoint OpenAI Responses, et ainsi de suite.

Pour un accès typé, parseEnv (depuis @neon/env) retourne env.aiGateway (apiKey, baseUrl) dérivé de votre neon.ts.

Construire des agents avec le Vercel AI SDK (recommandé)

Le Vercel AI SDK est le moyen recommandé d'appeler la gateway et de construire des agents depuis TypeScript : un ensemble de primitives (generateText, streamText, tool calling, structured output) sur chaque modèle du catalogue, avec streaming first-class pour les longues réponses d'agent que les Neon Functions sont construites pour héberger.

Le @neon/ai-sdk-provider dédié lit NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN depuis l'env injectée avec zéro config et route chaque modèle vers le meilleur endpoint (Anthropic → Messages, OpenAI/Codex → Responses, tout le reste → MLflow). Sur une Neon Function qui stream du texte et génère des images, choisissez juste 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-2-5-flash, ...
  messages,
  tools: {
    image_generation: neon.tools.imageGeneration({
      outputFormat: "jpeg",
      size: "1024x1024",
    }),
  },
});
return result.toUIMessageStreamResponse();

Une completion unique utilise le même provider 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-2-5-flash, ...
  prompt: "Résume Postgres pour moi.",
});

Préférez @neon/ai-sdk-provider au openai() plain @ai-sdk/openai : Neon n'injecte que NEON_AI_GATEWAY_*, pas OPENAI_*, donc openai() ne récupérera pas la gateway depuis l'env de lui-même. Si vous utilisez @ai-sdk/openai, configurez-le explicitement avec createOpenAI({ 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 tools en boucle puis répond — ajoutez tools et un budget stopWhen. La boucle s'exécute in-process, donc sur une Neon Function elle n'est pas coupée par les timeouts de style 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 todos ouverts ai-je, et quel est le plus ancien ?",
  tools: {
    listTodos: tool({
      description: "Liste les todos ouverts de l'utilisateur.",
      inputSchema: z.object({}), // AI SDK v5+: `inputSchema`, pas `parameters`
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // laisse le modèle appeler des tools, puis résume
});

Pour un agent AI SDK complet déployé en tant que Neon Function (streaming, tool calling, génération d'image, persistence), voir references/ai-sdk.md de la skill neon-functions.

Construire des agents avec Mastra (recommandé)

Mastra est le framework recommandé quand vous voulez des agents batterie-comprise — mémoire, tools, workflows et tracing intégrés — avec le modèle toujours pointé vers la gateway. 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ées par neon deploy quand 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:
    "You are a warm, concise personal assistant with long-term memory.",
  model: "neon/claude-haiku-4-5",
  memory,
});

Utiliser avec les SDK plain (niveau inférieur)

Quand vous n'avez pas besoin d'un framework d'agent — une completion unique, une intégration SDK-fournisseur existante, ou des fonctionnalités fournisseur natives — appelez la gateway avec les SDK plain. Neon injecte les variables NEON_AI_GATEWAY_* (pas OPENAI_*), donc définissez le apiKey + baseURL du client à partir d'elles. Pour le dialecte OpenAI Responses (/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 res = await client.responses.create({
  model: "gpt-5-mini", // changez pour claude-sonnet-4-6, gemini-2-5-flash, ...
  input: "Qu'est-ce que Neon ?",
});

Pour le dialecte unifié chat-completions, pointez baseURL vers /v1 à la place :

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

const res = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Qu'est-ce que Neon ?" }],
});

Le SDK Anthropic et google-genai fonctionnent de la même manière pour les fonctionnalités fournisseur natives — pointez le SDK Anthropic vers ${NEON_AI_GATEWAY_BASE_URL}/anthropic/v1 (reflète le chemin réel de l'API Anthropic, donc /anthropic/v1/messages) et google-genai vers ${NEON_AI_GATEWAY_BASE_URL}/ai-gateway/gemini (Gemini est toujours servi sous le préfixe hérité /ai-gateway/).

Identifiants de modèle

Utilisez l'ID de catalogue d'un modèle directement dans le champ model — par exemple claude-sonnet-4-6, gpt-5-mini, gemini-2-5-flash. Aucun préfixe de fournisseur n'est nécessaire. Pour rechercher les identifiants exacts que la gateway sert, le modèle sous-jacent auquel chacun mappe, et leurs context windows, tarification et capacités, utilisez l'un des :

  • Page du fournisseur Neon sur models.dev : https://models.dev/providers/neon — la liste canonique et toujours actuelle des ID de modèle du fournisseur Neon et leurs modèles sous-jacents. Le catalogue lisible par machine est à https://models.dev/api.json (la clé neon).
  • Doc Models : voir Lectures complémentaires.

Lister les modèles disponibles à l'exécution (/v1/models)

La gateway expose aussi le catalogue de modèles en direct depuis votre propre endpoint de branche, donc une application ou un agent peut découvrir exactement quels modèles cette branche sert sans coder en dur la liste. C'est un endpoint de liste compatible OpenAI, servi uniquement sur le dialecte unifié (/v1) :

curl "$NEON_AI_GATEWAY_BASE_URL/v1/models" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN"
  • GET ${NEON_AI_GATEWAY_BASE_URL}/v1/models → 200
  • GET ${NEON_AI_GATEWAY_BASE_URL}/openai/v1/models → 404 (non servi sur le dialecte Responses — utilisez /v1)

Obtenir les credentials pour la requête. Les deux valeurs proviennent de la même credential Neon limitée à la branche que la gateway utilise partout ailleurs — vous ne gérez jamais de clé de fournisseur :

  • Provisionner via neon.ts (recommandé). Activez preview.aiGateway dans neon.ts et lancez neon deploy (ou neon config apply). Le provisionnement, neon link et neon checkout tirent NEON_AI_GATEWAY_TOKEN + NEON_AI_GATEWAY_BASE_URL dans votre .env.local local ; à l'intérieur d'une Neon Function déployée elles s'injectent automatiquement. Voir Configuration et Variables d'environnement ci-dessus.
  • Tirer dans l'environnement via CLI. Sur une branche qui a déjà la gateway activée, neon env pull écrit les deux variables dans .env/.env.local, ou neon-env run -- <cmd> les injecte à l'exécution sans fichier.
  • Provisionner via la Console UI. Activez AI Gateway sur la branche dans la Console Neon et copiez l'URL de base gateway et une credential Neon (token) de la branche depuis la vue connection/credentials du projet.

Toute credential Neon (nt_live_...) valide pour la branche fonctionne comme le token porteur ; NEON_AI_GATEWAY_BASE_URL est le host de branche nu (pas de chemin).

Forme de la réponse — liste compatible OpenAI/OpenRouter :

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4-6",              // ID de modèle du catalogue — utilisez directement dans le champ `model`
      "canonical_slug": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",            // nom d'affichage lisible par l'humain
      "object": "model",
      "owned_by": "anthropic",                // anthropic | openai | google | meta | alibaba | databricks
      "created": 0,
      "enabled": true,
      "context_length": null,
      "architecture": {
        "modality": "text->text",
        "input_modalities": ["text"],
        "output_modalities": ["text"],
        "tokenizer": "Claude",                // Claude | Gemini | GPT | "" (vide pour open-source)
        "instruct_type": null
      },
      "top_provider": {
        "is_moderated": false,
        "context_length": null,
        "max_completion_tokens": null
      },
      "pricing": null,
      "per_request_limits": null
    }
    // ... une entrée par modèle dans le catalogue de la branche
  ]
}

Note : context_length, pricing et per_request_limits sont actuellement null et created est 0 pour chaque entrée — pour les context windows, la tarification et les capacités utilisez le catalogue models.dev ci-dessus. Utilisez /v1/models quand vous avez besoin de la liste en direct limitée à la branche des ID de modèle servables (par exemple pour remplir un sélecteur de modèle ou valider un model avant une requête).

Disponibilité

AI Gateway est une fonctionnalité en bêta publique disponible uniquement sur les nouveaux projets dans la région us-east-2 ; elle ne peut pas être activée sur les projets existants. L'accès aux modèles de fondation nécessite un plan Neon payant. Confirmez que le projet de l'utilisateur est un nouveau projet dans us-east-2.

Activation de la gateway : gating du plan et du catalogue de modèles

AI Gateway est credential-gatée plutôt qu'une étape de provisionnement, mais deux limites de plan/bêta la gatent — l'une bloque le provisionnement, l'autre ne fait que réduire le catalogue — et la CLI surface chacune :

  • Plan gratuit → le provisionnement est bloqué. neon config apply / deploy et neon checkout refusent d'activer la gateway sur un plan Free (la gateway ne peut pas servir de requêtes là), avec un message d'erreur amical « upgradez vers un plan payant, ou supprimez preview.aiGateway ». Un neon config plan dry-run et neon env pull ne provisionent pas, donc ils avertissent seulement. Donc : pour utiliser la gateway 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 gateway provisionne et sert, mais pendant la bêta un compte peut commencer avec un catalogue limité — certains modèles phare (par exemple Anthropic Opus, OpenAI Codex / *-pro) manquent du GET /v1/models. C'est attendu ; neon env pull (et l'env pull intégré à apply / deploy / checkout) avertit et met le lien utilisateur vers la page AI Gateway 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 modèles ci-dessus) plutôt que d'assumer le catalogue complet.

Quand vous aidez un utilisateur à déboguer « la gateway ne fonctionne pas » ou « un modèle manque », utilisez /v1/models plus le plan du compte pour distinguer ces deux cas — un plan Free bloque entièrement le provisionnement, tandis qu'un catalogue réduit sur un plan payant a juste besoin d'une demande d'accès au modèle.

Documentation Neon

La documentation Neon est la source de vérité et AI Gateway évolue rapidement, donc vérifiez toujours par rapport aux docs officielles. Toute page doc peut être récupérée en markdown en ajoutant .md à l'URL ou en demandant Accept: text/markdown. Trouvez la bonne page depuis l'index des docs (https://neon.com/docs/llms.txt) et les annonces du changelog.

Lectures complémentaires

Skills similaires

neon-ai-gateway
neondatabase / agent-skills

Accéder à plusieurs LLMs via une seule API unifiée intégrée à Neon.

81
claude-api
anthropics / skills

Construire des applications LLM avec Claude via le SDK officiel adapté au langage.

163 727
eval-bootstrap
datadog-labs / agent-skills

Générer du code d'évaluation Python à partir de traces de production LLM Datadog.

146
llm-obs-eval-pipeline
datadog-labs / agent-skills

Orchestrer un pipeline complet classify→RCA→bootstrap pour évaluer une app LLM en production.

146
llm-obs-experiment-py-bootstrap
datadog-labs / agent-skills

Générer un script Python ou notebook Jupyter d'expérimentation LLM avec ddtrace.llmobs.

146