Vercel AI SDK e Integração com Frontend
Nesta página
Atualizado em 3 de novembro de 2026 com base na documentação do AI SDK 7 (
ai7.0.x,@ai-sdk/react4.x): ouseChatfunciona comDefaultChatTransportesendMessage, as mensagens são apresentadas através departs, a rota devolvecreateUIMessageStreamResponse,systemtorna-seinstructionse o fornecedor@ai-sdk/xai5 já não suporta Chat Completions:xai()utiliza a API de Respostas (código verificado com o compilador TypeScript usandoai7.0.162 e@ai-sdk/xai5.0.38). A versão anterior utilizava a API do AI SDK 4 (input,handleSubmit,isLoading,toDataStreamResponse). Fontes: AI SDK, Chatbot · AI SDK, fornecedor xAI.
O Vercel AI SDK para Aplicações Web
O Vercel AI SDK é uma estrutura TypeScript concebida para integrar modelos de IA em aplicações web. Fornece hooks React, utilitários de streaming e uma abstração unificada que suporta nativamente xAI/Grok através do pacote @ai-sdk/xai.
Se estiver a construir uma aplicação Next.js, Nuxt, SvelteKit ou qualquer aplicação React que necessite de apresentar respostas em streaming, o Vercel AI SDK simplifica significativamente o trabalho.
Instalação
Instale o SDK principal e o fornecedor xAI:
npm install ai @ai-sdk/xai
Configure a sua chave de API nas variáveis de ambiente:
# .env.local
XAI_API_KEY=a-sua-chave-api
Lado do Servidor: Geração de Texto
A função generateText é o equivalente mais simples a client.chat.create(). Uma coisa mudou, e diz respeito diretamente a este curso: desde a versão 5 do fornecedor @ai-sdk/xai (setembro de 2026), compatível com o AI SDK 7, o fornecedor já não suporta o endpoint de Chat Completions. xai(model) utiliza a API de Respostas, que a xAI recomenda agora. O método xai.chat(model), que alguns guias de migração ainda citam, existiu apenas na versão 4 do fornecedor; para código que deva permanecer no Chat Completions, utilize o SDK OpenAI apontado para a xAI em vez disso (Lição 5).
import { generateText } from "ai";
import { xai } from "@ai-sdk/xai";
const { text } = await generateText({
model: xai("grok-4.7"), // API de Respostas xAI
instructions: "Você é um assistente técnico.",
prompt: "Explique o conceito de contentorização.",
});
console.log(text);
O fornecedor xai lê automaticamente XAI_API_KEY do ambiente; createXai() permite-lhe criar uma instância com definições personalizadas. A opção instructions substitui system, que ainda é aceite mas está obsoleto no AI SDK 7.
Streaming no Lado do Servidor
Para streaming, utilize streamText. A resposta lê fragmento por fragmento a partir de textStream:
import { streamText } from "ai";
import { xai } from "@ai-sdk/xai";
const result = streamText({
model: xai("grok-4.7"),
instructions: "Você é um assistente de ensino.",
messages: [
{ role: "user", content: "Como funciona uma base de dados relacional?" },
],
});
for await (const chunk of result.textStream) {
process.stdout.write(chunk);
}
Lado do Cliente: O Hook useChat
O hook useChat é a peça central no frontend. Gere o histórico da conversa, o streaming e o estado do pedido; o campo de entrada, no entanto, permanece um estado React simples que gere:
"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import { useState } from "react";
export default function ChatPage() {
const { messages, sendMessage, status } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const [input, setInput] = useState("");
return (
<div>
{messages.map((m) => (
<div key={m.id}>
<strong>{m.role === "user" ? "Você" : "Grok"}</strong>
{m.parts.map((part, i) =>
part.type === "text" ? <p key={i}>{part.text}</p> : null
)}
</div>
))}
<form
onSubmit={(e) => {
e.preventDefault();
if (input.trim()) {
sendMessage({ text: input });
setInput("");
}
}}
>
<input
value={input}
onChange={(e) => setInput(e.target.value)}
placeholder="Faça a sua pergunta..."
disabled={status !== "ready"}
/>
<button type="submit" disabled={status !== "ready"}>
Enviar
</button>
</form>
</div>
);
}
O que o useChat Gere Automaticamente
- Histórico de mensagens: Acumula trocas; cada mensagem carrega
parts(texto, chamadas de ferramentas…), apresente isto em vez do antigo campocontent - Streaming: Apresenta a resposta à medida que é gerada
- Estado do pedido:
statuséreadyquando uma nova mensagem pode ser enviada - Gestão de erros: Interceta erros de rede e de API
- Cancelamento:
stop()interrompe uma geração em curso
Rota de API Correspondente
O hook espera uma rota que devolva um fluxo de mensagens de interface. Eis a implementação com o Next.js App Router, modelada segundo o exemplo oficial do AI SDK 7:
// app/api/chat/route.ts
import {
convertToModelMessages,
createUIMessageStreamResponse,
streamText,
toUIMessageStream,
type UIMessage,
} from "ai";
import { xai } from "@ai-sdk/xai";
export async function POST(req: Request) {
const { messages }: { messages: UIMessage[] } = await req.json();
const result = streamText({
model: xai("grok-4.7"),
instructions: "Você é um assistente prestativo. Responda em inglês.",
messages: await convertToModelMessages(messages),
});
return createUIMessageStreamResponse({
stream: toUIMessageStream({ stream: result.stream }),
});
}
Duas conversões envolvem a troca: convertToModelMessages transforma as mensagens de interface recebidas do cliente em mensagens de modelo, e toUIMessageStream faz o inverso no fluxo de resposta. Os métodos toUIMessageStreamResponse() no resultado streamText ainda funcionam no AI SDK 7, mas estão obsoletos; quanto ao antigo toDataStreamResponse(), já não existe.
Pontos-chave
- O Vercel AI SDK suporta xAI/Grok através do pacote
@ai-sdk/xai generateTextpara respostas síncronas,streamTextpara streaming- O hook
useChatgere o estado completo de uma conversa no cliente createUIMessageStreamResponseetoUIMessageStreamdevolvem o fluxo esperado pelouseChat;toDataStreamResponse()já não existe- Desde o
@ai-sdk/xai5, o fornecedor já não suporta Chat Completions:xai()utiliza a API de Respostas; para permanecer no Chat Completions, utilize o SDK OpenAI - O fornecedor
createXai()deteta automaticamente a chave de API no ambiente