fx AI SDK harness adapter di Vercel: guida completa

Vercel ha aggiunto fx al livello harness di AI SDK il 31 agosto 2026. È ora possibile eseguire questo coding agent leggero tramite la stessa interfaccia HarnessAgent utilizzata per altri coding harness; tuttavia, il reale vantaggio pratico consiste nella riduzione del lavoro di integrazione, non in un agente magicamente intercambiabile.

Che cos'è in realtà l'fx AI SDK harness adapter

fx è un coding-agent harness e uno strumento da riga di comando. Un harness rappresenta il runtime che circonda la chiamata a un modello: gestisce il workspace, gli strumenti, le skill, le sessioni, i permessi, la compattazione del contesto e i sotto-agenti che consentono a un modello di portare a termine un lavoro di programmazione reale.

Questo lo rende molto diverso dalla semplice aggiunta di un altro model provider in AI SDK. Non si sta scambiando un modello di testo con un altro: si sta integrando un intero runtime di sviluppo software dietro un'interfaccia con cui la propria applicazione sa già comunicare.

Il nuovo adapter @ai-sdk/harness-fx si posiziona tra HarnessAgent e fx. Sotto il cofano, sfrutta l'Agent Client Protocol (ACP) come linguaggio comune per avviare una sessione, inviare un prompt, trasmettere i progressi in streaming, gestire i tool e rilasciare le risorse.

Il flusso operativo ora si articola così: l'applicazione comunica con HarnessAgent, l'adapter fx traduce la richiesta in comandi ACP, fx viene eseguito all'interno di una sandbox di rete e le sue chiamate verso i modelli transitano tramite Vercel AI Gateway.

Tutto il meccanismo risiede qui: l'applicazione gestisce un'unica interfaccia, mentre l'harness conserva il proprio comportamento specifico.

Perché è importante e cosa non dimostra

La vera differenza riguarda i costi di integrazione tecnica. Se il proprio prodotto racchiude già HarnessAgent, supportare fx non comporta più la creazione di un ulteriore session manager, parser di stream, bridge per i permessi o procedura di cleanup.

Ciò offre ai team di piattaforma un metodo molto più lineare per confrontare diversi harness dietro un'unica superficie di prodotto. Inoltre, consente alle applicazioni più compatte di aggiungere un runtime di programmazione supplementare senza dover mantenere uno stack di orchestrazione separato.

Il sito attuale di fx contrassegna l'agente come v0.0.7, sperimentale e distribuito con licenza Apache-2.0. Anche i pacchetti harness di AI SDK sono sperimentali. Questa soluzione è quindi idonea per un engineering spike controllato, ma non rappresenta ancora una dipendenza consolidata su cui fare affidamento a lungo termine.

Non esistono metriche pubbliche sul prima e dopo riguardo a tempi di configurazione, latenza, qualità del codice generato o riduzione delle spese. È importante non trasformare la presenza di una singola API in affermazioni prestazionali non dimostrate: l'adapter elimina il lavoro idraulico personalizzato, ma resta necessario valutare se fx sia all'altezza dei task sui propri repository.

Chi impiega fx direttamente dal terminale non noterà cambiamenti sostanziali. Lo stesso vale per le applicazioni che richiamano i modelli solo con le normali funzioni di generazione di AI SDK senza mai eseguire un coding harness. Questa novità assume rilevanza soprattutto quando si integrano coding agent all'interno di un prodotto commerciale o di una piattaforma interna.

Chi può utilizzarlo da subito

Un solo founder che aggiunge la correzione dei repository a un SaaS

Se un'applicazione accetta già un repository Git e richiede a un agente di risolvere un test fallito, è possibile mantenere invariata la gestione della sessione e dello streaming, selezionando semplicemente fx come harness per un gruppo di prova. Il vantaggio è un confronto reale all'interno dello stesso ambiente applicativo senza dover allestire un prototipo dedicato con un backend proprio.

Un team di agent platform che valuta diversi harness

Un team infrastrutturale può inviare lo stesso prompt di correzione a fx e a un altro harness supportato, catturare il medesimo stream applicativo e confrontare il tasso di completamento. All'interno del livello harness compaiono infatti anche Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode e Pi.

Il benchmark richiede comunque metriche di valutazione specifiche per harness: un'interfaccia standardizzata non rende identici il sistema dei permessi, i tool a disposizione, la compattazione del contesto o i passaggi di pianificazione interna.

Un'agenzia software che isola gli ambienti cliente

Un'agenzia può avviare una singola Vercel Sandbox per intervenire sul codice di un cliente, inviare il lavoro in streaming alla propria dashboard operatore e distruggere la sessione al termine dell'attività. Tale approccio isola l'area di lavoro del cliente dal processo host e fornisce al team un ciclo di vita univoco indipendentemente dall'agente impiegato.

Un team interno di developer tools per piccoli interventi

Un team dedicato agli strumenti interni può proporre fx per attività circoscritte, come la correzione di un test o la modifica di una piccola feature, conservando invariate le skill esistenti e la configurazione del server MCP sul livello harness. Il risultato è un runtime opzionale in più senza dover ridisegnare il front-end.

Il percorso pratico di implementazione

La documentazione ufficiale dell'harness fx fornisce una guida completa in TypeScript, da applicare in un progetto AI SDK configurato per TypeScript.

1. 1

   Installare i tre pacchetti

   Aggiungere il core dell'harness, l'adapter fx e l'adapter Vercel Sandbox:

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

2. 2

   Assegnare al runtime una credenziale Gateway

   Configurare VERCEL_OIDC_TOKEN oppure AI_GATEWAY_API_KEY nell'ambiente che avvia l'agente. In presenza di entrambe, l'adapter assegna la priorità a VERCEL_OIDC_TOKEN.

   Evitare l'inserimento della credenziale nel codice sorgente. La sandbox necessita di connettività di rete poiché la prima sessione provvede al download di fx e le sessioni successive richiedono la rete per interagire con i modelli e con il web.

3. 3

   Creare, trasmettere e distruggere una sessione

   Ecco l'esempio base documentato, completo di deallocazione sia in caso di successo che di errore:

   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

   Verificare permessi ed eventi prima dell'uso reale

   Eseguire innanzitutto un task innocuo sul repository. Controllare che l'applicazione riceva correttamente lo stream di testo, che le richieste di autorizzazione arrivino all'operatore e che la chiamata a session.destroy() venga invocata in caso di fallimento del task.

   Un dettaglio spesso trascurato riguarda la porta esposta: poiché fx comunica tramite un bridge ACP, la sandbox di rete deve renderne accessibile almeno una. L'esempio fa uso della porta 4000.

Se occorre realizzare un adapter per un agente diverso compatibile con ACP, la relativa guida all'adapter AI SDK ACP harness analizza nel dettaglio questo livello sottostante.

Analisi dei costi

fx è distribuito come software open source sotto licenza Apache-2.0, ma una sessione ospitata comporta comunque i costi relativi ai token dei modelli e all'infrastruttura Sandbox.

AI Gateway applica $0 di ricarico e $0 di costi di piattaforma sui token. Ciascun team Vercel ha a disposizione $5 al mese di credito nel piano gratuito per un set selezionato di modelli, sebbene con rate limit inferiori per modello. L'acquisto di crediti Gateway trasferisce il team al piano a pagamento ed esaurisce il credito mensile gratuito.

Sul fronte sandbox, l'esempio di riferimento iad1 fornito da Vercel quantifica un'attività di validazione del codice tramite AI della durata di 5 minuti con 2 vCPU e 4 GB di RAM a circa $0.03 ipotizzando un utilizzo della CPU al 100%. In base a tale tariffa di esempio, 1,000 attività comportano una spesa di calcolo Sandbox di circa $30, esclusi i token del modello. I costi effettivi di Active CPU possono risultare inferiori mentre l'agente attende l'I/O di rete o le risposte dei modelli.

L'uso di Pro Sandbox consuma in prima battuta il credito mensile di $20 incluso nel piano. Il timeout predefinito della sandbox è pari a 5 minuti: conviene quindi definire con cura il timeout del task e distruggere le sessioni concluse per evitare addebiti superflui.

I cinque limiti per l'uso in produzione

1. Entrambi i livelli sono sperimentali

Sia fx sia i pacchetti harness di AI SDK mantengono una classificazione sperimentale. La documentazione dell'harness segnala apertamente che tra una versione e l'altra possono verificarsi breaking change senza preavviso.

2. L'adapter fa riferimento all'ultima release di fx

La prima sessione esegue l'installer ufficiale di fx, il quale recupera in automatico l'ultima versione rilasciata. L'adapter imposta in modo fisso l'origine dell'installazione, l'eseguibile, il comando di avvio e la versione ACP; di conseguenza, createFx() non consente di bloccare questi dettagli su parametri specifici. Tale comportamento ostacola la riproducibilità se i requisiti di produzione impongono un binario convalidato e con versione bloccata.

3. La mappatura dei permessi non è lineare

I permessi allow-reads e allow-edits rimandano entrambi alla modalità ask di fx, mentre allow-all corrisponde a code. fx non offre una modalità che consenta di modificare i file richiedendo al contempo una conferma per i comandi da terminale: non si può dare per scontato che le denominazioni dei permessi a livello applicativo conservino il loro significato esatto.

4. ACP v1 presenta limitazioni nell'osservabilità

Gli eventi standard dei tool nativi possono omettere il nome programmatico dello strumento e i dati di input grezzi. Inoltre, ACP v1 non include la demarcazione dei singoli passaggi del modello né il consumo token per step, rendendo i log granulari e il monitoraggio dei costi meno precisi di quanto l'interfaccia unica lascerebbe sperare.

5. Molti controlli non sono portabili

Tramite questo percorso non sono disponibili la compattazione manuale portabile, l'indirizzamento a metà turno (mid-turn steering) o il filtraggio integrato dei tool. Manca inoltre il supporto all'output strutturato vincolato da schema. Un adapter ACP tende a esporre una porzione più ridotta delle capacità dell'harness rispetto a un adapter nativo; per questa ragione Vercel consiglia l'uso di adapter diretti per Claude Code e Codex, laddove supportati.

Come procedere operativamente

È consigliabile provare l'adapter fin da subito se si dispone già di un'applicazione basata su HarnessAgent, se si vuole testare fx su task circoscritti e se si può gestire una dipendenza con stato sperimentale. La strategia migliore consiste nell'isolare una singola tipologia di task, registrando percentuale di completamento, richieste di autorizzazione, correttezza del cleanup e consumo economico sia per i modelli che per la Sandbox.

È preferibile invece attendere qualora il progetto richieda un binario fx con versione bloccata, output strutturato, tracciamento dei token per singolo passaggio, mid-turn steering o una netta separazione tra permessi sui file e autorizzazioni da riga di comando. Si tratta di vincoli architetturali dell'interfaccia, non di errori di configurazione.

Nessun intervento è richiesto per chi impiega fx unicamente come CLI locale o gestisce applicazioni limitate alle semplici chiamate ai modelli. Non c'è motivo di introdurre un livello harness solo perché è stato rilasciato un adapter in più.

Per ulteriori analisi tecniche sugli strumenti che i team di sviluppo portano realmente in produzione, è disponibile la newsletter.