L'adaptateur fx AI SDK harness de Vercel expliqué

Vercel a intégré fx à la couche harness du AI SDK le August 31, 2026. Vous pouvez désormais exécuter cet agent de code léger via la même interface HarnessAgent que pour les autres environnements de développement autonomes. Le véritable gain réside dans la réduction du travail d'intégration, et non dans un agent magiquement interchangeable.

En quoi consiste réellement le vercel fx ai sdk harness adapter ?

fx est à la fois un harness pour agent de code et un outil en ligne de commande. Un harness représente l'environnement d'exécution autour de l'appel au modèle : il gère l'espace de travail, les outils, les compétences (skills), les sessions, les permissions, la compaction du contexte et les sous-agents qui permettent à un modèle d'accomplir une vraie tâche de développement.

Cette approche diffère fondamentalement de l'ajout d'un simple fournisseur de modèles dans le AI SDK. Vous ne remplacez pas un modèle de texte par un autre. Vous intégrez un environnement d'exécution complet pour le code derrière une interface que votre application sait déjà manipuler.

Le nouvel adaptateur @ai-sdk/harness-fx fait le pont entre HarnessAgent et fx. En coulisses, il exploite le protocole ACP (Agent Client Protocol) comme langage commun pour initialiser une session, envoyer un prompt, streamer la progression, orchestrer les outils et nettoyer les ressources.

Le workflow est désormais standardisé : votre application dialogue avec HarnessAgent, l'adaptateur fx traduit la requête en instructions ACP, fx s'exécute dans une sandbox réseau isolée, et ses requêtes vers les modèles transitent par Vercel AI Gateway.

C'est là tout l'intérêt. L'application conserve une interface unique, tandis que le harness préserve son comportement natif.

Pourquoi cette évolution compte (et ce qu'elle ne résout pas)

C'est la charge d'intégration qui a été allégée. Si votre produit repose déjà sur HarnessAgent, intégrer fx ne vous oblige plus à concevoir un gestionnaire de sessions dédié, un parseur de flux, une passerelle de permissions et une procédure de nettoyage.

Cela offre aux équipes plateforme une méthode propre pour benchmarker plusieurs environnements derrière une même surface produit. Cela permet également à une structure plus modeste d'intégrer un runtime de code supplémentaire sans maintenir une pile d'orchestration séparée.

Le site actuel de fx identifie l'agent comme étant en v0.0.7, expérimental et sous licence Apache-2.0. Les packages harness de AI SDK sont également expérimentaux. Le dispositif convient donc parfaitement pour un spike d'ingénierie isolé, mais il ne s'agit pas d'une dépendance silencieuse dont la stabilité à long terme est garantie.

Aucun chiffre officiel n'a été publié concernant les gains de temps d'installation, la latence, la qualité du code produit ou les économies financières. Il ne faut pas transformer « une API unifiée » en un argument de performance infondé. L'adaptateur supprime la plomberie personnalisée. Il vous incombe toujours d'évaluer si fx résout efficacement les problèmes de vos dépôts.

Les personnes utilisant fx directement dans un terminal ne sont pas concernées par ce changement. Il en va de même pour une application qui appelle simplement un modèle via les fonctions classiques de génération de AI SDK sans exécuter de harness de code. Cette mise à jour s'adresse aux développeurs qui intègrent des agents de code au cœur d'un produit ou d'une plateforme interne.

Cas d'usage concrets dès aujourd'hui

Un solo founder intégrant la correction de dépôts dans son SaaS

Imaginons que votre application reçoive un dépôt Git et demande à un agent de corriger un test en échec. Vous pouvez conserver la gestion de session et de flux existante, puis activer fx comme harness pour une cohorte de test. Le gain : une comparaison concrète au sein du même produit au lieu d'un prototype fx isolé nécessitant son propre backend.

Une équipe plateforme évaluant différents agents

Une équipe centrale peut soumettre le même prompt de correction à fx et à un autre harness compatible, capturer un flux applicatif identique et comparer le taux de complétion des tâches. Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode et Pi font également partie des runtimes répertoriés.

La comparaison nécessite cependant un barème propre à chaque agent. Une interface commune n'uniformise pas la gestion des permissions, l'outillage, la compaction du contexte ou les stratégies de planification interne.

Une agence isolant les interventions pour ses clients

Une agence peut instancier une Vercel Sandbox pour corriger le dépôt d'un client, streamer l'avancement dans son tableau de bord opérateur existant, puis détruire la session à la fin de la tâche. Cette approche protège la machine hôte des modifications du workspace client et maintient un modèle de cycle de vie unique, quel que soit l'agent retenu.

Une équipe d'outillage interne pour les correctifs ciblés

Une équipe developer-tools peut proposer fx pour des opérations restreintes — réparer un test unitaire ou ajuster une petite fonctionnalité — tout en conservant sa configuration de skills et de serveurs MCP au niveau de la couche harness. L'avantage direct : un nouveau runtime sans avoir à reconstruire une interface utilisateur.

Guide de mise en œuvre pratique

La documentation actuelle du harness fx propose une implémentation complète en TypeScript. Intégrez-la dans un projet AI SDK configuré pour TypeScript.

1. 1

   Installer les trois packages nécessaires

   Ajoutez le cœur du harness, l'adaptateur fx et l'adaptateur Vercel Sandbox :

   pnpm add @ai-sdk/harness @ai-sdk/harness-fx @ai-sdk/sandbox-vercel

2. 2

   Configurer les identifiants pour Gateway

   Définissez la variable d'environnement VERCEL_OIDC_TOKEN ou AI_GATEWAY_API_KEY sur l'environnement qui lance l'agent. Si les deux sont présentes, l'adaptateur donne la priorité à VERCEL_OIDC_TOKEN.

   Ne stockez jamais ces secrets dans le code source. La sandbox requiert un accès réseau, car la première session télécharge le binaire fx, et les sessions suivantes l'utilisent pour les requêtes de modèle et d'outillage web.

3. 3

   Créer, streamer et détruire une session

   Voici le code standard documenté, incluant le nettoyage des ressources en cas de succès comme d'erreur :

   import { HarnessAgent } from '@ai-sdk/harness/agent';
   import { fx } from '@ai-sdk/harness-fx';
   import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
   
   const agent = new HarnessAgent({
     harness: fx,
     model: 'openai/gpt-5.6-luna',
     sandbox: createVercelSandbox({
       runtime: 'node24',
       ports: [4000],
     }),
   });
   
   const session = await agent.createSession();
   
   let exitCode = 0;
   try {
     const result = await agent.stream({
       session,
       prompt: 'Check the test failures and fix the production code.',
     });
   
     for await (const part of result.stream) {
       if (part.type === 'text-delta') {
         process.stdout.write(part.text);
       }
     }
   } catch (err) {
     exitCode = 1;
     console.error(err);
   } finally {
     await session.destroy();
     process.exit(exitCode);
   }

4. 4

   Valider permissions et événements avant la mise en production

   Testez d'abord une tâche sans risque sur votre dépôt. Vérifiez que votre application intercepte bien le flux de texte, qu'une demande d'autorisation remonte correctement à l'opérateur et que session.destroy() s'exécute bien en cas d'échec.

   Le piège fréquent concerne l'ouverture des ports. fx communiquant via un bridge ACP, la sandbox réseau doit exposer au moins un port. L'exemple ci-dessus configure le port 4000.

Pour concevoir un adaptateur dédié à un autre agent compatible avec ACP, consultez notre guide de l'adaptateur ACP pour AI SDK qui détaille ces mécanismes de bas niveau.

Modèle de coûts

fx est un outil open source sous licence Apache-2.0, mais son exécution intégrée génère des coûts liés aux tokens du modèle et à la Sandbox.

AI Gateway applique $0 de marge et $0 de frais de plateforme sur les tokens. Chaque équipe Vercel dispose de $5 par mois de crédits gratuits sur un sous-ensemble de modèles, avec des quotas (rate limits) plus stricts par modèle. L'achat de crédits Gateway bascule automatiquement l'équipe sur le forfait payant et met fin à ce crédit mensuel offert.

Pour la partie Sandbox, les estimations de Vercel sur la région iad1 évaluent une tâche de validation de code par IA de 5 minutes (avec 2 vCPUs et 4 GB de mémoire) à environ $0.03 pour 100% d'utilisation CPU. À cette échelle, 1,000 tâches reviennent à environ $30 de calcul Sandbox, hors consommation de tokens. La dépense réelle en CPU actif peut être inférieure lorsque l'agent attend les réponses du modèle ou les retours réseau (I/O).

L'usage des Sandbox Pro s'impute en priorité sur les $20 de crédits mensuels du forfait. Le timeout par défaut d'une Sandbox étant de 5 minutes, configurez explicitement les délais d'expiration de vos tâches et assurez-vous de détruire les sessions terminées au lieu de les laisser ouvertes.

Les cinq limites majeures en production

1. Deux couches logicielles encore expérimentales

L'outil fx tout comme les packages harness de AI SDK portent la mention expérimentale. La documentation officielle prévient expressément que des breaking changes peuvent intervenir d'une version à l'autre.

2. Téléchargement systématique de la dernière version de fx

La session initiale lance le script d'installation officiel de fx, qui récupère automatiquement la toute dernière release. L'adaptateur fige la source d'installation, l'exécutable, la commande de démarrage et la version d'ACP, ce qui empêche createFx() de verrouiller ces paramètres. Cela pose un sérieux défi de reproductibilité si vos exigences de production imposent un binaire certifié et versionné.

3. Correspondance imparfaite des modes de permission

Les permissions allow-reads et allow-edits se traduisent toutes les deux par le mode ask dans fx. Le mode allow-all bascule vers code. fx ne propose pas d'état intermédiaire autorisant la modification des fichiers tout en réclamant une validation pour les commandes du terminal. Vous ne pouvez donc pas supposer que les libellés de permissions définis dans votre application conservent leur sémantique exacte.

4. Manque de granularité dans l'observabilité avec ACP v1

Les événements d'outils natifs omettent parfois le nom programmatique de la fonction et les données brutes saisies en entrée. De plus, ACP v1 ne fournit ni délimitation claire des étapes internes du modèle (step boundaries) ni décompte de l'usage par étape, ce qui limite le traçage fin et l'attribution précise des tokens par rapport à ce que l'interface unifiée laisse espérer.

5. Absence de portabilité sur plusieurs fonctionnalités avancées

Cette architecture ne supporte pas la compaction manuelle du contexte, l'orientation en cours d'exécution (mid-turn steering) ou le filtrage direct des outils. Les sorties structurées adossées à un schéma ne sont pas prises en charge. Un adaptateur ACP expose souvent moins de capacités qu'un adaptateur natif dédié, raison pour laquelle Vercel privilégie les adaptateurs directs pour Claude Code et Codex lorsqu'ils existent.

Que devriez-vous faire maintenant ?

Adoptez cet adaptateur dès aujourd'hui si votre application utilise déjà HarnessAgent, que vous souhaitez tester fx sur un scénario de code bien délimité, et que votre environnement tolère une dépendance expérimentale. Lancez l'évaluation sur une seule classe de tâches et mesurez précisément le taux de succès, les demandes d'intervention humaine, la fiabilité du nettoyage et les dépenses en Sandbox comme en tokens.

Attendez en revanche si votre infrastructure exige un binaire fx strictement verrouillé, des sorties structurées, une télémétrie détaillée par étape, du steering en cours de tour, ou une distinction stricte entre autorisation d'édition de fichiers et exécution dans le terminal. Ces restrictions découlent de l'interface actuelle et non d'erreurs de paramétrage.

Enfin, vous n'avez rien à modifier si vous utilisez fx exclusivement via votre terminal local ou si votre application se contente de requêtes textuelles classiques. Rien ne justifie d'introduire la couche harness si votre architecture ne manipule pas d'agents autonomes.

Pour découvrir d'autres analyses claires et détaillées sur les architectures d'IA déployées en production, abonnez-vous à la newsletter.