Integrazione con l'SDK AI di Vercel
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della documentazione dell’SDK AI 7 e della pagina Multi-agent di xAI:
xai()utilizza ora le API Responses (l’avviso della versione precedente non si applica più), la route di Next.js non utilizza più il metodo rimossotoDataStreamResponse(), e il fallback punta sugrok-4.7. La mappaturalow/medium→ 4 agenti,high/xhigh→ 16 agenti proviene dalla documentazione di xAI. Fonti: AI SDK, provider xAI · xAI, Multi-agent.
Multi-agent nell’ecosistema JavaScript
L’SDK AI di Vercel (ai) è diventato lo standard per integrare modelli di IA nelle applicazioni web JavaScript e TypeScript. In combinazione con il provider @ai-sdk/xai, ti consente di accedere alla modalità multi-agente di Grok direttamente da Next.js, SvelteKit o qualsiasi altro framework JavaScript, senza dover uscire dalle astrazioni che il tuo team front-end conosce già.
Installazione
Hai bisogno di due pacchetti:
npm install ai @ai-sdk/xai
Si dividono il lavoro: @ai-sdk/xai gestisce la comunicazione con le API di xAI, mentre ai fornisce le funzioni generiche generateText e streamText che utilizzi indipendentemente dal provider.
Configurazione di base
import { xai } from "@ai-sdk/xai";
import { generateText } from "ai";
const { text } = await generateText({
model: xai.responses("grok-4.20-multi-agent-0309"),
prompt: "Quali sono gli ultimi framework JavaScript del 2026?",
providerOptions: {
xai: { reasoningEffort: "low" },
},
});
console.log(text);
Il multi-agent richiede le API Responses di xAI. Con le versioni attuali (AI SDK 7 e @ai-sdk/xai 5), è l’unica API utilizzata dal provider: xai(model) vi passa già attraverso. Scrivere xai.responses() rende esplicita questa scelta, proteggendo anche il codice eseguito su una versione precedente dell’SDK in cui xai() passava attraverso le Chat Completions.
Controllo del numero di agenti
Imposti il numero di agenti tramite providerOptions.xai.reasoningEffort:
// Da passare come providerOptions a generateText o streamText
const rapide = { xai: { reasoningEffort: "low" } }; // 4 agenti
const approfondie = { xai: { reasoningEffort: "high" } }; // 16 agenti
La mappatura è la stessa che hai visto con l’SDK di OpenAI: low e medium utilizzano 4 agenti, mentre high e xhigh ne utilizzano 16. Ottieni quindi le stesse due modalità sotto un nome di parametro diverso.
Streaming con streamText
In un’applicazione web, lo streaming diventa obbligatorio: un’esecuzione di ricerca multi-agente può richiedere un minuto e nessuno rimane davanti a uno schermo vuoto per così tanto tempo.
import { xai } from "@ai-sdk/xai";
import { streamText } from "ai";
const result = streamText({
model: xai.responses("grok-4.20-multi-agent-0309"),
prompt: "Analizza le tendenze del mercato dell'IA in Europa",
providerOptions: {
xai: { reasoningEffort: "medium" },
},
});
for await (const chunk of result.textStream) {
process.stdout.write(chunk);
}
In un’applicazione Next.js che utilizza l’App Router, non hai nemmeno bisogno di consumare lo stream sul server: una route API può restituirlo direttamente al browser.
// app/api/research/route.ts
import { xai } from "@ai-sdk/xai";
import { createTextStreamResponse, streamText, toTextStream } from "ai";
export async function POST(req: Request) {
const { query } = await req.json();
const result = streamText({
model: xai.responses("grok-4.20-multi-agent-0309"),
prompt: query,
providerOptions: {
xai: { reasoningEffort: "low" },
},
});
// Stream di testo grezzo: sul client, leggilo con fetch,
// oppure con useChat e un TextStreamChatTransport
return createTextStreamResponse({
stream: toTextStream({ stream: result.stream }),
});
}
Il valore reasoningEffort: "low" in questo esempio è una scelta deliberata: su una route chiamata direttamente dall’interfaccia utente, la latenza di 16 agenti sarebbe difficile da sostenere.
Gestione degli errori
Poiché il multi-agent è in beta, un’interruzione del servizio non deve trasformarsi in una pagina rotta. Il pattern seguente mostra il fallback più semplice: cattura l’errore e ripeti la stessa domanda su un modello standard:
try {
const { text } = await generateText({
model: xai.responses("grok-4.20-multi-agent-0309"),
prompt: "La mia domanda",
providerOptions: {
xai: { reasoningEffort: "low" },
},
});
return text;
} catch (error) {
console.error("Errore multi-agent:", error);
// Fallback su un modello standard
const { text } = await generateText({
model: xai("grok-4.7"),
prompt: "La mia domanda",
});
return text;
}
Il fallback passa a un modello standard, grok-4.7, che non ha i vincoli del multi-agent (con l’SDK AI 7, anche xai() utilizza le API Responses). Informa comunque l’utente in qualche modo, perché la risposta di fallback sarà meno approfondita di quella che si aspettava.
Caso d’uso in un’applicazione web
Il caso d’uso che sfrutta al meglio questa integrazione è l’interfaccia di ricerca avanzata: l’utente pone una domanda complessa, la tua applicazione apre lo stream e la risposta si scrive sullo schermo mentre gli agenti continuano a lavorare in background.
L’esperienza risultante è sorprendentemente naturale. Il testo avanza, a volte si ferma quando gli agenti lanciano una ricerca sul web, per poi riprendere. Queste pause sono tutt’altro che un difetto: dicono all’utente che è in corso una ricerca reale, a patto che la tua interfaccia le abbini a un indicatore invece di farle sembrare un blocco.
Punti chiave
- Utilizza
@ai-sdk/xaiconxai.responses()per il multi-agent - Controlla il numero di agenti con
providerOptions.xai.reasoningEffort streamTextè ideale per le applicazioni web interattive- L’SDK AI di Vercel si integra nativamente con Next.js e altri framework
- Prevedi un fallback su un modello standard in caso di errore