Um cliente fintech me ligou no final de 2023, com pânico genuíno na voz, porque seu time de desenvolvimento tinha passado seis semanas construindo uma interface de chat com streaming em cima da API do OpenAI e ainda assim estava quebrada no Mobile Safari. Condições de corrida. Problemas de chunking de tokens. A UI travava no meio da resposta. Seis semanas. Olhei para o codebase deles e era exatamente o que você esperaria: uma implementação feita na mão de ReadableStream, uma camada de gerenciamento de estado customizada para os tokens em streaming, lógica de retry copiada de uma resposta do Stack Overflow de três anos atrás. A coisa estava toda remendada.
Reescrevi o core usando o Vercel AI SDK em cerca de dois dias. Streaming funcionou. Mobile Safari funcionou. O cliente parou de ligar.
Isso não é um discurso de vendas. É só o que aconteceu. E é por isso que quero caminhar pelo que esse SDK realmente faz, onde economiza seu tempo de verdade, e onde você ainda vai bater na parede.
O Que o Vercel AI SDK Realmente É
As pessoas ouvem "Vercel AI SDK" e assumem que está preso à infraestrutura Vercel. Não está. Você pode rodar em qualquer servidor Node.js, incluindo seu próprio VPS, Railway, Render, onde quer que seja. O que ele realmente é: uma biblioteca TypeScript que abstrai as partes mais complicadas de construir recursos powered by LLM em uma aplicação web.
Há dois pacotes principais que você vai usar. ai é o runtime core. @ai-sdk/openai (ou @ai-sdk/anthropic, @ai-sdk/google, etc.) são os adaptadores de provedor. O SDK usa uma interface unificada, então mudar de GPT-4o para Claude 3.5 Sonnet é genuinamente uma mudança de uma linha em na maioria dos casos. Testei isso. Funciona.
Os Primitivos Core
Três coisas estão no coração do SDK:
streamText, faz streaming de uma resposta de texto token por token, ideal para interfaces de chatgenerateText, aguarda a resposta completa, bom para jobs em background ou quando você não precisa de UX com streaminggenerateObject, retorna JSON estruturado validado contra um schema Zod, que é onde as coisas ficam realmente interessantes
streamText é o que a maioria das pessoas quer primeiro. Ele cuida do encanamento do ReadableStream, da codificação e do chunking. Aquele pesadelo de seis semanas em fintech que mencionei? É exatamente o que streamText teria resolvido no primeiro dia.
Configurando Sem Perder a Sanidade
Assumindo que você está no Next.js 14 ou 15 com o App Router (que você provavelmente está se está lendo isso em 2025), a configuração é genuinamente rápida.
- Instale os pacotes:
npm install ai @ai-sdk/openai - Crie um manipulador de rota em
app/api/chat/route.ts - Importe
streamTexte seu provedor, passe seu modelo e mensagens, retorne o resultado como umaStreamingTextResponse - No cliente, use o hook
useChatdo pacoteai/react
É isso. Você terá um chat com streaming funcionando em menos de uma hora se conhecer Next.js razoavelmente bem. O hook useChat gerencia o array de mensagens, o estado de carregamento, a vinculação do campo de entrada e as atualizações de streaming. Você não escreve nada disso sozinho.
O que eu adicionaria imediatamente a qualquer configuração de produção: um prompt de sistema adequado, rate limiting (eu uso Upstash para isso, seu rate limiter respaldado por Redis funciona bem com Edge Functions), e algum tipo de logging de uso de tokens. O SDK expõe dados de uso no objeto de resposta, então você pode registrar prompt tokens e completion tokens no seu banco de dados sem nenhuma chamada de API extra.
generateObject É o Recurso em Que Você Está Dormindo
Opinião honesta: streamText recebe toda a atenção, mas generateObject é o que mudou como eu arquiteto features de IA.
A ideia é simples. Você define um schema Zod, passa para generateObject, e o SDK instrui o modelo a retornar JSON que esteja em conformidade com ele. Você recebe um objeto tipado, não uma string que você precisa fazer parsing e rezar.
Seahawk teve um projeto ano passado para uma empresa de gestão de propriedades. Eles queriam extrair dados estruturados de documentos de aluguel enviados, nomes de inquilinos, valores de aluguel, cláusulas de quebra, datas de renovação. A abordagem antiga teria sido: avisar o modelo, obter texto, escrever um parser regex, chorar. Com generateObject, definimos um LeaseSchema com Zod, e o modelo retornou dados tipados e limpos em cada execução. Estávamos enviando aluguéis extraídos para uma tabela Postgres dentro de uma semana.
O que confunde as pessoas: nem todos os modelos suportam saída estruturada igualmente bem. GPT-4o e Claude 3.5 Sonnet lidam com isso de forma confiável. Alguns modelos menores ou mais antigos vão alucinar campos ou ignorar o schema completamente. Fique com os modelos principais para este, pelo menos até validar seu caso de uso.
Tool Calling: Onde o Verdadeiro Poder Reside
Se generateObject é subutilizado, tool calling é ativamente mal compreendido. A maioria dos desenvolvedores pensa que "tool calling" significa que a IA pode navegar na internet ou executar código. Às vezes faz. Mas na prática, ferramentas são apenas funções que você define e que o modelo pode escolher invocar durante uma resposta.
Como Pensar Sobre Isso
Digamos que você está construindo um bot de suporte para um produto SaaS. O usuário pergunta "qual é meu plano de assinatura atual?" O modelo não pode saber disso. Mas você pode definir uma ferramenta getUserSubscription que recebe um ID de usuário e retorna os dados do plano do seu banco de dados. O modelo reconhece a intenção, chama a ferramenta, obtém os dados de volta e os incorpora na resposta. O usuário apenas vê uma resposta coerente.
O parâmetro tools do SDK em streamText e generateText recebe um objeto onde cada chave é um nome de ferramenta, e cada valor tem uma description (que o modelo usa para decidir quando chamá-la), um schema de parameters (Zod novamente) e uma função execute. A função execute é executada no servidor, com segurança, longe do cliente.
Construí agentes com múltiplas etapas dessa forma. O SDK suporta maxSteps para que o modelo possa encadear chamadas de ferramentas, chamar uma ferramenta, usar o resultado, chamar outra ferramenta, sintetizar tudo e responder. Não é magia. Você ainda precisa pensar cuidadosamente sobre suas descrições de ferramentas e seu system prompt. Mas toda a fiação é tratada para você.
Middleware, Wrapping e o Modelo de Pipeline
Uma coisa que não apreciei até ler mais fundo na documentação: o SDK tem um conceito de middleware que permite encapsular chamadas de modelo para adicionar logging, cache ou comportamento personalizado sem tocar no código da sua funcionalidade.
wrapLanguageModel recebe um modelo e um objeto middleware. Você pode interceptar requisições antes de elas chegarem à API, modificar parâmetros, fazer cache de respostas. Usei isso em uma ferramenta de geração de conteúdo que construímos para uma editora, o caso de uso deles tinha muitos prompts repetidos (o mesmo resumo de artigo sendo solicitado múltiplas vezes por dia), e fizemos cache de respostas em Redis usando a camada de middleware. O custo caiu cerca de 35% no primeiro mês.
Isso é o tipo de coisa que você normalmente teria que boltar desajeitadamente ao redor das suas chamadas de API. Ter isso como um conceito de primeira classe no SDK significa que é composto e testável.
O Que Não Faz (Seja Honesto Consigo Mesmo)
Certo. Deixa eu te poupar dessa dor.
O SDK não gerencia memória ou histórico de conversas de longo prazo para você. useChat mantém o array de mensagens no estado do cliente, mas no momento em que o usuário atualiza a página, desaparece. Se você precisa de conversas persistentes, você constrói isso sozinho. Postgres ou MongoDB para armazenamento de mensagens, buscar ao montar para reidratar o chat, nada disso é fornecido. Isso é comportamento correto, na verdade. O SDK não deveria ser dono da sua camada de dados. Mas iniciantes frequentemente esperam que seja.
Também não trata entradas multimodais nativamente de forma que abstraia toda a complexidade. Você pode passar URLs de imagem no array de mensagens e modelos como GPT-4o as processarão bem, mas construir um fluxo adequado de upload de imagem com preview, compressão e armazenamento ainda é seu trabalho. Uso Uploadthing quando estou no Next.js, leva uns 30 minutos para conectar.
RAG (geração aumentada por recuperação) também não está incluído. Não há busca vetorial integrada, nenhum pipeline de embedding, nenhuma lógica de chunking. Para isso você recorre a algo como pgvector no Postgres ou um serviço dedicado como Pinecone. O SDK cuida da chamada LLM. O resto da arquitetura de recuperação é seu para construir.
Implantando: Vercel vs Qualquer Outro Lugar
Sim, o SDK funciona melhor no Vercel. StreamingTextResponse funciona com o Edge Runtime do Vercel pronto para uso, e cold starts em Edge Functions são muito menores do que em funções serverless Node.js. Se suas respostas de chat parecem lentas, a latência até o primeiro token importa muito, e Edge reduz isso.
Mas já rodei em Railway (Node.js, não Edge) e funciona bem. Você só usa Response com headers de streaming apropriados em vez dos helpers específicos do Vercel, e os docs do SDK cobrem isso. Não deixe "Vercel AI SDK" fazer você achar que está preso.
Uma coisa que eu recomendaria genuinamente: mantenha seus route handlers de IA enxutos. Não faça queries de banco de dados, verificações de autenticação e chamadas LLM tudo em uma função. Middleware (middleware do Next.js, não o middleware do SDK) deveria lidar com autenticação antes mesmo da requisição chegar ao seu route de IA. Mantém rápido, mantém debugável.
FAQ
O Vercel AI SDK é gratuito para usar?
O SDK em si é open source e gratuito. Você paga pelas APIs dos modelos subjacentes, OpenAI, Anthropic, Google, whoever você está chamando. Esses custos são seus para gerenciar. O SDK não marca nada.
Posso usá-lo com modelos além do OpenAI?
Sim, e essa é uma de suas forças genuínas. Há adaptadores oficiais para Anthropic, Google (Gemini), Mistral, Groq, Cohere e mais. A comunidade também construiu adaptadores para Ollama se você quiser executar modelos locais. A interface unificada significa que seu código de feature não muda quando você troca de provider.
Funciona com React Server Components?
Parcialmente. generateText e generateObject podem rodar em Server Components sem problemas, são apenas funções async. streamText com o hook useChat requer estado do lado do cliente, então essa parte fica em um Client Component. Essa é a arquitetura padrão do Next.js e não deve causar problemas se você entender o limite.
Como eu lido com erros quando a API cai?
O SDK lança erros tipados que você pode capturar e tratar. Na prática eu envolverei minhas chamadas de LLM em um try/catch e retorno uma mensagem de fallback elegante em vez de deixar o erro do stream se propagar para a UI como uma resposta parcial quebrada. Os docs do SDK sobre tratamento de erros cobrem os tipos de erro em detalhes e valem a pena ler antes de você ir para produção.
Qual é a situação do limite de tokens?
O SDK não gerencia limites de context window para você. Se você está construindo uma conversa de longa duração e não aparar o histórico de mensagens, você vai atingir a context window do modelo e obter um erro. Um conserto simples: manter as últimas N mensagens (eu geralmente faço 20) mais um system prompt fixo. Bom o suficiente para a maioria das aplicações de chat.
---
Olha, o Vercel AI SDK não é uma mágica. É uma abstração bem-desenhada sobre uma plumbing genuinamente tediosa. Ele lida com streaming corretamente, oferece outputs estruturados tipados, torna tool calling acessível e funciona entre providers. Para 80% do trabalho de features de IA que assumo, é o ponto de partida certo.
O cliente fintech, aliás, foi ao ar com o chat reconstruído duas semanas depois que reescrevi. Sem problemas no mobile Safari. Sem race conditions. Seis semanas viraram dois dias. Às vezes a abstração certa vale muito.
Leitura relacionada: Segurança Headless vs WordPress em 2026: por que Next.js e Astro, headless, e Astro.