Vercel AI Gateway: proč přestat volat Anthropic SDK přímo

Půl roku jsem volal Anthropic přes @ai-sdk/anthropic ve všech produkčních deploymentech. Klasický pattern: npm install @ai-sdk/anthropic, hodit ANTHROPIC_API_KEY do Vercel ENV, přiložit do streamText({ model: anthropic('claude-sonnet-4-6') }) a hotovo. Funguje. Až do dne, kdy Anthropic na hodinu odpadl s 529 errors a já neměl kam přesměrovat. Tehdy jsem migroval na Vercel AI Gateway a přestal jsem se k SDK pattern vracet.

Co je AI Gateway a co řeší

Vercel AI Gateway je proxy pro LLM providery, kterou pustíš mezi tvojí aplikací a Anthropic/OpenAI/Google/xAI. Místo přímého SDK voláš model přes Gateway endpoint. To ti dá čtyři věci, které se těžko buildí samostatně:

1. Provider-agnostic model strings - 'anthropic/claude-sonnet-4-6', 'openai/gpt-5.1', 'google/gemini-3'. Žádný import { anthropic } from '@ai-sdk/anthropic'. Stejný kód, jiný string.
2. Fallback chain - když primary provider hodí 5xx nebo 429, Gateway switchne na sekundární během single requestu. Klient vidí jen úspěšný stream.
3. Centralizovaná observability - všechny requesty v jednom dashboardu, breakdown podle modelu, projektu, route. Bez Datadogu navíc.
4. OIDC auth na Vercel - Vercel deploy podepíše request, Gateway ověří. Žádný API key v ENV.

Před: přímý Anthropic SDK

Tohle byl můj pattern v DokladBotu, Marušce, customer support botech.

import { anthropic } from '@ai-sdk/anthropic';
import { streamText } from 'ai';
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: anthropic('claude-sonnet-4-6'),
    system: 'You are a helpful assistant.',
    messages,
    maxOutputTokens: 2048,
  });
  return result.toUIMessageStreamResponse();
}

Zdánlivě v pohodě. Tři problémy:

• API key v ENV. Když rotuju klíč (pravidelně, kvůli leak prevenci), musím přebuildit deploy. Dvouminutová pauza pro produkci.
• Single provider. Anthropic 529 = můj endpoint vrací 500. Žádný fallback.
• Per-project usage tracking. Anthropic Console mi řekne celkovou útratu na klíči, ale ne breakdown po routách.

Po: AI Gateway přes model string

import { streamText } from 'ai';
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: 'anthropic/claude-sonnet-4-6',
    system: 'You are a helpful assistant.',
    messages,
    maxOutputTokens: 2048,
  });
  return result.toUIMessageStreamResponse();
}

Ten string místo importu není kosmetická změna. AI SDK v6 detekuje string formát provider/model a routuje přes Gateway. Žádné @ai-sdk/anthropic v package.json. Žádné ANTHROPIC_API_KEY v ENV. Když deploy běží na Vercel a má linkly k AI Gateway integraci, OIDC token se připojí automaticky.

Lokální dev funguje stejně přes vercel env pull a vercel dev - Gateway klíč je pro lokální runtime, na deployi se používá OIDC.

Fallback chain za 2 řádky

Tohle je hlavní důvod, proč už zpátky nepůjdu. AI SDK v6 podporuje přímo v options:

import { streamText } from 'ai';
 
const result = streamText({
  model: 'anthropic/claude-sonnet-4-6',
  providerOptions: {
    gateway: {
      order: ['anthropic', 'openai'],
    },
  },
  messages,
});

order: ['anthropic', 'openai'] znamená: zkus Anthropic, když failne, hop na OpenAI ekvivalent. Gateway si interně namapuje claude-sonnet-4-6 → gpt-5.1 (nebo cokoliv si nakonfiguruješ jako equivalent).

Reálná příhoda: během demo deploye Marušky pro klienta padlo Anthropic na 47 minut s 529. Gateway switchnul na OpenAI fallback, demo dojelo, klient si nevšiml. Bez tohohle bych musel demo přerušit.

Cost cap a observability

Vercel dashboard má pro Gateway per-project budget. Já si na každý projekt nastavuju $5/day soft cap, $20/day hard cap. Jakmile soft cap přeteče, dostávám notification. Hard cap = Gateway vrátí 402 a já vím, že někde teče.

Edge cases, na kterých jsi mohl narazit

1. Streaming kompatibilita. AI Gateway plně podporuje streamText SSE flow. Žádný buffering navíc, latence < 50ms overhead vs přímý SDK call. Měřil jsem p95 240ms (gateway) vs 215ms (přímý) na typický 800-token response.

2. Tool calling napříč providery. anthropic/claude-sonnet-4-6 a openai/gpt-5.1 mají odlišné tool schemas, ale AI SDK v6 je normalizuje. Tools definuješ jednou, fallback funguje.

3. Lokální dev. Pokud nepoužíváš vercel dev, musíš si nastavit AI_GATEWAY_API_KEY v .env.local. Pro CI/CD pipeline je to extra secret, ale jen jeden - místo per-provider klíčů.

4. Pricing. Gateway si nepřipočítává markup. Platíš provider cenu plus minimální observability fee. Pro mě řádově $0.50/měsíc přes všechny projekty.

Migrace v existujícím projektu

V Marušce trvala migrace 9 minut:

# 1. Odstraň provider package
pnpm remove @ai-sdk/anthropic
 
# 2. Najdi všechny anthropic('...') volání
grep -rn "anthropic('" src/
 
# 3. Replace na model string
sed -i "s/anthropic('claude-sonnet-4-6')/'anthropic\/claude-sonnet-4-6'/g" src/**/*.ts
 
# 4. Smaž ANTHROPIC_API_KEY z Vercel ENV
vercel env rm ANTHROPIC_API_KEY production

Plus pull request s diff, který vypadá triviálně. Code review byl spíš o tom, jestli má smysl, než o správnosti změny.

Lessons

• Model string > SDK import je správný default pro AI features na Vercel. Provider-package per model je technical debt.
• Fallback chain zachraňuje demo prezentace. Aspoň jednou za rok ti primary provider odpadne, a ten den máš důležitou call.
• OIDC auth = méně secret rotation práce. Když nemáš API key v ENV, nemáš co kompromitovat.
• Cost cap nastav před prvním deployem. Jednou jsem nechal aplikaci s buggy retry logikou běžet noc - bez capu by to byla pětičíslo.
• AI SDK v6 dropy mají kompatibilní migrační path. Můžeš jet hybridně (některé routy na Gateway, jiné přímo) během migrace.

Co dál

• DokladBot case study → - projekt, kde Gateway dropnul provozní bolest na nulu
• Claude Code workflow → - jak Claude Code dělá review těchhle migrací
• Multi-tenant Postgres → - další "udělej to správně jednou" pattern

Pokud řešíš migraci z přímého SDK na Gateway na vlastním projektu, napiš mi. Většina migrací je pod 30 minut.