Agent IA avec Vercel AI SDK : comprendre l’adaptateur ACP

Ce que Vercel a vraiment livré pour un agent IA

Commençons par distinguer les couches que l’on confond souvent.

Un modèle produit la réponse suivante. Un harness transforme ce modèle en exécutant : il gère les sessions, les outils, les autorisations, les sandbox, les instructions, la compaction et la boucle de travail. ACP, pour Agent Client Protocol, fournit un langage commun au client et au harness.

Le HarnessAgent de Vercel offrait déjà aux applications une API unique pour travailler avec différents harness. Il manquait toutefois le connecteur. Avant cette version, Vercel devait créer un adaptateur propre à chaque runtime, notamment pour Claude Code, Codex, Pi, Deep Agents et OpenCode.

Le nouvel adaptateur ACP pour harness encapsule le protocole plutôt qu’un runtime précis. Il suffit de fournir à createACP le package NPM qui implémente ACP pour le harness, son exécutable, les règles d’authentification ainsi que la correspondance des instructions et des autorisations. L’adaptateur générique prend ensuite en charge la passerelle, le client ACP, le relais des outils, les événements, les approbations et le cycle de vie des sessions.

Toute l’idée tient dans cette séparation : Vercel maîtrise la passerelle commune, tandis que le profil du runtime décrit ce qui varie d’un harness à l’autre.

L’adaptateur prend actuellement en charge ACP version 1, et uniquement la version 1. La compatibilité s’arrête à la frontière du protocole : elle ne garantit pas que tous les harness se comportent de la même façon une fois connectés.

Vercel tranche clairement entre les deux options. Pour ces runtimes, utilisez @ai-sdk/harness-claude-code ou @ai-sdk/harness-codex. Réservez @ai-sdk/harness-acp aux harness disposant d’un package compatible, mais dépourvus d’adaptateur direct.

Pourquoi cet adaptateur ACP est important

Ce qui change, c’est la charge d’intégration.

Une équipe devtools n’a plus à recréer la gestion des sessions, la traduction des événements, le circuit d’approbation, le relais des outils de l’hôte et le cycle de vie pour placer un nouveau runtime ACP derrière HarnessAgent. Elle écrit le profil du runtime et conserve la même API de harness dans le reste de l’application.

La couche produit reste ainsi protégée. HarnessAgent.generate() comme HarnessAgent.stream() renvoient des résultats compatibles avec AI SDK. Une équipe qui utilise déjà useChat peut donc conserver le fonctionnement de son interface tout en remplaçant l’exécutant en arrière-plan.

Cette version ne rend pas un harness plus rapide, moins cher ou plus performant. Elle n’uniformise pas non plus les implémentations ACP et ne remplace pas la sandbox. Chaque harness ACP exige toujours une sandbox réseau avec au moins un port exposé.

Pour les personnes qui utilisent directement Claude Code, Codex ou un autre agent de code, presque rien ne change. Cette fonctionnalité vise celles qui construisent le produit autour de ces agents.

À qui cet adaptateur peut servir dès demain

Une startup devtools qui veut prendre en charge AI SDK

Imaginons que votre entreprise fournisse un harness de code et publie déjà un package NPM compatible ACP. Vous pouvez désormais définir un profil createACP et proposer aux utilisateurs d’AI SDK un moyen pris en charge d’accéder à votre runtime.

L’intérêt est la distribution. Votre équipe maintient l’installation propre au package, l’authentification, les instructions et les autorisations. L’adaptateur de Vercel s’occupe de toute la plomberie commune.

Un ingénieur plateforme qui gère plusieurs runtimes

Une plateforme d’ingénierie de taille moyenne peut vouloir confier la réparation de dépôts à un agent, les migrations à un autre et l’automatisation propre à l’entreprise à un harness interne. L’ingénieur plateforme conserve un contrat unique pour les sessions et les résultats, puis sélectionne un profil de harness différent selon la tâche.

Les écarts de comportement ne disparaissent pas. Ils sont regroupés dans des profils nommés, plus faciles à examiner que plusieurs piles d’orchestration distinctes.

Une équipe SaaS dotée d’une interface AI SDK

Une équipe produit peut ajouter un agent de code adossé à ACP derrière une application AI SDK existante sans reconstruire son interface de chat. Le changement concret se fait côté serveur : créer le profil du harness, lui associer une sandbox, démarrer une session et renvoyer le même type de résultat, généré ou diffusé en streaming, que l’interface sait déjà traiter.

Si vous en êtes encore au choix de l’agent, et non à son intégration dans un produit, commencez par ce comparatif des agents de code. Cet adaptateur devient pertinent une fois cette décision produit prise.

Un ingénieur sécurité qui définit la frontière

L’ingénieur sécurité dispose de points de contrôle précis. Les identifiants peuvent passer par un intermédiaire : le processus ACP isolé dans la sandbox ne voit alors que des valeurs de substitution, tandis que les vraies valeurs sont ajoutées aux requêtes sortantes. Les modes d’autorisation peuvent être associés à ceux que le runtime prend réellement en charge ; les options non prises en charge sont définies sur null afin d’échouer, plutôt que d’élargir silencieusement l’accès.

Le résultat n’est pas une sécurité automatique, mais un emplacement clair où formaliser et tester les règles de sécurité.

Le parcours d’intégration

Un exemple documenté complet

Installez le harness, l’adaptateur ACP et les packages Vercel Sandbox :

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

La démonstration minimale la plus fidèle s’appuie sur le profil ACP complet de Codex fourni par Vercel, car il réunit l’installation du package, les identifiants directs, la configuration d’AI Gateway, les instructions et les autorisations. C’est un exemple de câblage, pas une recommandation en faveur d’ACP pour Codex. Pour une véritable intégration de Codex, Vercel privilégie l’adaptateur direct.

Le code ci-dessous reprend le profil et le flux d’appel actuellement documentés. Rendez CODEX_API_KEY ou OPENAI_API_KEY disponible pour une authentification directe. Si AI_GATEWAY_API_KEY ou VERCEL_OIDC_TOKEN est disponible, le chemin auth: 'auto' par défaut choisit AI Gateway.

import { createACP, type ACPPermissionModeMapping } from '@ai-sdk/harness-acp';
import { createCredentialRequestTransformation } from '@ai-sdk/harness/utils';
import { secureJsonParse } from '@ai-sdk/provider-utils';

export const codexACPHarness = createACP({
  harnessId: 'acp-codex',
  // Define the runtime's built-in tool names and input schemas to expose
  // provider-executed calls as typed HarnessAgent tools.
  // builtinTools: { ... },
  source: {
    type: 'npm-simple',
    packageName: '@agentclientprotocol/codex-acp',
    packageVersion: '1.1.4',
  },
  executable: 'codex-acp',
  forwardEnv: ['CODEX_CONFIG'],
  credentialEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
  credentialBrokering: ({ env }) => {
    const credential = env.CODEX_API_KEY ?? env.OPENAI_API_KEY;
    if (!credential) return [];
    const config =
      env.CODEX_CONFIG == null
        ? undefined
        : (secureJsonParse(env.CODEX_CONFIG) as {
            model_provider?: string;
            model_providers?: Record<string, { base_url?: string }>;
          });
    const baseUrl =
      config?.model_providers?.[config.model_provider ?? '']?.base_url ??
      'https://api.openai.com/v1';
    return [
      createCredentialRequestTransformation({
        baseUrl,
        headers: { Authorization: `Bearer ${credential}` },
      }),
    ];
  },
  instructionMapping: {
    type: 'launch-env-json',
    variable: 'CODEX_CONFIG',
    path: ['developer_instructions'],
  },
  permissionModeMapping: {
    'allow-reads': null,
    'allow-edits': null,
    'allow-all': { type: 'session-mode', modeId: 'agent-full-access' },
  } as const satisfies ACPPermissionModeMapping,
  authentication: {
    methodId: 'api-key',
  },
  providerAuthentication: {
    gateway: {
      env: {
        CODEX_API_KEY: { $source: 'gateway-api-key' },
        CODEX_CONFIG: {
          model: 'openai/gpt-5.6-sol',
          model_provider: 'ai_gateway',
          model_providers: {
            ai_gateway: {
              name: 'AI Gateway',
              base_url: {
                $source: 'gateway-base-url',
                ensureSuffix: '/v1',
              },
              env_key: 'CODEX_API_KEY',
              wire_api: 'responses',
              supports_websockets: false,
              http_headers: {
                'User-Agent': { $source: 'client-app' },
                'x-client-app': { $source: 'client-app' },
              },
            },
          },
          model_supports_reasoning_summaries: true,
          preferred_auth_method: 'apikey',
        },
      },
    },
  },
});

L’erreur fréquente consiste à réduire le profil du runtime à un nom de package et une clé API. La correspondance des autorisations, celle des instructions, le port de la sandbox, la frontière des identifiants et le nettoyage de la session font eux aussi partie de l’intégration.

Ce qu’il faut savoir sans détour

Les packages de harness sont expérimentaux. Des changements incompatibles sont attendus d’une version à l’autre : ce n’est donc pas une dépendance de production que l’on peut laisser évoluer sans surveillance.

L’épinglage des packages demande une décision explicite. La source simple peut fixer une version exacte, comme dans l’exemple qui épingle @agentclientprotocol/codex-acp sur 1.1.4. Si la version est omise, la sandbox installe le tag latest du package, sans intégrer cette version à l’identité du harness. Pour une compilation reproductible, utilisez la source verrouillée avec un package.json et un pnpm-lock.yaml ; Vercel l’installe avec pnpm install --frozen-lockfile.

ACP version 1 présente également de vraies lacunes :

• Le protocole n’expose ni les limites entre les étapes du modèle ni l’usage par étape. L’adaptateur déduit ces limites, tandis que l’usage détaillé par étape reste inconnu.
• Il n’offre aucune API portable pour la compaction manuelle ou le pilotage en cours de traitement.
• Il ne permet pas de filtrer de manière portable les outils intégrés au harness. Le filtrage des outils de l’hôte reste possible, mais toute tentative de filtrer les outils ACP intégrés déclenche une erreur.
• Si le catalogue d’outils de l’hôte change, l’implémentation ACP doit actualiser sa liste d’outils MCP. Une implémentation obsolète échoue explicitement.

Les pages de Vercel consultées pour cette version n’indiquent aucun prix distinct pour @ai-sdk/harness-acp. N’en concluez pas que les « agents sont gratuits ». L’architecture comprend toujours un chemin d’authentification au modèle et exige une sandbox réseau ; vos coûts et contrôles d’exécution habituels continuent donc de s’appliquer.

La limite la plus profonde tient à la fidélité. ACP fournit une connexion commune, mais un adaptateur direct peut restituer plus précisément le comportement natif d’un harness. La standardisation réduit le travail d’intégration ; elle n’efface pas le runtime sous-jacent.

Que faire maintenant

Ma règle est simple.

Agissez cette semaine si vous gérez un harness compatible ACP sans adaptateur AI SDK direct, ou si votre équipe plateforme doit placer plusieurs de ces runtimes derrière un même contrat applicatif. Créez un profil léger, épinglez le package et testez chaque autorisation ainsi que chaque scénario d’échec.

Attendez si votre politique de production n’accepte pas un package expérimental, si vous avez besoin de données d’usage exactes à chaque étape, ou si la compaction manuelle et le pilotage en cours de traitement sont des contrôles indispensables.

Conservez l’adaptateur direct si vous utilisez Claude Code ou Codex. Vous disposez déjà de la voie recommandée par Vercel, qui contraint moins les comportements aux limites du protocole.

Vous n’êtes pas concerné si vous appelez directement les modèles, utilisez un agent de code en tant qu’utilisateur final ou n’avez pas besoin d’exécuter un harness au sein de votre propre application.

Pour recevoir d’autres décryptages accessibles des outils qui transforment la façon dont les équipes livrent leurs produits, abonnez-vous à la newsletter.