Harness AI con Vercel AI SDK: cosa cambia con l’adattatore ACP

Che cosa ha rilasciato davvero Vercel

Partiamo dai livelli che spesso vengono confusi.

Un modello genera la risposta successiva. Un harness trasforma quel modello in un esecutore operativo gestendo sessioni, tool, approvazioni, sandbox, istruzioni, compattazione e ciclo di lavoro. ACP, acronimo di Agent Client Protocol, offre a client e harness un linguaggio comune.

Il HarnessAgent di Vercel metteva già a disposizione delle applicazioni un’unica API per lavorare con gli harness. Mancava però il connettore. Prima di questo rilascio, Vercel aveva bisogno di un adattatore distinto per ciascun runtime, tra cui Claude Code, Codex, Pi, Deep Agents e OpenCode.

Il nuovo adattatore ACP per gli harness incapsula il protocollo, non uno specifico runtime. A createACP si forniscono il pacchetto NPM che implementa ACP per l’harness, il relativo eseguibile, le regole di autenticazione e le mappature di istruzioni e permessi. L’adattatore generico gestisce poi il bridge, il client ACP, l’inoltro dei tool, gli eventi, le approvazioni e il ciclo di vita della sessione.

È questa la logica dell’architettura: Vercel si occupa del bridge comune; il profilo del runtime raccoglie i dettagli che cambiano da un harness all’altro.

Al momento, l’adattatore supporta ACP versione 1, e soltanto la versione 1. La compatibilità riguarda il confine del protocollo: non garantisce che tutti gli harness si comportino allo stesso modo una volta collegati.

Vercel indica chiaramente quale strada seguire. Per questi due runtime vanno usati @ai-sdk/harness-claude-code o @ai-sdk/harness-codex. @ai-sdk/harness-acp è invece la scelta giusta quando l’harness dispone di un pacchetto compatibile, ma non di un adattatore diretto.

Perché l’adattatore per harness AI conta davvero

A cambiare è la quantità di lavoro necessaria per l’integrazione.

Un team che sviluppa tool non deve più ricostruire la gestione delle sessioni, la traduzione degli eventi, il flusso delle approvazioni, l’inoltro dei tool dell’host e il ciclo di vita soltanto per collocare un altro runtime ACP dietro HarnessAgent. Gli basta scrivere il profilo del runtime, lasciando il resto dell’applicazione sulla stessa API per harness.

In questo modo resta protetto anche il livello di prodotto. Sia HarnessAgent.generate() sia HarnessAgent.stream() restituiscono risultati compatibili con AI SDK. Un team che usa già useChat può mantenere invariato il flusso dell’interfaccia e sostituire il worker sottostante.

Questo rilascio non migliora la velocità, i costi o le capacità di un harness. Non uniforma le implementazioni ACP e non sostituisce la sandbox. Ogni harness ACP richiede comunque una sandbox di rete con almeno una porta esposta.

Per chi usa direttamente Claude Code, Codex o un altro coding agent cambia ben poco. Questa funzionalità interessa soprattutto chi costruisce il prodotto intorno a quegli agenti.

Chi può usarlo da subito

Chi sviluppa tool per developer e vuole supportare AI SDK

Immaginiamo un’azienda che offre un coding harness e pubblica già un pacchetto NPM compatibile con ACP. Ora può definire un solo profilo createACP e offrire agli utenti di AI SDK un accesso supportato al proprio runtime.

Il vantaggio è una distribuzione più semplice. Il team continua a gestire installazione, autenticazione, istruzioni e permessi specifici del pacchetto; l’adattatore di Vercel si occupa dell’infrastruttura condivisa.

Un platform engineer che gestisce più runtime

Una piattaforma di engineering di medie dimensioni potrebbe volere un agente per correggere repository, un altro per le migrazioni e un harness interno per le automazioni aziendali. Il platform engineer può mantenere un unico contratto per sessioni e risultati, scegliendo poi un profilo harness diverso per ogni attività.

Le differenze di comportamento non scompaiono. Vengono spostate in profili espliciti, più facili da esaminare rispetto a stack di orchestrazione separati.

Un team SaaS con un’interfaccia AI SDK esistente

Un team di prodotto può aggiungere un worker per il coding basato su ACP dietro un’applicazione AI SDK già esistente, senza rifare l’interfaccia di chat. La modifica concreta è sul server: si crea il profilo dell’harness, si collega una sandbox, si avvia una sessione e si restituisce lo stesso tipo di risultato, in streaming o completo, che l’interfaccia già gestisce.

Se la scelta riguarda ancora l’agente da adottare, e non la sua integrazione in un prodotto, conviene partire dal confronto tra coding agent. Questo adattatore entra in gioco dopo quella decisione di prodotto.

Un security engineer che definisce il perimetro

Per il security engineer i punti di controllo sono ben definiti. Le credenziali possono essere intermediate: il processo ACP nella sandbox vede segnaposto, mentre i valori reali vengono aggiunti alle richieste in uscita. Le modalità di autorizzazione si possono associare a quelle effettivamente supportate dal runtime, impostando su null le opzioni non disponibili, così da provocare un errore anziché ampliare tacitamente l’accesso.

Questo non rende il sistema automaticamente sicuro, ma offre un punto preciso in cui codificare e verificare le regole di sicurezza.

Il percorso di adozione

Un esempio completo tratto dalla documentazione

Per prima cosa si installano i pacchetti dell’harness, dell’adattatore ACP e di Vercel Sandbox:

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

La demo minima senza scorciatoie usa il profilo Codex ACP completo di Vercel, perché mostra nello stesso punto installazione del pacchetto, credenziali dirette, configurazione di AI Gateway, istruzioni e permessi. È un esempio di collegamento, non un invito a scegliere ACP per Codex. Per un’integrazione Codex reale, Vercel preferisce l’adattatore diretto.

Il codice seguente riproduce il profilo e il flusso di chiamata attualmente documentati. Per l’autenticazione diretta deve essere disponibile CODEX_API_KEY oppure OPENAI_API_KEY. Se è presente AI_GATEWAY_API_KEY o VERCEL_OIDC_TOKEN, il percorso predefinito auth: 'auto' sceglie invece 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’errore più comune è considerare il profilo del runtime come la semplice somma di un nome di pacchetto e una chiave API. Anche la mappatura dei permessi, la mappatura delle istruzioni, la porta della sandbox, il confine delle credenziali e la chiusura della sessione fanno parte dell’integrazione.

I limiti, senza giri di parole

I pacchetti harness sono sperimentali. Tra una release e l’altra sono previste modifiche incompatibili, quindi non è una dipendenza da aggiornare automaticamente in produzione senza verifiche.

Il pinning dei pacchetti richiede una decisione esplicita. La sorgente semplice consente di fissare una versione esatta, come nell’esempio che blocca @agentclientprotocol/codex-acp alla 1.1.4. Se la versione viene omessa, la sandbox installa il tag latest del pacchetto e quella versione resta fuori dall’identità dell’harness. Per una build riproducibile occorre usare la sorgente con lockfile, includendo package.json e pnpm-lock.yaml; Vercel esegue l’installazione con pnpm install --frozen-lockfile.

ACP versione 1 presenta inoltre limiti concreti:

• Non espone i confini dei passaggi del modello né il consumo per singolo passaggio. L’adattatore deduce quei confini, mentre il consumo per passaggio resta sconosciuto.
• Non offre API portabili per la compattazione manuale o lo steering durante l’esecuzione.
• Non consente di filtrare in modo portabile i tool integrati dell’harness. Il filtro dei tool dell’host continua a funzionare, ma il tentativo di filtrare quelli integrati in ACP genera un errore.
• Se cambia il catalogo dei tool dell’host, l’implementazione ACP deve aggiornare il proprio elenco di tool MCP. Un’implementazione non aggiornata restituisce un errore esplicito.

Nelle pagine Vercel consultate per questo rilascio non è indicato un prezzo separato per @ai-sdk/harness-acp. Questo non significa che gli agenti siano “gratis”. L’architettura comprende comunque un percorso di autenticazione del modello e richiede una sandbox di rete, quindi restano validi costi e controlli già previsti per il runtime.

Il limite più profondo riguarda la fedeltà. ACP offre una connessione comune, mentre un adattatore diretto può rappresentare più da vicino il comportamento nativo di un harness. La standardizzazione riduce il lavoro di integrazione, ma non cancella il runtime sottostante.

Cosa conviene fare adesso

La regola pratica è semplice.

Conviene muoversi già questa settimana se si gestisce un harness compatibile con ACP privo di un adattatore diretto per AI SDK, oppure se il team di piattaforma deve collocare diversi runtime di questo tipo dietro un unico contratto applicativo. Il primo passo è creare un profilo essenziale, fissare la versione del pacchetto e testare ogni permesso e percorso di errore.

Meglio aspettare se le policy di produzione non ammettono un pacchetto sperimentale, se è indispensabile misurare con precisione il consumo di ogni passaggio oppure se compattazione manuale e steering durante l’esecuzione sono controlli essenziali.

Chi usa Claude Code o Codex dovrebbe restare sull’adattatore diretto. È già il percorso raccomandato da Vercel e costringe meno il comportamento entro i limiti del protocollo.

Non cambia nulla per chi chiama direttamente i modelli, usa un coding agent come utente finale o non deve eseguire un harness all’interno della propria applicazione.

Per altri approfondimenti chiari sugli strumenti che stanno cambiando il modo in cui i team rilasciano software, iscriviti alla newsletter.