Integração com o Vercel AI SDK
Nesta página
Atualizado em 3 de novembro de 2026, com base na documentação do AI SDK 7 e na página Multi-agent da xAI: a função
xai()utiliza agora a API de Respostas (o aviso da versão anterior já não se aplica), a rota do Next.js deixou de usar a função removidatoDataStreamResponse(), e o mecanismo de contingência visa o modelogrok-4.7. O mapeamentolow/medium→ 4 agentes,high/xhigh→ 16 agentes provém da documentação da xAI. Fontes: AI SDK, fornecedor xAI · xAI, Multi-agent.
Multi-agent no ecossistema JavaScript
O Vercel AI SDK (ai) tornou-se um padrão para integrar modelos de IA em aplicações web JavaScript e TypeScript. Quando combinado com o fornecedor @ai-sdk/xai, permite-lhe aceder ao modo multi-agente do Grok a partir do Next.js, SvelteKit ou qualquer outra estrutura JavaScript, sem abandonar as abstrações que a sua equipa de front-end já conhece.
Instalação
Precisa de dois pacotes:
npm install ai @ai-sdk/xai
Estes dividem o trabalho: o @ai-sdk/xai gere a comunicação com a API da xAI, enquanto o ai fornece as funções genéricas generateText e streamText que utiliza, independentemente do fornecedor.
Configuração básica
import { xai } from "@ai-sdk/xai";
import { generateText } from "ai";
const { text } = await generateText({
model: xai.responses("grok-4.20-multi-agent-0309"),
prompt: "What are the latest JavaScript frameworks of 2026?",
providerOptions: {
xai: { reasoningEffort: "low" },
},
});
console.log(text);
O modo multi-agente exige a API de Respostas da xAI. Com as versões atuais (AI SDK 7 e @ai-sdk/xai 5), esta é a única API que o fornecedor utiliza: xai(model) já recorre a ela. Escrever xai.responses() torna essa escolha explícita, o que também protege o código executado numa versão mais antiga do SDK onde xai() passava pela API de Conclusões de Chat.
Controlo do número de agentes
Define o número de agentes através de providerOptions.xai.reasoningEffort:
// Passar como providerOptions para generateText ou streamText
const rapide = { xai: { reasoningEffort: "low" } }; // 4 agents
const approfondie = { xai: { reasoningEffort: "high" } }; // 16 agents
O mapeamento é o mesmo que viu com o OpenAI SDK: low e medium utilizam 4 agentes, enquanto high e xhigh utilizam 16. Assim, obtém os mesmos dois modos sob um nome de parâmetro diferente.
Streaming com streamText
Numa aplicação web, o streaming torna-se obrigatório: uma execução de pesquisa multi-agente pode demorar um minuto, e ninguém permanece diante de um ecrã vazio durante 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: "Analyze AI market trends in Europe",
providerOptions: {
xai: { reasoningEffort: "medium" },
},
});
for await (const chunk of result.textStream) {
process.stdout.write(chunk);
}
Numa aplicação Next.js que utiliza o App Router, nem sequer precisa de consumir o stream no servidor: uma rota de API pode devolvê-lo diretamente ao navegador.
// 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" },
},
});
// Raw text stream: on the client, read it with fetch,
// or with useChat and a TextStreamChatTransport
return createTextStreamResponse({
stream: toTextStream({ stream: result.stream }),
});
}
A opção reasoningEffort: "low" neste exemplo é uma escolha deliberada: numa rota chamada diretamente a partir da interface do utilizador, a latência de 16 agentes seria difícil de sustentar.
Gestão de erros
Como o modo multi-agente está em beta, uma indisponibilidade não deve resultar numa página quebrada. O padrão abaixo mostra a contingência mais simples: capturar o erro e repetir a mesma pergunta num modelo padrão:
try {
const { text } = await generateText({
model: xai.responses("grok-4.20-multi-agent-0309"),
prompt: "My question",
providerOptions: {
xai: { reasoningEffort: "low" },
},
});
return text;
} catch (error) {
console.error("Multi-agent error:", error);
// Fall back to a standard model
const { text } = await generateText({
model: xai("grok-4.7"),
prompt: "My question",
});
return text;
}
A contingência muda para um modelo padrão, grok-4.7, que não tem as restrições do modo multi-agente (com o AI SDK 7, xai() também utiliza a API de Respostas). Informe também o seu utilizador de alguma forma, pois a resposta de contingência será menos exaustiva do que a que ele esperava.
Caso de uso numa aplicação web
O caso de uso que melhor aproveita esta integração é a interface de pesquisa avançada: o utilizador faz uma pergunta complexa, a sua aplicação abre o stream e a resposta escreve-se no ecrã enquanto os agentes continuam a trabalhar em segundo plano.
A experiência resultante é surpreendentemente natural. O texto avança, por vezes pausa quando os agentes lançam uma pesquisa na web, e depois retoma. Estas pausas estão longe de ser um defeito: indicam ao utilizador que está a decorrer uma pesquisa real — desde que a sua interface as associe a um indicador, em vez de fazer parecer que o sistema bloqueou.
Pontos-chave
- Utilize
@ai-sdk/xaicomxai.responses()para o modo multi-agente - Controle o número de agentes com
providerOptions.xai.reasoningEffort streamTexté ideal para aplicações web interativas- O Vercel AI SDK integra-se nativamente com o Next.js e outras estruturas
- Planeie uma contingência para um modelo padrão em caso de erro