Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Integração com o Vercel AI SDK

Aula 7 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Multi-agent no ecossistema JavaScript
  2. Instalação
  3. Configuração básica
  4. Controlo do número de agentes
  5. Streaming com streamText
  6. Gestão de erros
  7. Caso de uso numa aplicação web
  8. Pontos-chave

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 removida toDataStreamResponse(), e o mecanismo de contingência visa o modelo grok-4.7. O mapeamento low/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/xai com xai.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