Adapter Grok Build per Vercel AI SDK: come funziona

Con l’adapter Grok Build, il 13 agosto 2026 Vercel ha aperto a Grok Build un accesso ufficiale a HarnessAgent di AI SDK 7. Un prodotto può così eseguire Grok Build attraverso la stessa interfaccia applicativa che Vercel offre oggi per nove coding harness supportati, senza dover ricostruire ogni volta il livello di orchestrazione.

Cosa ha rilasciato davvero Vercel con l’adapter Grok Build

Si tratta di un adapter, non di un nuovo modello Grok.

Per capirne il ruolo conviene separare i diversi livelli. Un modello genera risposte. Un coding harness trasforma il modello in un esecutore operativo, gestendo file, tool, sessioni, permessi e il ciclo che porta avanti il task. L’Agent Client Protocol, o ACP, è il linguaggio comune tra un client e un harness compatibile. Un adapter traduce quel protocollo nell’interfaccia già utilizzata dall’applicazione.

Il nuovo pacchetto di Vercel è @ai-sdk/harness-grok-build. Collega HarnessAgent alla CLI di Grok Build tramite ACP e, a un livello inferiore, si appoggia al pacchetto @ai-sdk/harness-acp.

Il percorso è quindi questo:

L’applicazione → HarnessAgent → adapter Grok Build → CLI di Grok Build dentro un sandbox

Il livello ACP generico fornisce l’infrastruttura di collegamento. L’adapter Grok Build è invece il connettore pronto all’uso: pacchetto, eseguibile, associazione delle credenziali, comando di avvio e mapping dei tool sono già definiti. Per approfondire il funzionamento del protocollo, è disponibile la guida all’adapter harness ACP di AI SDK. Qui ci concentriamo sul percorso operativo di Grok Build.

Prima di questo rilascio, aggiungere un runtime ACP significava definirne in autonomia il profilo. Con il lancio del 13 agosto, Grok Build ha ottenuto un adapter ufficiale ed è entrato nello stesso flusso di sessione di HarnessAgent già usato da Claude Code, Codex, Deep Agents, OpenCode e Pi. L’elenco disponibile allora è così salito a sei harness.

Dal 31 agosto 2026, l’aggiunta di fx da parte di Vercel ha portato l’elenco a nove harness supportati: Claude Code, Cline, Codex, Cursor, Deep Agents, fx, Grok Build, OpenCode e Pi. L’adapter fx amplia il catalogo, ma non cambia il funzionamento dell’adapter Grok Build.

L’espressione «stessa interfaccia» conta più di «stesso agente». Il contratto applicativo può restare invariato, ma comportamento dei tool, permessi, osservabilità e output del modello non diventano identici nei nove harness supportati.

Perché l’adapter Grok Build è importante

A cambiare è il lavoro necessario per l’integrazione.

HarnessAgent.generate() e HarnessAgent.stream() restituiscono risultati compatibili con AI SDK. Se il prodotto dispone già di un’interfaccia AI SDK per chat o task, Grok Build può inserirsi nel flusso di risultati esistente. Cambia l’harness lato server; l’interfaccia utente non ha bisogno di un nuovo formato di risposta solo perché cambia l’esecutore.

Per un team di piattaforma diventa più semplice confrontare i runtime o instradare task diversi. Il ciclo di vita delle sessioni e la struttura dello streaming possono restare condivisi, mentre l’harness viene scelto in funzione del lavoro da svolgere.

Questo rilascio non rende Grok Build più veloce, economico o accurato. Aggiunge una connessione ufficialmente supportata. Inoltre, non offre vantaggi a chi usa Grok Build soltanto dalla sua CLI: è pensato per chi sviluppa un prodotto o un sistema interno attorno ai coding agent.

Chi può usarlo subito

Il founder di un devtool che vuole aggiungere un runtime

Un prodotto di code review o riparazione dei repository basato su AI SDK può aggiungere Grok Build come ulteriore harness lato server, senza creare appositamente un’altra API di sessione e un diverso contratto di streaming.

L’intervento concreto è contenuto: si installa l’adapter, si collega lo stesso tipo di sandbox e si seleziona Grok Build quando lo richiedono il cliente o il task. Il vantaggio è un runtime in più senza un’altra superficie di prodotto da mantenere.

Il platform engineer che confronta nove harness

Un team di piattaforma può assegnare lo stesso task circoscritto su un repository a Grok Build e a un altro harness supportato, quindi confrontare qualità del risultato e modalità di errore all’interno di un unico flusso applicativo.

Il confronto deve però restare corretto. ACP versione 1 non espone sempre il consumo di ogni singolo passaggio; quando Grok non restituisce i totali, l’adapter non può quindi produrre un confronto pulito dei costi token per token. È possibile confrontare risultati e comportamento end-to-end, ma non presumere che ogni campo di osservabilità sia altrettanto completo.

Il team di strumenti interni che ripara repository

Un team dedicato agli strumenti interni può inviare un task di correzione dei test falliti a un workspace isolato, mostrare in streaming il testo dell’agente a un operatore e distruggere la sessione al termine del lavoro. Il confine del sandbox protegge l’host, mentre un ciclo di vita esplicito evita che le sessioni temporanee diventino infrastruttura dimenticata.

Il vantaggio è il controllo operativo: l’esecutore che modifica il codice lavora in un ambiente circoscritto e l’applicazione decide quando avviarlo e quando terminarlo.

Il responsabile di sicurezza o affidabilità che valuta il rilascio

Qui c’è una scelta concreta da compiere. L’autenticazione diretta usa XAI_API_KEY; quella tramite AI Gateway usa le credenziali del Gateway. La modalità predefinita auto sceglie AI Gateway quando trova quelle credenziali, altrimenti ricorre all’autenticazione diretta xAI.

Occorre inoltre verificare i permessi nel punto in cui i tool vengono effettivamente eseguiti. Grok Build non dichiara modalità di sessione ACP e alcune operazioni sicure integrate possono avvenire senza una richiesta di autorizzazione ACP. Una policy progettata per un altro harness non dimostra che Grok Build si comporti allo stesso modo.

Come configurare l’adapter Grok Build

La configurazione completa più breve usa Vercel Sandbox e le impostazioni predefinite dell’adapter.

1. 1

   Installa i pacchetti

   Aggiungi l’API comune degli harness, l’adapter Grok Build e l’implementazione di Vercel Sandbox:

   pnpm add @ai-sdk/harness @ai-sdk/harness-grok-build @ai-sdk/sandbox-vercel

2. 2

   Configura le credenziali del sandbox e del modello

   Per il percorso documentato con Vercel Sandbox, rendi disponibile VERCEL_OIDC_TOKEN. Per l’autenticazione diretta a Grok, fornisci XAI_API_KEY. Se scegli il Gateway, inserisci le credenziali AI Gateway necessarie; AI_GATEWAY_BASE_URL consente di sostituire l’URL di base quando serve. La selezione predefinita auth: 'auto' dell’adapter sceglie il percorso disponibile.

3. 3

   Crea, esegui e distruggi la sessione

   Usa l’attuale esempio dell’harness Grok Build:

   import { HarnessAgent } from '@ai-sdk/harness/agent';
   import { grokBuild } from '@ai-sdk/harness-grok-build';
   import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
   
   const agent = new HarnessAgent({
     harness: grokBuild,
     model: 'grok-build-0.1',
     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

   Prevedi un’installazione via rete alla prima sessione

   La prima sessione richiede accesso in uscita alla rete, perché l’harness ACP installa nel sandbox il pacchetto @xai-official/grok@1.0.5 bloccato a quella versione. Un sandbox privo di traffico in uscita si interrompe prima che l’agente possa produrre risultati utili.

Il dettaglio facile da trascurare è la porta. Grok Build richiede un sandbox di rete con almeno una porta esposta per il bridge ACP. L’esempio usa Node 24 e la porta 4000. Un oggetto sandbox privo di quel percorso di rete non rappresenta una configurazione equivalente.

L’esempio attuale passa model: 'grok-build-0.1' a HarnessAgent. Per intervenire sulle opzioni dell’adapter, sostituisci grokBuild con createGrokBuild(). È possibile scegliere autenticazione, inoltro delle credenziali, reasoning effort, server MCP, porta del bridge, timeout di avvio o una funzione personalizzata per il token del bridge. Se reasoningEffort viene omesso, Grok Build usa il valore predefinito della propria configurazione.

I limiti da conoscere

L’adapter eredita i limiti di ACP versione 1, e in produzione hanno conseguenze concrete.

• I dati di utilizzo sono incompleti. ACP non espone i confini dei singoli passaggi del modello né il relativo consumo. L’adapter deduce tali confini e, se Grok non fornisce i totali, segnala il consumo come sconosciuto.
• Non è possibile guidare in modo portabile un turno già in corso. ACP non offre un’API comune per intervenire a metà turno o avviare una compattazione manuale.
• Il filtraggio dei tool integrati è limitato. È possibile filtrare i tool dell’host, ma tentare di filtrare quelli integrati in Grok genera un errore di funzionalità non supportata.
• Il catalogo dei tool può diventare obsoleto. Quando cambia l’elenco dei tool dell’host, Grok Build deve aggiornare la propria lista MCP via ACP. Se conserva quella precedente, il turno fallisce in modo esplicito.

Esiste anche un rischio legato alla gestione delle release. I pacchetti harness di AI SDK sono sperimentali, quindi tra una versione e l’altra sono previste modifiche incompatibili. L’adapter Grok blocca internamente la versione della CLI e il comando di avvio ACP, e createGrokBuild() non permette di sostituire questi dettagli. Il percorso supportato risulta più semplice, ma è il pacchetto dell’adapter a decidere quando cambierà il runtime bloccato.

La credenziale predefinita del bridge è un token casuale da 32 byte. Se si sostituisce la funzione che lo genera, quella nuova deve restituire un valore adeguatamente segreto. È un controllo di sicurezza, non un posto comodo in cui inserire una stringa di sviluppo leggibile.

Infine, non si tratta di un annuncio sui prezzi. Il metodo scelto per autenticarsi a Grok e il sandbox di rete continuano ad avere costi operativi propri. L’adapter riduce il lavoro d’integrazione personalizzato, ma non elimina l’infrastruttura sottostante.

Cosa conviene fare adesso

Conviene agire questa settimana se AI SDK 7 è già in uso e si vuole rendere Grok Build un runtime di coding selezionabile. Parti da un task circoscritto su un repository, mantieni l’adapter predefinito, prova sia il percorso di successo sia quello di errore e verifica che la sessione venga eliminata.

Se un prodotto deve gestire più harness, esegui una breve valutazione prima di andare in produzione. Confronta risultati dei task, comportamento dei permessi, recupero dagli errori e costo totale del lavoro. Non usare il consumo per singolo passaggio come criterio decisivo, perché ACP potrebbe non fornirlo.

È meglio attendere se compattazione manuale, interventi a metà turno, misurazione esatta per singolo passaggio o allowlist dei tool integrati sono requisiti indispensabili. Sono limiti del protocollo, non errori di configurazione.

Non cambia nulla per chi usa direttamente Grok Build, chi interroga i modelli Grok senza un coding harness o chi non dispone di un’applicazione che debba passare da un runtime agente all’altro.

Per ricevere altre analisi pratiche sugli strumenti che stanno cambiando il modo in cui i team rilasciano software, iscriviti alla newsletter.