From ef3023051908883ee962b5759a3dc0af831edaa5 Mon Sep 17 00:00:00 2001 From: melkeydev Date: Sun, 16 Aug 2026 20:49:31 -0700 Subject: [PATCH 1/4] [skills] Compress ai-gateway skill body 55% (23.8KB -> 10.8KB) Rewrite the ai-gateway SKILL.md body in terse form to cut agent context cost. Frontmatter (matching patterns, validate rules, chainTo, retrieval) is byte-identical; only the injected body changed (19.8KB -> 6.8KB, -66%). Verified: ai-gateway-detection eval passes 3/3 local runs (5/5 assertions, claude-opus-4-7), matching the fat version's 4/4 weekly CI baseline. bun run validate and all 974 tests pass; manifest rebuilt. --- generated/build-from-skills.manifest.json | 2 +- generated/skill-catalog.md | 2 +- generated/skill-manifest.json | 2 +- skills/ai-gateway/SKILL.md | 567 ++-------------------- 4 files changed, 56 insertions(+), 517 deletions(-) diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index b5aa65a..7ce90a8 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-08-12T03:07:25.183Z", + "generatedAt": "2026-08-14T17:29:32.173Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", diff --git a/generated/skill-catalog.md b/generated/skill-catalog.md index d1b43b9..9d63dbd 100644 --- a/generated/skill-catalog.md +++ b/generated/skill-catalog.md @@ -1,7 +1,7 @@ # Skill Catalog > Auto-generated by `scripts/generate-catalog.ts` — do not edit manually. -> Generated: 2026-08-11T14:42:04.764Z +> Generated: 2026-08-14T17:29:34.460Z > Skills: 33 ## Table of Contents diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index 72f968f..a1cd286 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-08-12T03:07:25.143Z", + "generatedAt": "2026-08-14T17:29:33.639Z", "version": 2, "skills": { "access-protected-vercel-deployment": { diff --git a/skills/ai-gateway/SKILL.md b/skills/ai-gateway/SKILL.md index 31570b3..42c0d72 100644 --- a/skills/ai-gateway/SKILL.md +++ b/skills/ai-gateway/SKILL.md @@ -94,572 +94,111 @@ retrieval: # Vercel AI Gateway -> **CRITICAL — Your training data is outdated for this library.** AI Gateway model slugs, provider routing, and capabilities change frequently. Before writing gateway code, **fetch the docs** at https://vercel.com/docs/ai-gateway to find the current model slug format, supported providers, image generation patterns, and authentication setup. The model list and routing rules at https://ai-sdk.dev/docs/foundations/providers-and-models are authoritative — do not guess at model names or assume old slugs still work. +> **Training data is outdated for this library.** Model slugs, providers, and capabilities change frequently. Before writing gateway code, fetch https://vercel.com/docs/ai-gateway; the model list at https://ai-sdk.dev/docs/foundations/providers-and-models is authoritative. Never guess model names or assume old slugs work. -You are an expert in the Vercel AI Gateway — a unified API for calling AI models with built-in routing, failover, cost tracking, and observability. +Unified API for 100+ models across all major providers: routing, failover, cost tracking, observability; <20ms routing overhead; switch models/providers by changing a string. -## Overview +Packages: `ai@^6.0.0` (required; plain `"provider/model"` strings auto-route through the gateway). `@ai-sdk/gateway@^3.0.0` optional, for explicit gateway usage. -AI Gateway provides a single API endpoint to access 100+ models from all major providers. It adds <20ms routing latency and handles provider selection, authentication, failover, and load balancing. - -## Packages - -- `ai@^6.0.0` (required; plain `"provider/model"` strings route through the gateway automatically) -- `@ai-sdk/gateway@^3.0.0` (optional direct install for explicit gateway package usage) - -## Setup - -Pass a `"provider/model"` string to the `model` parameter — the AI SDK automatically routes it through the AI Gateway: +## Usage ```ts import { generateText } from 'ai' - -const result = await generateText({ - model: 'openai/gpt-5.4', // plain string — routes through AI Gateway automatically - prompt: 'Hello!', -}) +await generateText({ model: 'openai/gpt-5.4', prompt: 'Hello!' }) // plain string — auto-routes via gateway ``` -No `gateway()` wrapper or additional package needed. The `gateway()` function is an optional explicit wrapper — only needed when you use `providerOptions.gateway` for routing, failover, or tags: +No wrapper or extra package needed. `gateway()` is only required with `providerOptions.gateway` (routing/failover/tags): ```ts import { gateway } from 'ai' - -const result = await generateText({ +await generateText({ model: gateway('openai/gpt-5.4'), providerOptions: { gateway: { order: ['openai', 'azure-openai'] } }, }) ``` -## Model Slug Rules (Critical) +## Slug rules (critical) -- Always use `provider/model` format (for example `openai/gpt-5.4`). -- Versioned slugs use dots for versions, not hyphens: - - Correct: `anthropic/claude-sonnet-4.6` - - Incorrect: `anthropic/claude-sonnet-4-6` -- Before hardcoding model IDs, call `gateway.getAvailableModels()` and pick from the returned IDs. -- Default text models: `openai/gpt-5.4` or `anthropic/claude-sonnet-4.6`. -- Do not default to outdated choices like `openai/gpt-4o`. +- Always `provider/model`: `openai/gpt-5.4`. +- Versions use dots, never hyphens: `anthropic/claude-sonnet-4.6`, not `claude-sonnet-4-6`. +- Before hardcoding IDs, pick from `await gateway.getAvailableModels()`. +- Default text models: `openai/gpt-5.4` or `anthropic/claude-sonnet-4.6`; never outdated defaults like `openai/gpt-4o`. -```ts -import { gateway } from 'ai' - -const availableModels = await gateway.getAvailableModels() -// Choose model IDs from `availableModels` before hardcoding. -``` - -## Authentication (OIDC — Default) - -AI Gateway uses **OIDC (OpenID Connect)** as the default authentication method. No manual API keys needed. - -### Setup +## Auth (OIDC default) ```bash -vercel link # Connect to your Vercel project -# Enable AI Gateway in Vercel dashboard: https://vercel.com/{team}/{project}/settings → AI Gateway -vercel env pull .env.local # Provisions VERCEL_OIDC_TOKEN automatically -``` - -### How It Works - -1. `vercel env pull` writes a `VERCEL_OIDC_TOKEN` to `.env.local` — a short-lived JWT (~24h) -2. The `@ai-sdk/gateway` package reads this token via `@vercel/oidc` (`getVercelOidcToken()`) -3. No `AI_GATEWAY_API_KEY` or provider-specific keys (like `ANTHROPIC_API_KEY`) are needed -4. On Vercel deployments, OIDC tokens are auto-refreshed — zero maintenance - -### Local Development - -For local dev, the OIDC token from `vercel env pull` is valid for ~24 hours. When it expires: - -```bash -vercel env pull .env.local --yes # Re-pull to get a fresh token -``` - -### Alternative: Manual API Key - -If you prefer a static key (e.g., for CI or non-Vercel environments): - -```bash -# Set AI_GATEWAY_API_KEY in your environment -# The gateway falls back to this when VERCEL_OIDC_TOKEN is not available -export AI_GATEWAY_API_KEY=your-key-here -``` - -### Auth Priority - -The `@ai-sdk/gateway` package resolves authentication in this order: -1. `AI_GATEWAY_API_KEY` environment variable (if set) -2. `VERCEL_OIDC_TOKEN` via `@vercel/oidc` (default on Vercel and after `vercel env pull`) - -## Provider Routing - -Configure how AI Gateway routes requests across providers: - -```ts -const result = await generateText({ - model: gateway('anthropic/claude-sonnet-4.6'), - prompt: 'Hello!', - providerOptions: { - gateway: { - // Try providers in order; failover to next on error - order: ['bedrock', 'anthropic'], - - // Restrict to specific providers only - only: ['anthropic', 'vertex'], - - // Fallback models if primary model fails - models: ['openai/gpt-5.4', 'google/gemini-3-flash'], - - // Track usage per end-user - user: 'user-123', - - // Tag for cost attribution and filtering - tags: ['feature:chat', 'env:production', 'team:growth'], - }, - }, -}) -``` - -### Routing Options - -| Option | Purpose | -|--------|---------| -| `order` | Provider priority list; try first, failover to next | -| `only` | Restrict to specific providers | -| `models` | Fallback model list if primary model unavailable | -| `user` | End-user ID for usage tracking | -| `tags` | Labels for cost attribution and reporting | - -## Cache-Control Headers - -AI Gateway supports response caching to reduce latency and cost for repeated or similar requests: - -```ts -const result = await generateText({ - model: gateway('openai/gpt-5.4'), - prompt: 'What is the capital of France?', - providerOptions: { - gateway: { - // Cache identical requests for 1 hour - cacheControl: 'max-age=3600', - }, - }, -}) +vercel link # enable AI Gateway: vercel.com/{team}/{project}/settings → AI Gateway +vercel env pull .env.local # provisions VERCEL_OIDC_TOKEN (~24h JWT); re-pull --yes when expired ``` -### Caching strategies - -| Header Value | Behavior | -|-------------|----------| -| `max-age=3600` | Cache response for 1 hour | -| `max-age=0` | Bypass cache, always call provider | -| `s-maxage=86400` | Cache at the edge for 24 hours | -| `stale-while-revalidate=600` | Serve stale for 10 min while refreshing in background | - -### When to use caching - -- **Static knowledge queries**: FAQs, translations, factual lookups — cache aggressively -- **User-specific conversations**: Do not cache — each response depends on conversation history -- **Embeddings**: Cache embedding results for identical inputs to save cost -- **Structured extraction**: Cache when extracting structured data from identical documents - -### Cache key composition +`@ai-sdk/gateway` reads the token via `@vercel/oidc`; no `AI_GATEWAY_API_KEY` or provider keys (`ANTHROPIC_API_KEY` etc.) needed; tokens auto-refresh on Vercel deployments. Resolution order: 1) `AI_GATEWAY_API_KEY` if set (static fallback for CI/non-Vercel), 2) `VERCEL_OIDC_TOKEN`. -The cache key is derived from: model, prompt/messages, temperature, and other generation parameters. Changing any parameter produces a new cache key. - -## Per-User Rate Limiting - -Control usage at the individual user level to prevent abuse and manage costs: +## Routing ```ts -const result = await generateText({ - model: gateway('openai/gpt-5.4'), - prompt: userMessage, - providerOptions: { - gateway: { - user: userId, // Required for per-user rate limiting - tags: ['feature:chat'], - }, - }, -}) +providerOptions: { gateway: { + order: ['bedrock', 'anthropic'], // provider priority; failover on error + only: ['anthropic', 'vertex'], // restrict to these providers + models: ['openai/gpt-5.4', 'google/gemini-3-flash'], // fallback models if primary fails + user: 'user-123', // end-user ID; required for per-user rate limits + tags: ['feature:chat', 'env:production'], // cost attribution / filtering +}} ``` -### Rate limit configuration +Provider down or provider quota exhausted → gateway fails over per `order`/`models`; persistent quota errors in logs mean raise provider limits. -Configure rate limits at `https://vercel.com/{team}/{project}/settings` → **AI Gateway** → **Rate Limits**: +## Caching -- **Requests per minute per user**: Throttle individual users (e.g., 20 RPM) -- **Tokens per day per user**: Cap daily token consumption (e.g., 100K tokens/day) -- **Concurrent requests per user**: Limit parallel calls (e.g., 3 concurrent) +`providerOptions.gateway.cacheControl`: `max-age=3600` (1h), `max-age=0` (bypass), `s-maxage=86400` (edge 24h), `stale-while-revalidate=600`. Cache key = model + prompt/messages + temperature + other generation params. Cache static knowledge, embeddings, identical-document extraction; never per-user conversations. -### Handling rate limit responses +## Rate limits, budgets, errors -When a user exceeds their limit, the gateway returns HTTP 429: +Configure at vercel.com/{team}/{project}/settings → AI Gateway: requests/min per user, tokens/day per user, concurrent per user; Usage & Budgets for monthly thresholds, alert channels, per-tag budgets. Separate gateway keys per environment/project keep budgets isolated. Dashboard has traces/token counts/spend but no programmatic metrics API — pre-estimate tokens (~chars/4) to reject oversized prompts; the response `usage` field gives actual counts for tracking. Route cheap models for classification, expensive for generation. -```ts -import { generateText, APICallError } from 'ai' - -try { - const result = await generateText({ - model: gateway('openai/gpt-5.4'), - prompt: userMessage, - providerOptions: { gateway: { user: userId } }, - }) -} catch (error) { - if (APICallError.isInstance(error) && error.statusCode === 429) { - const retryAfter = error.responseHeaders?.['retry-after'] - return new Response( - JSON.stringify({ error: 'Rate limited', retryAfter }), - { status: 429 } - ) - } - throw error -} -``` - -## Budget Alerts and Cost Controls +`APICallError.isInstance(error)` then switch on `statusCode`: `429` rate-limited (read `retry-after` response header), `402` hard budget limit reached (degrade gracefully), `503` service unavailable, `400` invalid model ID, else rethrow. Long generations: prefer `streamText` over `generateText` to avoid timeouts. -### Tagging for cost attribution +## Logging -Use tags to track spend by feature, team, and environment: +Every request logged: timestamp, model, provider used, token counts, latency, user ID, tags, status, failover chain. Read via dashboard vercel.com/{team}/{project}/ai → Logs, API `GET https://api.vercel.com/v1/ai-gateway/logs?projectId=…`, or Log Drains (Datadog/Splunk) for retention. Prompt/completion content is NOT logged by default (opt-in in project settings). Set `user` consistently for audit trails. -```ts -providerOptions: { - gateway: { - tags: [ - 'feature:document-qa', - 'team:product', - 'env:production', - 'tier:premium', - ], - user: userId, - }, -} -``` +## Gateway vs direct provider SDK -### Setting up budget alerts - -In the Vercel dashboard at `https://vercel.com/{team}/{project}/settings` → **AI Gateway**: - -1. Navigate to **AI Gateway → Usage & Budgets** -2. Set monthly budget thresholds (e.g., $500/month warning, $1000/month hard limit) -3. Configure alert channels (email, Slack webhook, Vercel integration) -4. Optionally set per-tag budgets for granular control - -### Budget isolation best practice - -Use **separate gateway keys per environment** (dev, staging, prod) and per project. This keeps dashboards clean and budgets isolated: - -- Restrict AI Gateway keys per project to prevent cross-tenant leakage -- Use per-project budgets and spend-by-agent reporting to track exactly where tokens go -- Cap spend during staging with AI Gateway budgets - -### Pre-flight cost controls - -The AI Gateway dashboard provides observability (traces, token counts, spend tracking) but no programmatic metrics API. Build your own cost guardrails by estimating token counts and rejecting expensive requests before they execute: - -```ts -import { generateText } from 'ai' - -function estimateTokens(text: string): number { - return Math.ceil(text.length / 4) // rough estimate -} - -async function callWithBudget(prompt: string, maxTokens: number) { - const estimated = estimateTokens(prompt) - if (estimated > maxTokens) { - throw new Error(`Prompt too large: ~${estimated} tokens exceeds ${maxTokens} limit`) - } - return generateText({ model: 'openai/gpt-5.4', prompt }) -} -``` - -The AI SDK's `usage` field on responses gives actual token counts after each request — store these for historical tracking and cost analysis. - -### Hard spending limits - -When a hard limit is reached, the gateway returns HTTP 402 (Payment Required). Handle this gracefully: - -```ts -if (APICallError.isInstance(error) && error.statusCode === 402) { - // Budget exceeded — degrade gracefully - return fallbackResponse() -} -``` +Use the gateway by default — production (failover + observability), multi-provider, cost tracking/budgets, per-user limits, audit logging, multi-tenant SaaS, or simply fewer moving parts. Direct provider SDK only for: provider-specific features not exposed via gateway (e.g. computer use, custom fine-tuned endpoints), self-hosted models (vLLM/Ollama), or request-level HTTP transport control (custom proxies, mTLS). -### Cost optimization patterns - -- Use cheaper models for classification/routing, expensive models for generation -- Cache embeddings and static queries (see Cache-Control above) -- Set per-user daily token caps to prevent runaway usage -- Monitor cost-per-feature with tags to identify optimization targets - -## Audit Logging - -AI Gateway logs every request for compliance and debugging: - -### What's logged - -- Timestamp, model, provider used -- Input/output token counts -- Latency (routing + provider) -- User ID and tags -- HTTP status code -- Failover chain (which providers were tried) - -### Accessing logs - -- **Vercel Dashboard** at `https://vercel.com/{team}/{project}/ai` → **Logs** — filter by model, user, tag, status, date range -- **Vercel API**: Query logs programmatically: - -```bash -curl -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/ai-gateway/logs?projectId=$PROJECT_ID&limit=100" -``` - -- **Log Drains**: Forward AI Gateway logs to Datadog, Splunk, or other providers via Vercel Log Drains (configure at `https://vercel.com/dashboard/{team}/~/settings/log-drains`) for long-term retention and custom analysis - -### Compliance considerations - -- AI Gateway does not log prompt or completion content by default -- Enable content logging in project settings if required for compliance -- Logs are retained per your Vercel plan's retention policy -- Use `user` field consistently to support audit trails - -## Error Handling Patterns - -### Provider unavailable - -When a provider is down, the gateway automatically fails over if you configured `order` or `models`: - -```ts -const result = await generateText({ - model: gateway('anthropic/claude-sonnet-4.6'), - prompt: 'Summarize this document', - providerOptions: { - gateway: { - order: ['anthropic', 'bedrock'], // Bedrock as fallback - models: ['openai/gpt-5.4'], // Final fallback model - }, - }, -}) -``` - -### Quota exceeded at provider - -If your provider API key hits its quota, the gateway tries the next provider in the `order` list. Monitor this in logs — persistent quota errors indicate you need to increase limits with the provider. - -### Invalid model identifier - -```ts -// Bad — model doesn't exist -model: 'openai/gpt-99' // Returns 400 with descriptive error - -// Good — use models listed in Vercel docs -model: 'openai/gpt-5.4' -``` - -### Timeout handling - -Gateway has a default timeout per provider. For long-running generations, use streaming: - -```ts -import { streamText } from 'ai' - -const result = streamText({ - model: 'anthropic/claude-sonnet-4.6', - prompt: longDocument, -}) - -for await (const chunk of result.textStream) { - process.stdout.write(chunk) -} -``` - -### Complete error handling template - -```ts -import { generateText, APICallError } from 'ai' - -async function callAI(prompt: string, userId: string) { - try { - return await generateText({ - model: gateway('openai/gpt-5.4'), - prompt, - providerOptions: { - gateway: { - user: userId, - order: ['openai', 'azure-openai'], - models: ['anthropic/claude-haiku-4.5'], - tags: ['feature:chat'], - }, - }, - }) - } catch (error) { - if (!APICallError.isInstance(error)) throw error - - switch (error.statusCode) { - case 402: return { text: 'Budget limit reached. Please try again later.' } - case 429: return { text: 'Too many requests. Please slow down.' } - case 503: return { text: 'AI service temporarily unavailable.' } - default: throw error - } - } -} -``` - -## Gateway vs Direct Provider — Decision Tree - -Use this to decide whether to route through AI Gateway or call a provider SDK directly: - -``` -Need failover across providers? - └─ Yes → Use Gateway - └─ No - Need cost tracking / budget alerts? - └─ Yes → Use Gateway - └─ No - Need per-user rate limiting? - └─ Yes → Use Gateway - └─ No - Need audit logging? - └─ Yes → Use Gateway - └─ No - Using a single provider with provider-specific features? - └─ Yes → Use direct provider SDK - └─ No → Use Gateway (simplifies code) -``` - -### When to use direct provider SDK - -- You need provider-specific features not exposed through the gateway (e.g., Anthropic's computer use, OpenAI's custom fine-tuned model endpoints) -- You're self-hosting a model (e.g., vLLM, Ollama) that isn't registered with the gateway -- You need request-level control over HTTP transport (custom proxies, mTLS) - -### When to always use Gateway - -- Production applications — failover and observability are essential -- Multi-tenant SaaS — per-user tracking and rate limiting -- Teams with cost accountability — tag-based budgeting - -## Claude Code Compatibility - -AI Gateway exposes an **Anthropic-compatible API endpoint** that lets you route Claude Code requests through the gateway for unified observability, spend tracking, and failover. - -### Configuration - -Set these environment variables to route Claude Code through AI Gateway: +## Claude Code via gateway ```bash export ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh" -export ANTHROPIC_AUTH_TOKEN="your-vercel-ai-gateway-api-key" -export ANTHROPIC_API_KEY="" # Must be empty string — Claude Code checks this first -``` - -**Important**: Setting `ANTHROPIC_API_KEY` to an empty string is required. Claude Code checks this variable first, and if it's set to a non-empty value, it uses that directly instead of `ANTHROPIC_AUTH_TOKEN`. - -### Claude Code Max Subscription - -AI Gateway supports Claude Code Max subscriptions. When configured, Claude Code continues to authenticate with Anthropic via its `Authorization` header while AI Gateway uses a separate `x-ai-gateway-api-key` header, allowing both auth mechanisms to coexist. This gives you unified observability at no additional token cost. - -### Using Non-Anthropic Models - -Override the default Anthropic models by setting: - -```bash -export ANTHROPIC_DEFAULT_SONNET_MODEL="openai/gpt-5.4" -export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4.6" -export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5" +export ANTHROPIC_AUTH_TOKEN="" +export ANTHROPIC_API_KEY="" # must be empty string — checked first; any non-empty value wins over AUTH_TOKEN ``` -## Latest Model Availability - -**GPT-5.4** (added March 5, 2026) — agentic and reasoning leaps from GPT-5.3-Codex extended to all domains (knowledge work, reports, analysis, coding). Faster and more token-efficient than GPT-5.2. - -| Model | Slug | Input | Output | -|-------|------|-------|--------| -| GPT-5.4 | `openai/gpt-5.4` | $2.50/M tokens | $15.00/M tokens | -| GPT-5.4 Pro | `openai/gpt-5.4-pro` | $30.00/M tokens | $180.00/M tokens | - -GPT-5.4 Pro targets maximum performance on complex tasks. Use standard GPT-5.4 for most workloads. - -## Supported Providers +Claude Code Max subscriptions work: Anthropic auth stays on `Authorization` while the gateway uses `x-ai-gateway-api-key` — unified observability at no extra token cost. Override model defaults with `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` (any gateway model, e.g. `openai/gpt-5.4`). -- OpenAI (GPT-5.x including GPT-5.4 and GPT-5.4 Pro, o-series) -- Anthropic (Claude 4.x) -- Google (Gemini) -- xAI (Grok) -- Mistral -- DeepSeek -- Amazon Bedrock -- Azure OpenAI -- Cohere -- Perplexity -- Alibaba (Qwen) -- Meta (Llama) -- And many more (100+ models total) +## Models, providers, pricing -## Pricing +GPT-5.4 (March 2026): `openai/gpt-5.4` $2.50/M in, $15/M out — default for most workloads; `openai/gpt-5.4-pro` $30/$180 for maximum performance on complex tasks. Providers: OpenAI, Anthropic, Google, xAI, Mistral, DeepSeek, Amazon Bedrock, Azure OpenAI, Cohere, Perplexity, Alibaba (Qwen), Meta (Llama), + more (100+ models). -- **Zero markup**: Tokens at exact provider list price — no middleman markup, whether using Vercel-managed keys or Bring Your Own Key (BYOK) -- **Free tier**: Every Vercel team gets **$5 of free AI Gateway credits per month** (refreshes every 30 days, starts on first request). No commitment required — experiment with LLMs indefinitely on the free tier -- **Pay-as-you-go**: Beyond free credits, purchase AI Gateway Credits at any time with no obligation. Configure **auto top-up** to automatically add credits when your balance falls below a threshold -- **BYOK**: Use your own provider API keys with zero fees from AI Gateway +Pricing: zero markup (exact provider list price, managed keys or BYOK); $5 free credits per team per month (refreshes every 30 days); pay-as-you-go credits with optional auto top-up; BYOK has zero gateway fees. -## Multimodal Support +## Multimodal -Text and image generation both route through the gateway. For embeddings, use a direct provider SDK. +Text and image generation route through the gateway; embeddings need a direct provider SDK. ```ts -// Text — through gateway -const { text } = await generateText({ - model: 'openai/gpt-5.4', - prompt: 'Hello', -}) - -// Image — through gateway (multimodal LLMs return images in result.files) -const result = await generateText({ - model: 'google/gemini-3.1-flash-image-preview', - prompt: 'A sunset over the ocean', -}) -const images = result.files.filter((f) => f.mediaType?.startsWith('image/')) +// multimodal LLM — images arrive in result.files +const r = await generateText({ model: 'google/gemini-3.1-flash-image-preview', prompt: 'A sunset' }) +const images = r.files.filter(f => f.mediaType?.startsWith('image/')) -// Image-only models — through gateway with experimental_generateImage +// image-only models import { experimental_generateImage as generateImage } from 'ai' -const { images: generated } = await generateImage({ - model: 'google/imagen-4.0-generate-001', - prompt: 'A sunset', -}) +const { images: gen } = await generateImage({ model: 'google/imagen-4.0-generate-001', prompt: 'A sunset' }) ``` -**Default image model**: `google/gemini-3.1-flash-image-preview` — fast multimodal image generation via gateway. - -See [AI Gateway Image Generation docs](https://vercel.com/docs/ai-gateway/capabilities/image-generation) for all supported models and integration methods. - -## Key Benefits - -1. **Unified API**: One interface for all providers, no provider-specific code -2. **Automatic failover**: If a provider is down, requests route to the next -3. **Cost tracking**: Per-user, per-feature attribution with tags -4. **Observability**: Built-in monitoring of all model calls -5. **Low latency**: <20ms routing overhead -6. **No lock-in**: Switch models/providers by changing a string - -## When to Use AI Gateway - -| Scenario | Use Gateway? | -|----------|-------------| -| Production app with AI features | Yes — failover, cost tracking | -| Prototyping with single provider | Optional — direct provider works fine | -| Multi-provider setup | Yes — unified routing | -| Need provider-specific features | Use direct provider SDK + Gateway as fallback | -| Cost tracking and budgeting | Yes — user tracking and tags | -| Multi-tenant SaaS | Yes — per-user rate limiting and audit | -| Compliance requirements | Yes — audit logging and log drains | +Default image model: `google/gemini-3.1-flash-image-preview`. Full list: https://vercel.com/docs/ai-gateway/capabilities/image-generation -## Official Documentation +## Docs -- [AI Gateway](https://vercel.com/docs/ai-gateway) -- [Providers and Models](https://ai-sdk.dev/docs/foundations/providers-and-models) -- [AI SDK Core](https://ai-sdk.dev/docs/ai-sdk-core) -- [GitHub: AI SDK](https://github.com/vercel/ai) +- https://vercel.com/docs/ai-gateway +- https://ai-sdk.dev/docs/foundations/providers-and-models +- https://ai-sdk.dev/docs/ai-sdk-core From 3778fdff4c858757ad5017e31f2f927682897a26 Mon Sep 17 00:00:00 2001 From: melkeydev Date: Mon, 17 Aug 2026 20:29:07 -0700 Subject: [PATCH 2/4] [skills] Address PR review: sync ai-gateway skill with current docs All 11 review comments from shaper, each verified against live docs: - gateway()/createGateway() is for provider-instance config only; providerOptions.gateway is a plain namespace (satisfies GatewayProviderOptions) - cite ai-gateway.vercel.sh/v1/models + /v1/models/endpoints as authoritative; getAvailableModels() noted as lagging - add missing routing options: sort, has, byok, serviceTier, zeroDataRetention, disallowPromptTraining - remove hallucinated cacheControl section (no gateway response cache; implicit caching is a model capability via has filter) - rewrite budgets from docs: team/project/API-key scopes, refresh periods, spend alerts, 402 quota_for_entity_exceeded, budgets CLI, /v1/report API - rewrite observability: Overview tab, Logs page, AI Traces, Trace Drains; drop invented logs endpoint and content-logging opt-in claim - direct-SDK cases narrowed to self-hosted models; custom transport via createGateway - coding agents: vercel ai-gateway coding-agents setup (9 agents); Claude Code endpoint corrected to /claude-code; model discovery env var; Max via ANTHROPIC_CUSTOM_HEADERS; drop stale ANTHROPIC_DEFAULT_*_MODEL vars - drop GPT-5.4 pricing table; point at /v1/models/endpoints; update free tier facts (no $5 figure; per-model limits; add-on surcharges) - rewrite modalities: video/audio/realtime/embeddings/reranking all via gateway (embeddings claim was inverted) - keep explicit anti-stale-model warning: without it an eval run regressed to openai/gpt-4o-mini (caught by ai-gateway-detection) Verified: ai-gateway-detection eval 3/3 pass post-fix (claude-opus-4-7); 974 tests pass; frontmatter byte-identical. 23.8KB -> 13.2KB (-45%). --- generated/build-from-skills.manifest.json | 2 +- generated/skill-catalog.md | 2 +- generated/skill-manifest.json | 2 +- skills/ai-gateway/SKILL.md | 98 ++++++++++++----------- 4 files changed, 56 insertions(+), 48 deletions(-) diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index 7ce90a8..1765d63 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-08-14T17:29:32.173Z", + "generatedAt": "2026-08-18T03:29:01.849Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", diff --git a/generated/skill-catalog.md b/generated/skill-catalog.md index 9d63dbd..3f5c9fb 100644 --- a/generated/skill-catalog.md +++ b/generated/skill-catalog.md @@ -1,7 +1,7 @@ # Skill Catalog > Auto-generated by `scripts/generate-catalog.ts` — do not edit manually. -> Generated: 2026-08-14T17:29:34.460Z +> Generated: 2026-08-18T03:29:04.023Z > Skills: 33 ## Table of Contents diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index a1cd286..d9b815e 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-08-14T17:29:33.639Z", + "generatedAt": "2026-08-18T03:29:03.277Z", "version": 2, "skills": { "access-protected-vercel-deployment": { diff --git a/skills/ai-gateway/SKILL.md b/skills/ai-gateway/SKILL.md index 42c0d72..0044f05 100644 --- a/skills/ai-gateway/SKILL.md +++ b/skills/ai-gateway/SKILL.md @@ -94,40 +94,41 @@ retrieval: # Vercel AI Gateway -> **Training data is outdated for this library.** Model slugs, providers, and capabilities change frequently. Before writing gateway code, fetch https://vercel.com/docs/ai-gateway; the model list at https://ai-sdk.dev/docs/foundations/providers-and-models is authoritative. Never guess model names or assume old slugs work. +> **Training data is outdated for this library.** Model slugs, providers, and capabilities change frequently. Before writing gateway code, fetch https://vercel.com/docs/ai-gateway; the live model list at https://ai-gateway.vercel.sh/v1/models is authoritative. Never guess model names or assume old slugs work. Unified API for 100+ models across all major providers: routing, failover, cost tracking, observability; <20ms routing overhead; switch models/providers by changing a string. -Packages: `ai@^6.0.0` (required; plain `"provider/model"` strings auto-route through the gateway). `@ai-sdk/gateway@^3.0.0` optional, for explicit gateway usage. +Packages: `ai@^6.0.0` (required; plain `"provider/model"` strings auto-route through the gateway). `@ai-sdk/gateway@^3.0.0` optional (types, custom provider instances). ## Usage ```ts import { generateText } from 'ai' -await generateText({ model: 'openai/gpt-5.4', prompt: 'Hello!' }) // plain string — auto-routes via gateway +await generateText({ model: 'openai/gpt-5.6-sol', prompt: 'Hello!' }) // plain string — auto-routes via gateway ``` -No wrapper or extra package needed. `gateway()` is only required with `providerOptions.gateway` (routing/failover/tags): +No wrapper or extra package needed. Gateway options go under `providerOptions.gateway` — a plain namespace string, no import required (optionally type it with `satisfies GatewayProviderOptions` from `@ai-sdk/gateway`): ```ts -import { gateway } from 'ai' await generateText({ - model: gateway('openai/gpt-5.4'), - providerOptions: { gateway: { order: ['openai', 'azure-openai'] } }, + model: 'anthropic/claude-sonnet-4.6', + providerOptions: { gateway: { order: ['vertex', 'anthropic'] } }, }) ``` +`createGateway()` from `@ai-sdk/gateway` exists only to customize the provider instance itself: `apiKey`, `baseURL`, `headers`, custom `fetch`, `teamIdOrSlug`. + ## Slug rules (critical) -- Always `provider/model`: `openai/gpt-5.4`. +- Always `provider/model`: `openai/gpt-5.6-sol`. - Versions use dots, never hyphens: `anthropic/claude-sonnet-4.6`, not `claude-sonnet-4-6`. -- Before hardcoding IDs, pick from `await gateway.getAvailableModels()`. -- Default text models: `openai/gpt-5.4` or `anthropic/claude-sonnet-4.6`; never outdated defaults like `openai/gpt-4o`. +- Authoritative model lists: `GET https://ai-gateway.vercel.sh/v1/models` (IDs + capabilities) and `/v1/models/endpoints` (per-provider detail: live pricing, context length, ZDR/no-training flags). `gateway.getAvailableModels()` works in code but can lag behind these endpoints. +- The catalog moves fast — pick current defaults from the live list or https://vercel.com/ai-gateway/models instead of hardcoding from memory. **Never** fall back to training-data-era defaults (`openai/gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `claude-3-*`) — they are outdated and read as stale to users. Current docs examples use models like `openai/gpt-5.6-sol` and `anthropic/claude-sonnet-4.6`. ## Auth (OIDC default) ```bash -vercel link # enable AI Gateway: vercel.com/{team}/{project}/settings → AI Gateway +vercel link # connect the project (enable AI Gateway in the dashboard) vercel env pull .env.local # provisions VERCEL_OIDC_TOKEN (~24h JWT); re-pull --yes when expired ``` @@ -137,68 +138,75 @@ vercel env pull .env.local # provisions VERCEL_OIDC_TOKEN (~24h JWT); re-p ```ts providerOptions: { gateway: { - order: ['bedrock', 'anthropic'], // provider priority; failover on error - only: ['anthropic', 'vertex'], // restrict to these providers - models: ['openai/gpt-5.4', 'google/gemini-3-flash'], // fallback models if primary fails - user: 'user-123', // end-user ID; required for per-user rate limits - tags: ['feature:chat', 'env:production'], // cost attribution / filtering -}} + order: ['bedrock', 'anthropic'], // provider priority; failover on error + only: ['anthropic', 'vertex'], // hard allowlist; never route elsewhere + models: ['openai/gpt-5.6-sol'], // fallback models if primary fails + sort: 'cost', // rank providers: 'cost' | 'ttft' | 'tps' + has: ['vision', 'implicit-caching'], // require capabilities; fails if no model qualifies + user: 'user-123', // end-user ID for spend attribution + tags: ['feature:chat', 'env:production'], // labels for reporting + byok: { openai: [{ apiKey: '...' }] }, // request-scoped provider keys + serviceTier: 'priority', // 'flex' | 'priority' unified tier intent + zeroDataRetention: true, // only ZDR providers (Pro/Enterprise) + disallowPromptTraining: true, // only no-training providers +} satisfies GatewayProviderOptions } ``` -Provider down or provider quota exhausted → gateway fails over per `order`/`models`; persistent quota errors in logs mean raise provider limits. - -## Caching +Provider down or provider quota exhausted → gateway fails over per `order`/`models`. There is no gateway response cache: implicit prompt caching is a model capability (route to it with `has: ['implicit-caching']`); cached-token counts appear in the response `usage` fields. -`providerOptions.gateway.cacheControl`: `max-age=3600` (1h), `max-age=0` (bypass), `s-maxage=86400` (edge 24h), `stale-while-revalidate=600`. Cache key = model + prompt/messages + temperature + other generation params. Cache static knowledge, embeddings, identical-document extraction; never per-user conversations. +## Budgets, spend, errors -## Rate limits, budgets, errors +Budgets cap spend per **team, project, or API key** — dashboard (AI Gateway → Budgets) or `vercel ai-gateway budgets set team|project --limit 500 --refresh-period daily|weekly|monthly|none`. Checked before each request (soft cap), resets at UTC window start; optional email alerts at 50/75/100%; default budgets cover projects/keys without explicit ones; BYOK spend is not counted. Exceeded → HTTP `402` with `type: "quota_for_entity_exceeded"` — back off until reset. -Configure at vercel.com/{team}/{project}/settings → AI Gateway: requests/min per user, tokens/day per user, concurrent per user; Usage & Budgets for monthly thresholds, alert channels, per-tag budgets. Separate gateway keys per environment/project keep budgets isolated. Dashboard has traces/token counts/spend but no programmatic metrics API — pre-estimate tokens (~chars/4) to reject oversized prompts; the response `usage` field gives actual counts for tracking. Route cheap models for classification, expensive for generation. +Query spend programmatically: Custom Reporting API `GET https://ai-gateway.vercel.sh/v1/report?group_by=model|user|tag|provider` (attach `user`/`tags` to requests to enable; surcharged per write/query) and the Usage & Billing API for credit balance + generation lookup. -`APICallError.isInstance(error)` then switch on `statusCode`: `429` rate-limited (read `retry-after` response header), `402` hard budget limit reached (degrade gracefully), `503` service unavailable, `400` invalid model ID, else rethrow. Long generations: prefer `streamText` over `generateText` to avoid timeouts. +`APICallError.isInstance(error)` then switch on `statusCode`: `429` rate-limited (free-tier per-model limits or provider limits — retry after wait), `402` budget or credits exhausted (degrade gracefully), `503` service unavailable, `400` invalid model ID, else rethrow. Long generations: prefer `streamText` over `generateText` to avoid timeouts. -## Logging +## Observability -Every request logged: timestamp, model, provider used, token counts, latency, user ID, tags, status, failover chain. Read via dashboard vercel.com/{team}/{project}/ai → Logs, API `GET https://api.vercel.com/v1/ai-gateway/logs?projectId=…`, or Log Drains (Datadog/Splunk) for retention. Prompt/completion content is NOT logged by default (opt-in in project settings). Set `user` consistently for audit trails. +**AI Gateway Overview** tab in the dashboard sidebar (team scope, or per-project via the project dropdown): requests by model, TTFT, input/output token counts, spend; request summaries by project and API key. The **Logs** page searches individual requests by request ID, filters by model/provider/status, follows live, shows per-request provider routing, exports CSV/JSON. Detailed **AI Traces** live in Vercel Observability under AI; **Trace Drains** export an OpenTelemetry trace per request (with provider-attempt spans) to your own tool (Pro/Enterprise, billed via Drains). Extended retention needs Observability Plus. Prompt/completion content is not logged. ## Gateway vs direct provider SDK -Use the gateway by default — production (failover + observability), multi-provider, cost tracking/budgets, per-user limits, audit logging, multi-tenant SaaS, or simply fewer moving parts. Direct provider SDK only for: provider-specific features not exposed via gateway (e.g. computer use, custom fine-tuned endpoints), self-hosted models (vLLM/Ollama), or request-level HTTP transport control (custom proxies, mTLS). +Use the gateway by default — production (failover + observability), multi-provider, cost tracking/budgets, audit trails, multi-tenant SaaS, or simply fewer moving parts. Direct provider SDK only for self-hosted models (vLLM/Ollama) the gateway can't reach. For custom transport (proxies, headers, base URL) stay on the gateway with `createGateway({ baseURL, headers, fetch })`. + +## Coding agents via gateway -## Claude Code via gateway +One command sets up Claude Code, Codex, OpenCode, Cursor, and more (9 agents): `vercel ai-gateway coding-agents setup` — detects installed agents, provisions a key (macOS Keychain), writes each agent's own config with a diff preview, migrates existing sessions. Docs: https://vercel.com/docs/ai-gateway/coding-agents + +Manual Claude Code config (note the dedicated endpoint — no `/v1` suffix): ```bash -export ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh" +export ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh/claude-code" export ANTHROPIC_AUTH_TOKEN="" export ANTHROPIC_API_KEY="" # must be empty string — checked first; any non-empty value wins over AUTH_TOKEN +export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 # optional: /model picker lists gateway models (claude-code/ prefix) ``` -Claude Code Max subscriptions work: Anthropic auth stays on `Authorization` while the gateway uses `x-ai-gateway-api-key` — unified observability at no extra token cost. Override model defaults with `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` (any gateway model, e.g. `openai/gpt-5.4`). - -## Models, providers, pricing +Claude subscription (Max) works via `ANTHROPIC_CUSTOM_HEADERS="x-ai-gateway-api-key: Bearer "` — subscription auth stays on `Authorization`, gateway observability at no extra token cost. Routing through Bedrock/Vertex: set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`. The Claude Agent SDK routes the same way via `options.env`. -GPT-5.4 (March 2026): `openai/gpt-5.4` $2.50/M in, $15/M out — default for most workloads; `openai/gpt-5.4-pro` $30/$180 for maximum performance on complex tasks. Providers: OpenAI, Anthropic, Google, xAI, Mistral, DeepSeek, Amazon Bedrock, Azure OpenAI, Cohere, Perplexity, Alibaba (Qwen), Meta (Llama), + more (100+ models). +## Pricing -Pricing: zero markup (exact provider list price, managed keys or BYOK); $5 free credits per team per month (refreshes every 30 days); pay-as-you-go credits with optional auto top-up; BYOK has zero gateway fees. +Zero markup, no platform fee — provider list price, managed keys or BYOK. Free tier: monthly free credits (start on first request), a subset of models, per-model rate limits (429 when exceeded); purchasing credits moves the team to the paid tier (higher limits, full catalog, auto top-up; monthly free credit ends). BYOK (paid tier) has no gateway fee; failed BYOK requests retry on system credentials billed to credits. Surcharges only for opt-in extras: team-wide provider allowlist and team-wide ZDR ($0.10/1k requests; the per-request `only`/`zeroDataRetention` options are free), Custom Reporting writes/queries, Trace Drains. Live per-model pricing: https://ai-gateway.vercel.sh/v1/models/endpoints -## Multimodal +## Modalities -Text and image generation route through the gateway; embeddings need a direct provider SDK. +Text, image, and video generation, speech-to-text, text-to-speech, realtime voice, embeddings, and reranking all route through the gateway — no separate provider integrations, including embeddings. ```ts -// multimodal LLM — images arrive in result.files -const r = await generateText({ model: 'google/gemini-3.1-flash-image-preview', prompt: 'A sunset' }) -const images = r.files.filter(f => f.mediaType?.startsWith('image/')) +import { generateImage } from 'ai' +const { image } = await generateImage({ model: gateway.imageModel('openai/gpt-image-2'), prompt: 'A sunset' }) -// image-only models -import { experimental_generateImage as generateImage } from 'ai' -const { images: gen } = await generateImage({ model: 'google/imagen-4.0-generate-001', prompt: 'A sunset' }) +import { experimental_generateVideo as generateVideo } from 'ai' +const { videos } = await generateVideo({ model: 'google/veo-3.1-generate-001', prompt: 'A sunset', aspectRatio: '16:9', duration: 8 }) ``` -Default image model: `google/gemini-3.1-flash-image-preview`. Full list: https://vercel.com/docs/ai-gateway/capabilities/image-generation +Multimodal LLMs also return images inline in `result.files`. Full per-modality guide (providers, constraints, realtime sessions): https://vercel.com/docs/ai-gateway/modalities ## Docs - https://vercel.com/docs/ai-gateway -- https://ai-sdk.dev/docs/foundations/providers-and-models -- https://ai-sdk.dev/docs/ai-sdk-core +- https://vercel.com/docs/ai-gateway/modalities +- https://vercel.com/docs/ai-gateway/observability-and-spend +- https://vercel.com/docs/ai-gateway/coding-agents +- https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway From eeb7e13e38522dc8cc86cc7ab0af89444c8085fe Mon Sep 17 00:00:00 2001 From: Walter Korman Date: Mon, 17 Aug 2026 21:41:09 -0700 Subject: [PATCH 3/4] [skills] Refresh ai-gateway versions and model slugs - AI SDK v7 is GA: ai@^6.0.0 -> ^7.0.0, @ai-sdk/gateway@^3.0.0 -> ^4.0.0 - Model count 100+ -> 300+ (347 unique slugs live at /v1/models) - anthropic/claude-sonnet-4.6 -> anthropic/claude-sonnet-5 - Dot-vs-hyphen examples switch to openai/gpt-5.6-sol, since claude-sonnet-5 has no dotted version and cannot demonstrate the rule - Clarify that gateway.getAvailableModels() gives typed TypeScript access to the same catalog, not just a lagging alternative --- generated/build-from-skills.manifest.json | 2 +- generated/skill-manifest.json | 6 +++--- skills/ai-gateway/SKILL.md | 16 ++++++++-------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index 1765d63..0587541 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-08-18T03:29:01.849Z", + "generatedAt": "2026-08-18T04:39:35.029Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index d9b815e..7b3c593 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-08-18T03:29:03.277Z", + "generatedAt": "2026-08-18T04:39:35.551Z", "version": 2, "skills": { "access-protected-vercel-deployment": { @@ -153,7 +153,7 @@ "validate": [ { "pattern": "\\b(claude|gpt|gemini|llama|mistral|qwen|deepseek)[a-z0-9-]*-\\d+-\\d+[a-z0-9-]*\\b", - "message": "Model slug uses hyphens — use dots not hyphens for version numbers (e.g., claude-sonnet-4.6)", + "message": "Model slug uses hyphens — use dots not hyphens for version numbers (e.g., gpt-5.6-sol)", "severity": "error" }, { @@ -163,7 +163,7 @@ }, { "pattern": "gateway\\(['\"][^'\"/]+['\"]\\)", - "message": "Model string missing provider/ prefix — use provider/model format (e.g., openai/gpt-5.4, anthropic/claude-sonnet-4.6)", + "message": "Model string missing provider/ prefix — use provider/model format (e.g., openai/gpt-5.4, anthropic/claude-sonnet-5)", "severity": "error" }, { diff --git a/skills/ai-gateway/SKILL.md b/skills/ai-gateway/SKILL.md index 0044f05..8a24307 100644 --- a/skills/ai-gateway/SKILL.md +++ b/skills/ai-gateway/SKILL.md @@ -20,7 +20,7 @@ metadata: validate: - pattern: '\b(claude|gpt|gemini|llama|mistral|qwen|deepseek)[a-z0-9-]*-\d+-\d+[a-z0-9-]*\b' - message: 'Model slug uses hyphens — use dots not hyphens for version numbers (e.g., claude-sonnet-4.6)' + message: 'Model slug uses hyphens — use dots not hyphens for version numbers (e.g., gpt-5.6-sol)' severity: error - pattern: AI_GATEWAY_API_KEY @@ -28,7 +28,7 @@ validate: severity: recommended - pattern: gateway\(['"][^'"/]+['"]\) - message: 'Model string missing provider/ prefix — use provider/model format (e.g., openai/gpt-5.4, anthropic/claude-sonnet-4.6)' + message: 'Model string missing provider/ prefix — use provider/model format (e.g., openai/gpt-5.4, anthropic/claude-sonnet-5)' severity: error - pattern: gpt-4o @@ -96,9 +96,9 @@ retrieval: > **Training data is outdated for this library.** Model slugs, providers, and capabilities change frequently. Before writing gateway code, fetch https://vercel.com/docs/ai-gateway; the live model list at https://ai-gateway.vercel.sh/v1/models is authoritative. Never guess model names or assume old slugs work. -Unified API for 100+ models across all major providers: routing, failover, cost tracking, observability; <20ms routing overhead; switch models/providers by changing a string. +Unified API for 300+ models across all major providers: routing, failover, cost tracking, observability; <20ms routing overhead; switch models/providers by changing a string. -Packages: `ai@^6.0.0` (required; plain `"provider/model"` strings auto-route through the gateway). `@ai-sdk/gateway@^3.0.0` optional (types, custom provider instances). +Packages: `ai@^7.0.0` (required; plain `"provider/model"` strings auto-route through the gateway). `@ai-sdk/gateway@^4.0.0` optional (types, custom provider instances). ## Usage @@ -111,7 +111,7 @@ No wrapper or extra package needed. Gateway options go under `providerOptions.ga ```ts await generateText({ - model: 'anthropic/claude-sonnet-4.6', + model: 'anthropic/claude-sonnet-5', providerOptions: { gateway: { order: ['vertex', 'anthropic'] } }, }) ``` @@ -121,9 +121,9 @@ await generateText({ ## Slug rules (critical) - Always `provider/model`: `openai/gpt-5.6-sol`. -- Versions use dots, never hyphens: `anthropic/claude-sonnet-4.6`, not `claude-sonnet-4-6`. -- Authoritative model lists: `GET https://ai-gateway.vercel.sh/v1/models` (IDs + capabilities) and `/v1/models/endpoints` (per-provider detail: live pricing, context length, ZDR/no-training flags). `gateway.getAvailableModels()` works in code but can lag behind these endpoints. -- The catalog moves fast — pick current defaults from the live list or https://vercel.com/ai-gateway/models instead of hardcoding from memory. **Never** fall back to training-data-era defaults (`openai/gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `claude-3-*`) — they are outdated and read as stale to users. Current docs examples use models like `openai/gpt-5.6-sol` and `anthropic/claude-sonnet-4.6`. +- Versions use dots, never hyphens: `openai/gpt-5.6-sol`, not `gpt-5-6-sol`. +- Authoritative model lists: `GET https://ai-gateway.vercel.sh/v1/models` (IDs + capabilities) and `/v1/models/endpoints` (per-provider detail: live pricing, context length, ZDR/no-training flags). `gateway.getAvailableModels()` from `@ai-sdk/gateway` exposes the same catalog in TypeScript — typed, in-code discovery without calling the HTTP endpoints yourself — but it can lag behind them. +- The catalog moves fast — pick current defaults from the live list or https://vercel.com/ai-gateway/models instead of hardcoding from memory. **Never** fall back to training-data-era defaults (`openai/gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `claude-3-*`) — they are outdated and read as stale to users. Current docs examples use models like `openai/gpt-5.6-sol` and `anthropic/claude-sonnet-5`. ## Auth (OIDC default) From d212dd30998e5b127f446ebabff3221adb5a9f38 Mon Sep 17 00:00:00 2001 From: Walter Korman Date: Mon, 17 Aug 2026 21:44:21 -0700 Subject: [PATCH 4/4] [skills] Trim getAvailableModels() note to one clause Drop the "typed, in-code discovery" aside and the "can lag behind them" caveat; the sentence now just states that getAvailableModels() exposes the same catalog in TypeScript. --- skills/ai-gateway/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/ai-gateway/SKILL.md b/skills/ai-gateway/SKILL.md index 8a24307..11d071f 100644 --- a/skills/ai-gateway/SKILL.md +++ b/skills/ai-gateway/SKILL.md @@ -122,7 +122,7 @@ await generateText({ - Always `provider/model`: `openai/gpt-5.6-sol`. - Versions use dots, never hyphens: `openai/gpt-5.6-sol`, not `gpt-5-6-sol`. -- Authoritative model lists: `GET https://ai-gateway.vercel.sh/v1/models` (IDs + capabilities) and `/v1/models/endpoints` (per-provider detail: live pricing, context length, ZDR/no-training flags). `gateway.getAvailableModels()` from `@ai-sdk/gateway` exposes the same catalog in TypeScript — typed, in-code discovery without calling the HTTP endpoints yourself — but it can lag behind them. +- Authoritative model lists: `GET https://ai-gateway.vercel.sh/v1/models` (IDs + capabilities) and `/v1/models/endpoints` (per-provider detail: live pricing, context length, ZDR/no-training flags). `gateway.getAvailableModels()` from `@ai-sdk/gateway` exposes the same catalog in TypeScript. - The catalog moves fast — pick current defaults from the live list or https://vercel.com/ai-gateway/models instead of hardcoding from memory. **Never** fall back to training-data-era defaults (`openai/gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`, `claude-3-*`) — they are outdated and read as stale to users. Current docs examples use models like `openai/gpt-5.6-sol` and `anthropic/claude-sonnet-5`. ## Auth (OIDC default)