neon-ai-gateway

Neon AI Gateway — скилл Neon для подключения приложений и AI-агентов к нескольким языковым моделям через один branch-scoped endpoint и одну Neon-учётную запись. В исходном SKILL.md он предназначен для случаев, когда нужно вызвать LLM, добавить чат или агента, переключать провайдеров, использовать OpenAI SDK, Anthropic SDK, google-genai, Vercel AI SDK или Mastra и не собирать отдельную связку ключей для каждого поставщика. Gateway описан как inference layer внутри ветки Neon, работающий на инфраструктуре Databricks. В каталоге могут быть модели Anthropic, OpenAI, Google, Meta, Alibaba и DeepSeek; конкретный набор нужно проверять через endpoint /v1/models, потому что доступность зависит от ветки и плана. Главная практическая идея — отделить код приложения от конкретного провайдера. Для OpenAI-совместимого Chat Completions используется путь /v1, для OpenAI Responses — /openai/v1, для нативных сообщений Anthropic — /anthropic/v1, а для Gemini — /gemini/v1beta. В существующем клиенте часто достаточно оставить знакомый SDK и заменить base URL. Для OpenAI SDK можно создать клиента с NEON_AI_GATEWAY_TOKEN и базовым адресом ветки, добавив нужный диалект; для Anthropic SDK и google-genai исходник также указывает соответствующие базовые пути. Модель передаётся её catalog ID, без обязательного префикса провайдера. Это позволяет менять поле model, не переписывая слой интеграции, но не отменяет проверку того, что выбранный ID реально доступен в конкретном Gateway. Для Vercel AI SDK рекомендуется @neon/ai-sdk-provider: он читает NEON_AI_GATEWAY_BASE_URL и NEON_AI_GATEWAY_TOKEN, выбирает подходящий маршрут для провайдера и поддерживает generateText, streamText, tool calling, structured output и потоковую выдачу. В примерах источника тот же provider используется для обычного completion, стриминга, вызова инструментов и генерации изображений. При построении агента цикл ограничивается stopWhen и stepCountIs, чтобы модель могла вызвать инструменты, а затем сформировать ответ. Для Mastra исходник показывает строку neon/<model> и работу с Agent; gateway-учётные данные берутся из окружения Neon. Если вместо специализированного provider используется @ai-sdk/openai, baseURL и apiKey нужно передать явно: Neon инжектирует NEON_AI_GATEWAY_* и не подменяет автоматически OPENAI_API_KEY или OPENAI_BASE_URL. Важное свойство — привязка к ветке. У каждой ветки свой Gateway host, а запросы preview или feature branch сохраняют ту же изоляцию, что и данные этой ветки. При создании новой ветки через neon checkout политика из neon.ts применяется автоматически, но checkout существующей ветки не выполняет reconcile: для неё нужен neon deploy или config apply. Перед настройкой следует проверить статус и план конфигурации, а после включения — получить окружение и запросить /v1/models. В исходнике отдельно указано, что поток SSE поддерживается без дополнительной настройки, а в Neon Functions переменные Gateway доступны автоматически. Ограничения нельзя скрывать за общим обещанием «один API». Функция находится в public beta и доступна только для новых проектов в регионе us-east-2; существующий проект в другом регионе не становится совместимым простой настройкой. Free plan блокирует provisioning, поэтому для Gateway нужен платный план. Даже на платном плане во время beta каталог может быть сокращён: отдельные флагманские модели могут отсутствовать, и доступ к ним запрашивается через страницу AI Gateway в Neon Console. Платёжный план, регион, branch credentials и фактический ответ /v1/models нужно проверять до выдачи пользователю инструкции. Скилл помогает настроить вызов и агента, но не заменяет проверку лимитов, биллинга, доступности модели, секретов и требований конкретного приложения.