Neon AI Gateway

Zuerst: Verwende das übergeordnete neon-Skill für eine Übersicht über Neon, erste Schritte mit Neon, Best Practices für die Entwicklung mit Neon und mehr.

Falls das neon-Skill nicht installiert ist, hole es von https://neon.com/docs/ai/skills/neon/SKILL.md oder installiere es mit:

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

Was macht Neon AI Gateway?

Dies ist ein öffentliches Beta-Feature, das derzeit in us-east-2 und eu-central-1 verfügbar ist.

Das Neon AI Gateway ist die LLM-Inferenzschicht, die in deinen Neon-Branch integriert ist: Eine API und ein Neon-Anmeldedatensatz geben dir Zugriff auf Frontier- und Open-Source-Modelle von vielen Anbietern (Anthropic, OpenAI, Google, Meta und mehr), die alle von Databricks gehostet und betrieben werden. Der Katalog ändert sich im Laufe der Zeit, daher betrachte /v1/models und die models.dev Neon-Seite als verbindliche Quelle und nicht eine feste Liste von Anbietern. Dein vorhandenes OpenAI/Anthropic/Gemini SDK funktioniert, indem du nur die Basis-URL änderst.

Verwende dieses Skill, um dem Benutzer zu helfen, Modellaufrufe über das Gateway zu senden, es in das AI SDK oder Mastra einzubinden und Anbieter zu wechseln, ohne Code umschreiben zu müssen. Liefere eine funktionierende Inferenzanfrage, einen konfigurierten Agenten oder eine präzise Antwort aus der offiziellen Neon-Dokumentation.

Wann verwenden

Greife auf das AI Gateway zurück, wann immer eine App oder ein Agent ein LLM aufrufen muss und der Benutzer nicht selbst die Modellanbieter verwalten möchte:

• Ein Anmeldedatensatz statt vieler Anbieterkonten. Ein einziger Neon-Anmeldedatensatz erreicht den gesamten Modellkatalog über alle Anbieter, die Databricks hostet. Keine separaten OpenAI/Anthropic/Google-Abrechnungen, Schlüssel oder Anmeldungen, die bereitgestellt und rotiert werden müssen.
• Modelle ohne Umbau wechseln. Der einheitliche Endpunkt ist OpenAI-kompatibel und funktioniert mit jedem Modell im Katalog – ändere ein model-Feld, um zwischen Claude, GPT und Gemini zu wechseln. Standard-SDKs (OpenAI, Anthropic, google-genai) funktionieren mit einer einfachen Änderung der Basis-URL.
• KI folgt deinen Branches. Jeder Branch hat seinen eigenen Gateway-Endpunkt, der mit derselben Abstammung wie deine Datenbank skaliert ist. KI-Anfragen aus einem Vorschau-/Feature-Branch sind auf diesen Branch isoliert – die gleiche Isolierung, die deine Daten bereits erhalten – was Vorschau-, CI- und Agentenumgebungen in sich geschlossen macht.
• Keine zusätzliche Infrastruktur, und es ist bereits neben deinen Daten. Das Gateway lebt innerhalb deines Neon-Projekts (und wird automatisch in Neon Functions injiziert), läuft auf derselben Databricks-Infrastruktur, die Billionen von Tokens pro Monat bedient, und unterstützt Streaming (SSE) von Haus aus.

Wenn der Benutzer bereits eine tiefe, einzelne Anbieterintegration hat und kein Interesse an Neon-Branching oder Multi-Modell-Routing hat, ist ein direktes Anbieter-SDK in Ordnung – aber sobald er einen einzigen Anmeldedatensatz, Modellportabilität oder Branch-gescopte KI möchte, ist dies der Grund, es zu verwenden.

Was es macht

• Eine API für alle Modelle – Frontier- und Open-Source-Modelle hinter einem einzigen Endpunkt, adressiert durch ihre Katalog-ID (z.B. claude-sonnet-4-6, gpt-5-mini, gemini-3-flash).
• Standard-SDKs, eine URL-Änderung – OpenAI SDK und AI SDK (OpenAI-kompatible MLflow/Responses-Routen), Anthropic SDK (native Messages), google-genai (natives Gemini).
• Branch-gescopt – Jeder Branch erhält seinen eigenen Gateway-Host; der Neon-Anmeldedatensatz autorisiert Anfragen für diesen Branch und seine Abkömmlinge.
• Streaming – Server-Sent-Events funktionieren auf allen Endpunkten ohne zusätzliche Konfiguration.

Verfügbarkeit

Überprüfe diese Vorbedingungen, bevor du etwas einrichtest:

Das AI Gateway ist ein öffentliches Beta-Feature, das derzeit in us-east-2 und eu-central-1 verfügbar ist. Der Zugriff auf Foundation-Modelle erfordert einen kostenpflichtigen Neon-Plan. Bestätige, dass sich das Projekt des Benutzers in einer dieser Regionen befindet.

Aktivierung des Gateways: Plan- und Modellkatalog-Gating

Das AI Gateway ist anmeldedaten-gesteuert und kein Bereitstellungsschritt, aber zwei Plan-/Beta-Limits steuern es – eines blockiert die Bereitstellung, das andere schränkt nur den Katalog ein – und die CLI zeigt jedes an:

• Kostenloser Plan → Bereitstellung ist blockiert. neon config apply / deploy und neon checkout weigern sich, das Gateway auf einem kostenlosen Plan zu aktivieren (das Gateway kann dort keine Anfragen bedienen), mit einem freundlichen Fehler "upgrade to a paid plan, or remove preview.aiGateway". Ein Dry-Run neon config plan und neon env pull stellen nichts bereit, also warnen sie nur. Also: Um das Gateway zu verwenden, muss das Konto des Projekts einen kostenpflichtigen Neon-Plan haben.
• Kostenpflichtiger Plan mit reduziertem Modellkatalog. Auf einem kostenpflichtigen Plan stellt das Gateway bereit und bedient, aber während der Beta kann ein Konto mit einem reduzierten Katalog beginnen – einige Flaggschiff-Modelle (z.B. Anthropic Opus, OpenAI Codex / *-pro) fehlen in GET /v1/models. Dies ist erwartet; neon env pull (und das env pull, das in apply / deploy / checkout integriert ist) warnt und verlinkt den Benutzer zur AI Gateway-Seite seines Branches in der Neon-Konsole (https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway), um Zugriff auf weitere Modelle zu beantragen. Überprüfe, was für den Branch tatsächlich verfügbar ist, indem du /v1/models liest (siehe den Abschnitt zu Modellen unten), anstatt den vollständigen Katalog anzunehmen.

Wenn du einem Benutzer hilfst, zu debuggen, "das Gateway funktioniert nicht" oder "ein Modell fehlt", verwende /v1/models plus den Plan des Kontos, um diese beiden Fälle zu unterscheiden – ein kostenloser Plan blockiert die Bereitstellung vollständig, während ein reduzierter Katalog auf einem kostenpflichtigen Plan nur eine Modellzugriffsanfrage benötigt.

Einrichtung

Das Gateway ist Teil von neon.ts (siehe das neon-Skill für den Branch-First-Workflow und neon.ts-Grundlagen). Aktiviere es unter preview.aiGateway:

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

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

neon deploy   # provisions the gateway on the linked branch

Neon Infrastructure as Code (neon.ts)

Der obige preview.aiGateway-Schalter ist Teil von neon.ts, Neons Infrastructure-as-Code-Datei – eine TypeScript-Datei deklariert das Gateway zusammen mit jedem anderen Branch-Dienst in der Versionskontrolle (siehe das neon-Skill für die vollständige Referenz). Gleiche es mit einem Branch auf die Terraform-Art ab:

neon config status   # print the branch's live config (is the gateway on?)
neon config plan     # dry-run diff of what apply would change
neon config apply    # enable the gateway on the branch  (neon deploy is an alias)

Das Gateway ist Branch-gescopt: Jeder Branch erhält seinen eigenen Gateway-Host. Wenn eine neon.ts vorhanden ist, wendet neon checkout die Richtlinie an, während es einen Branch erstellt, sodass ein neuer Vorschau-/CI-Branch mit bereits aktiviertem Gateway hochkommt. Das Auschecken eines bestehenden Branch gleicht es nicht ab – führe neon deploy aus, um Änderungen anzuwenden. Die Bereitstellung (config apply / deploy), link und checkout ziehen auch die Gateway-Anmeldeinformationen des Branch in dein lokales .env.local, sodass lokale Ausführungen denselben Branch-Gateway treffen wie die bereitgestellte Funktion (kein manuelles env pull erforderlich).

Umgebungsvariablen

Wenn preview.aiGateway aktiviert ist, injiziert Neon die Gateway-Anmeldeinformationen als Neon-gebränderte Umgebungsvariablen. Innerhalb einer bereitgestellten Neon Function werden diese automatisch injiziert; lokal schreibt neon env pull sie in .env/.env.local (oder verwende neon-env run -- <cmd>, um sie zur Laufzeit ohne Datei zu injizieren):

Variable	Bedeutung
NEON_AI_GATEWAY_TOKEN	Gateway Bearer-Token (ein Neon-Anmeldedatensatz, nt_live_...)
NEON_AI_GATEWAY_BASE_URL	Nackter Branch-Gateway-Host (scheme://host, kein Pfad — kein /ai-gateway): https://<branch-id>-api.ai.<region>.aws.neon.tech

Neon injiziert nur diese beiden Variablen – es setzt nicht OPENAI_API_KEY / OPENAI_BASE_URL. Der @neon/ai-sdk-provider und Mastras neon/<model> lesen NEON_AI_GATEWAY_* direkt (Nullkonfiguration); für das einfache OpenAI SDK / @ai-sdk/openai baue die Schlüssel apiKey + baseURL des Clients daraus (siehe unten), oder setze deine eigenen OPENAI_* von Hand (env pull lässt benutzergesetzte Variablen unberührt).

NEON_AI_GATEWAY_BASE_URL ist der nackte Host – du hängst den Dialektpfad selbst an (was genau das ist, was der @neon/ai-sdk-provider für dich tut). Die Routen unter dem Host sind:

• /v1 – vereinheitlicht, OpenAI Chat Completions-kompatibel; empfohlener Standard, funktioniert mit jedem Anbieter (/v1/chat/completions).
• /openai/v1 – OpenAI Responses API (erforderlich für gpt-5-…-codex-Varianten und gpt-5-5-pro); der @ai-sdk/openai-Anbieter verwendet standardmäßig die Responses API (/openai/v1/responses).
• /anthropic – native Anthropic Messages (erweitertes Denken, Prompt-Caching). Gib dem Anthropic SDK dies als Basis-URL und es hängt selbst /v1/messages an, sodass der vollständige Anforderungspfad /anthropic/v1/messages ist.
• /gemini – natives Gemini generateContent. Gib google-genai dies als Basis-URL und es hängt selbst /v1beta/models/<model>:generateContent an, sodass der vollständige Anforderungspfad /gemini/v1beta/models/<model>:generateContent ist.

Also ist ${NEON_AI_GATEWAY_BASE_URL}/v1 der Chat-Completions-Endpunkt und ${NEON_AI_GATEWAY_BASE_URL}/openai/v1 der OpenAI Responses-Endpunkt (beide von dir angehängt); für die nativen Anthropic- und Gemini-Dialekte übergibst du dem SDK die kürzere Basis /anthropic oder /gemini und es hängt den Rest an. Siehe Verwendung mit einfachen SDKs unten.

Für typisierten, validierten Zugriff auf die injizierten Anmeldeinformationen übergib das gleiche neon.ts-Konfigurationsobjekt an parseEnv von @neon/env – es gibt einen env.aiGateway-Namespace (apiKey, baseUrl) zurück, der aus deiner Konfiguration abgeleitet wird.

Erstelle Agents mit dem Vercel AI SDK (Empfohlen)

Das Vercel AI SDK ist die empfohlene Methode, um das Gateway aufzurufen und Agents aus TypeScript zu erstellen: ein Satz von Primitiven (generateText, streamText, Tool-Aufruf, strukturierte Ausgabe) über jedes Katalogmodell, mit erstklassigem Streaming für die langen Agentenantworten, die Neon Functions hosten sollen.

Der dedizierte @neon/ai-sdk-provider liest NEON_AI_GATEWAY_BASE_URL + NEON_AI_GATEWAY_TOKEN aus der injizierten Umgebung mit Nullkonfiguration und leitet jedes Modell zum besten Endpunkt (Anthropic → Messages, OpenAI/Codex → Responses, alles andere → MLflow). Auf einer Neon Function, die Text streamt und Bilder generiert, wähle einfach ein Katalogmodell:

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();

Eine einzelne Vervollständigung ist derselbe Anbieter mit 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: "Summarize Postgres for me.",
});

Bevorzuge @neon/ai-sdk-provider gegenüber dem einfachen @ai-sdk/openai openai(): Neon injiziert nur NEON_AI_GATEWAY_*, nicht OPENAI_*, daher wird openai() das Gateway nicht von selbst aus der Umgebung aufnehmen. Wenn du @ai-sdk/openai verwendest, konfiguriere es explizit mit createOpenAI({ apiKey: process.env.NEON_AI_GATEWAY_TOKEN, baseURL: ${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1 }).

Um einen Agenten zu erstellen – ein Modell, das Tools in einer Schleife aufruft und dann antwortet – füge tools und ein stopWhen-Budget hinzu. Die Schleife läuft im Prozess, sodass sie auf einer Neon Function nicht durch Lambda-ähnliche Timeouts unterbrochen wird:

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: "How many open todos do I have, and what's the oldest one?",
  tools: {
    listTodos: tool({
      description: "List the user's open todos.",
      inputSchema: z.object({}), // AI SDK v5+: `inputSchema`, not `parameters`
      execute: async () => db.select().from(todos),
    }),
  },
  stopWhen: stepCountIs(5), // let the model call tools, then summarize
});

Für einen vollständigen AI SDK Agenten, der als Neon Function bereitgestellt wird (Streaming, Tool-Aufruf, Bildgenerierung, Persistenz), siehe das neon-functions-Skill unter references/ai-sdk.md.

Erstelle Agents mit Mastra (Empfohlen)

Mastra ist das empfohlene Framework, wenn du Agents mit eingebauten Funktionen möchtest – integrierter Speicher, Tools, Workflows und Tracing – wobei das Modell weiterhin auf das Gateway zeigt. Mit @mastra/core 1.47+ verwende einen neon/<model>-Magic-String; Mastra liest NEON_AI_GATEWAY_BASE_URL und NEON_AI_GATEWAY_TOKEN aus der Umgebung (injiziert durch neon deploy, wenn preview.aiGateway aktiviert ist). Verwende parseEnv nur für andere deklarierte Dienste (z.B. env.postgres.databaseUrl für @mastra/pg-Speicher):

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, // your Mastra memory store, e.g. @mastra/pg on env.postgres.databaseUrl
});

Verwendung mit einfachen SDKs (Niedrigere Ebene)

Wenn du kein Agent-Framework benötigst – eine einzelne Vervollständigung, eine bestehende Anbieter-SDK-Integration oder native Anbieterfunktionen – rufe das Gateway mit den einfachen SDKs auf. Neon injiziert die NEON_AI_GATEWAY_*-Variablen (nicht OPENAI_*), also setze die Schlüssel apiKey + baseURL des Clients daraus. Für den OpenAI Responses-Dialekt (/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-5-pro",
  instructions: "You are a helpful assistant.",
  input: "What is the capital of France?",
});

Für den nativen Anthropic-Dialekt verwende das Anthropic SDK mit der Basis-URL, die auf /anthropic zeigt:

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-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude." }],
});

Modelle auflisten

Um zu sehen, welche Modelle für den Branch des Benutzers verfügbar sind, verwende den OpenAI-kompatiblen /v1/models-Endpunkt mit dem Token des Gateways als Autorisierung (verwende NEON_AI_GATEWAY_BASE_URL, den Host – hänge /v1 an, um den Chat-Completions-Endpunkt zu erhalten):

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

Der Katalog ändert sich; benutze diesen Endpunkt als Quelle der Wahrheit anstelle einer fest codierten Liste. Du kannst Modellnamen und -Ids dann verwenden, um die Antworten deines Agenten zu gestalten.

Tools

list-all-models

Aufgabe des Tools: Gib die vollständige Liste der Modelle aus, die über das Gateway des Benutzers verfügbar sind, indem du /v1/models aufrufst.

Verwendung: Wenn ein Benutzer fragt: "Welche Modelle sind für mich verfügbar?" oder "Kann ich Modell X verwenden?", tippe:

neon gateway models

oder führe direkt einen Aufruf durch:

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

Formatiere die Ausgabe als nummerierte Liste und gib sie dem Benutzer klar zurück. Erwähne, dass dies die Quelle der Wahrheit für den aktuellen Branch ist; wenn einem Benutzer ein Modell fehlt, ist er möglicherweise auf einem reduzierten Katalog (kostenpflichtiger Plan) oder einem Plan, der die Bereitstellung blockiert (kostenloser Plan).

Wichtige Einschränkungen

• Öffentliche Beta: Funktionen und Verfügbarkeit können sich ändern.
• Regionsbeschränkung: Derzeit nur in us-east-2 und eu-central-1.
• Kostenpflichtiger Plan erforderlich: Foundation-Modelle benötigen einen kostenpflichtigen Neon-Plan; kostenlose Pläne blockieren die Gateway-Bereitstellung mit einem klaren Fehler.
• Reduzierter Katalog während der Beta: Kostenpflichtige Konten können mit einem reduzierten Katalog beginnen; fordere Zugriff über die Neon-Konsole an, um das vollständige Modellspektrum freizuschalten.
• Keine OPENAI_*-Variablen: Neon injiziert nur NEON_AI_GATEWAY_*; verwende den @neon/ai-sdk-provider, neon/<model> in Mastra oder konfiguriere SDKs manuell.

Hilfe zur Fehlerbehebung

Wenn das Gateway nicht funktioniert, überprüfe:

1. Region: Stelle sicher, dass sich das Neon-Projekt des Benutzers in us-east-2 oder eu-central-1 befindet.
2. Plan: Bestätige, dass das Konto des Benutzers einen kostenpflichtigen Neon-Plan hat.
3. Aktivierung: Stelle sicher, dass preview.aiGateway: true in neon.ts gesetzt und neon deploy / neon config apply erfolgreich ausgeführt wurde.
4. Token/URL: Überprüfe, ob NEON_AI_GATEWAY_TOKEN und NEON_AI_GATEWAY_BASE_URL in der Umgebung gesetzt sind (echo $NEON_AI_GATEWAY_TOKEN).
5. Modellzugriff: Führe curl $NEON_AI_GATEWAY_BASE_URL/v1/models mit dem Token aus, um zu sehen, ob das Gateway antwortet und welche Modelle verfügbar sind.
6. SDK-Konfiguration: Verwende den @neon/ai-sdk-provider oder neon/<model> in Mastra, anstatt zu erwarten, dass openai() dies von selbst aufnimmt.