Déployer un agent avec Vercel AI Gateway

Introduction

Un Vercel AI Gateway agent est utile quand une application Next.js doit appeler plusieurs modèles avec une authentification, des logs et des règles de routage communs. Ce tutoriel construit une route App Router avec streaming et tool calling, puis la déploie avec des secrets séparés entre preview et production. Cette approche est à éviter si votre problème principal est l’orchestration durable, la mémoire ou les workflows longs : le Gateway route les appels LLM, mais ne remplace pas un moteur d’agents. Si vous hésitez encore sur la stack, commencez par notre analyse de Vercel AI SDK.

Résumé rapide

1. Installez AI SDK et Zod, puis liez le projet à Vercel.
2. Utilisez un identifiant creator/model : AI SDK passe alors par AI Gateway.
3. Exposez une route serveur avec un tool validé et un nombre d’étapes borné.
4. Configurez l’authentification par OIDC sur Vercel ou par AI_GATEWAY_API_KEY ailleurs.
5. Testez en preview, fixez budgets et limites, puis déployez avec vercel --prod.

Comprendre le rôle de Vercel AI Gateway

AI Gateway se place entre votre code et les fournisseurs de modèles. Il unifie l’authentification, les identifiants de modèles, le routage et l’observabilité. Avec AI SDK, une chaîne au format creator/model, par exemple openai/gpt-5.4-mini, sélectionne automatiquement le provider Gateway. Vous n’avez donc pas besoin d’installer un module par fournisseur pour ce chemin.

L’authentification mérite une décision explicite. Sur un déploiement Vercel, AI SDK sait utiliser le jeton OIDC fourni à l’exécution, sans clé longue durée. En local, sur un serveur externe ou en CI, AI_GATEWAY_API_KEY reste le chemin simple. Si cette variable existe, elle prend priorité sur OIDC, même si sa valeur est invalide. Évitez donc de conserver une ancienne clé dans les variables du projet lorsque vous voulez réellement tester OIDC.

Enfin, AI Gateway facture les tokens au prix catalogue du fournisseur, sans majoration de tokens annoncée. Cela ne signifie pas que tout est gratuit : crédits, options de reporting, allowlist globale, ZDR global ou drains de traces peuvent avoir leurs propres compteurs. La documentation officielle du pricing doit être relue avant chaque estimation contractuelle.

Déployer l’agent pas à pas

1. Préparer un projet minimal

Le tutoriel suppose une application Next.js App Router récente et Node.js compatible avec votre version d’AI SDK. Installez les seules dépendances utilisées par l’exemple :

npm install ai zod
npm install --save-dev vercel

Ne mettez jamais la clé Gateway dans une variable préfixée par NEXT_PUBLIC_. Pour un développement local hors vercel dev, ajoutez-la à .env.local sans la committer :

AI_GATEWAY_API_KEY=vck_...

Sur Vercel, OIDC est disponible automatiquement pour les requêtes de modèle. Vous pouvez néanmoins choisir une clé d’équipe si le même code doit tourner aussi hors Vercel. Dans les deux cas, la clé reste côté serveur.

2. Écrire une route avec tool calling borné

Créez app/api/agent/route.ts. Le tool ci-dessous est volontairement déterministe : en production, remplacez son corps par un appel à votre service météo avec timeout, validation et contrôle d’accès.

import { streamText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

export const runtime = 'nodejs';
export const maxDuration = 30;

const getWeather = tool({
  description: 'Retourne une météo de démonstration pour une ville autorisée',
  inputSchema: z.object({
    city: z.string().trim().min(2).max(80),
  }),
  execute: async ({ city }) => ({
    city,
    temperatureC: 18,
    condition: 'variable',
    source: 'demo',
  }),
});

export async function POST(request: Request) {
  const body = (await request.json()) as { prompt?: unknown };

  if (typeof body.prompt !== 'string' || body.prompt.length > 2_000) {
    return Response.json({ error: 'prompt invalide' }, { status: 400 });
  }

  const result = streamText({
    model: 'openai/gpt-5.4-mini',
    system:
      'Tu aides en français. Utilise getWeather pour une question météo. ' +
      'Ne présente jamais la valeur de démonstration comme une mesure réelle.',
    prompt: body.prompt,
    tools: { getWeather },
    stopWhen: stepCountIs(3),
    timeout: { totalMs: 25_000 },
  });

  return result.toTextStreamResponse();
}

Le modèle exact n’est pas un contrat durable : choisissez un slug actuellement visible dans le catalogue AI Gateway. stopWhen: stepCountIs(3) borne la boucle après exécution d’outils. La validation Zod limite l’entrée du tool, mais elle ne remplace pas l’autorisation métier. L’agent ne doit jamais recevoir un outil d’écriture sensible sans vérification côté serveur.

Testez localement :

npm run dev
curl -N http://localhost:3000/api/agent \
  -H 'content-type: application/json' \
  -d '{"prompt":"Quel temps fait-il à Lyon ?"}'

Le résultat attendu est un flux texte. Dans cet exemple, il doit signaler que la donnée météo est une démonstration. Une erreur d’authentification indique généralement une clé absente, une clé périmée ou une variable qui masque OIDC.

3. Lier le projet et configurer les environnements

Authentifiez la CLI, puis associez le dossier au bon projet :

npx vercel link
npx vercel env ls

Si vous utilisez une clé plutôt qu’OIDC, ajoutez des valeurs distinctes. La commande demande la valeur de façon interactive ; ne la passez pas dans l’historique du shell :

npx vercel env add AI_GATEWAY_API_KEY preview --sensitive
npx vercel env add AI_GATEWAY_API_KEY production --sensitive

Dans le dashboard, le chemin équivalent est Project → Settings → Environment Variables. Vérifiez la portée de chaque secret. Une preview issue d’une branche non fiable ne doit pas recevoir automatiquement les mêmes capacités qu’une production.

Déployez d’abord une preview :

npx vercel

Appelez l’URL temporaire avec un prompt valide, un prompt trop long et une requête sans JSON. Vérifiez ensuite les logs AI Gateway : statut, modèle, fournisseur, tokens, coût, durée et tentatives de routage. Les logs peuvent apparaître avec un délai. Quand la preview est validée :

npx vercel --prod

vercel deploy --prod est également accepté ; vercel --prod est la forme courte documentée. Un déploiement ne prouve pas que l’agent est sain : conservez un smoke test HTTP après promotion et une procédure de rollback.

4. Routage, limites et observabilité

Le Gateway peut trier des fournisseurs par coût, temps avant premier token ou débit, et définir des modèles de repli. Ne confondez pas fallback et retry aveugle : si un outil a déjà produit un effet externe, rejouer toute la boucle peut dupliquer l’action. Rendez les tools d’écriture idempotents et séparez l’appel LLM de la mutation métier.

Ajoutez une authentification utilisateur devant /api/agent, un rate limit par compte et un budget Gateway par projet ou clé. Les logs natifs donnent la vue modèle ; pour suivre une action métier complète, propagez aussi un identifiant de requête dans vos logs applicatifs. Le guide sur les audit logs d’agents IA détaille cette seconde couche.

Pour calculer le budget, utilisez les tokens mesurés plutôt qu’un faux « coût par requête » universel. La formule mensuelle est : requêtes × (tokens entrée × tarif entrée + tokens sortie × tarif sortie), en appliquant les tarifs par token affichés pour le modèle et le fournisseur choisis. Ajoutez ensuite les options Gateway réellement activées et votre coût Vercel hors modèle.

Scénario	Volume	Calcul à faire	Levier prioritaire
Petite équipe B2B	5 000 req/mois	Tokens moyens mesurés × tarifs du modèle	Budget par clé, sortie courte
SaaS mid-market	50 000 req/mois	Distribution p50/p95 des tokens, pas seulement moyenne	Modèle moins cher, cache si applicable, rate limit
Agent public	500 000 req/mois	Coût tokens + options + trafic abusif estimé	Quotas utilisateur, modèle de repli, alertes

À tokens et modèle identiques, le coût token via Gateway est annoncé sans markup par rapport au prix catalogue. Le delta réel vient donc surtout d’un routage différent, des options activées, du moyen de paiement et de l’exploitation. Pour une méthode complète, utilisez notre guide des coûts d’agents IA.

Exemple concret : valider une preview avant promotion

Supposons une application support qui doit répondre à une question et consulter un statut de commande. Avant de connecter la vraie base, gardez un tool factice comme celui du tutoriel. Déployez la branche gateway-preview, puis exécutez un jeu fixe de vingt requêtes : cinq sans tool, cinq avec tool, cinq entrées invalides et cinq tentatives d’injection demandant d’ignorer le système.

Pour chaque requête, enregistrez le code HTTP, le temps total, le nombre d’étapes, le modèle réellement servi et le coût rapporté. Le test est PASS si aucune entrée invalide n’atteint le modèle, si chaque requête tool reste sous trois étapes, si aucun secret n’apparaît dans la réponse et si les erreurs ont un format exploitable. Dans AI Gateway Logs, vérifiez aussi les tentatives de routage et l’attribution au bon projet.

Fixez ensuite un budget de preview faible et provoquez un dépassement contrôlé pour observer l’erreur. Testez enfin la panne du service métier : le tool doit retourner une erreur bornée, sans lancer une boucle infinie. Cette répétition transforme la preview en gate de production plutôt qu’en simple URL de démonstration.

Le CTA logique n’est pas une offre d’hébergement non vérifiée : validez d’abord votre choix avec Vercel AI SDK : faut-il l’utiliser ?, puis adaptez ces tests à vos outils réels.

Bonnes pratiques

Gardez les outils sensibles côté serveur et appliquez l’autorisation avant chaque lecture ou écriture. Validez taille et type des entrées, bornez les étapes, imposez un timeout global et évitez les retries sur une mutation non idempotente. Un fallback de modèle améliore la disponibilité, mais peut modifier la qualité, la latence et le coût : testez chaque route autorisée.

Séparez preview et production. Utilisez OIDC sur Vercel lorsque cela convient, ou des clés distinctes avec budgets limités. Révoquez les clés inutiles ; une variable AI_GATEWAY_API_KEY invalide peut masquer OIDC. N’envoyez pas de données sensibles avant d’avoir vérifié rétention, région, ZDR et conditions de chaque fournisseur.

Enfin, alertez sur coût, erreurs, latence p95 et boucles d’outils. Conservez des logs métier corrélés aux logs Gateway et un chemin dégradé lorsque le LLM est indisponible. Si votre agent exige des workflows de plusieurs minutes ou des compensations, gardez AI Gateway pour les appels de modèles et confiez l’orchestration à une couche durable.

Questions fréquentes

Vercel AI Gateway remplace-t-il OpenAI ou Anthropic ?

Non. AI Gateway route les requêtes vers des fournisseurs et modèles sous-jacents. Il unifie authentification, routage, facturation et observabilité, mais les capacités et conditions du modèle restent celles du fournisseur sélectionné. Vous devez toujours choisir les modèles, mesurer leur qualité et vérifier leur traitement des données.

Faut-il une clé AI_GATEWAY_API_KEY sur Vercel ?

Pas nécessairement. Sur Vercel, AI SDK peut utiliser automatiquement un jeton OIDC. Une clé Gateway reste utile en local, en CI ou sur une infrastructure externe. Attention : si AI_GATEWAY_API_KEY est définie, elle prend priorité sur OIDC, même lorsqu’elle est invalide.

Combien coûte un agent via Vercel AI Gateway ?

Le coût dépend du modèle, du fournisseur et des tokens d’entrée et de sortie. Vercel annonce zéro markup sur les prix token du fournisseur, mais certaines options ont des compteurs séparés. Mesurez les tokens par type de requête, appliquez les tarifs courants du catalogue, puis ajoutez les options et l’infrastructure réellement utilisées.

Comment tester un déploiement Vercel avant la production ?

Lancez npx vercel pour créer une preview, appelez sa route API avec des cas valides et invalides, puis contrôlez les logs Gateway et applicatifs. Utilisez des secrets et budgets propres à la preview. Ne lancez npx vercel --prod qu’après validation des tools, timeouts, limites et erreurs.

Articles liés

Vercel AI Gateway est pertinent pour un agent Next.js qui a besoin d’une couche d’accès aux modèles, pas d’un nouvel orchestrateur. Un déploiement fiable combine une route bornée, des secrets isolés, des budgets et des tests de preview. La prochaine étape consiste à mesurer les coûts et à renforcer l’audit des actions réelles.

• Vercel AI SDK : évaluer le fit de la stack
• Créer un premier agent IA
• Budgéter les coûts d’un agent IA
• Construire des audit logs pour agents IA
• Comprendre le routage de modèles