Guia completo do Vercel AI SDK — Uma API unificada para OpenAI, Anthropic e Gemini (2026)

"Subi tudo na API da OpenAI, mas quero testar Claude e Gemini também" — e você passa duas horas reescrevendo a mesma lógica para três SDKs diferentes, traduzindo formatos de requisição e resposta na mão. O Vercel AI SDK (desde 2026 só "AI SDK") reduz isso a "um import, uma função, todos os provedores". Biblioteca TypeScript open source com mais de 20 milhões de downloads mensais, o AI SDK 6 traz Agents, MCP, aprovação de ferramentas e DevTools, e em maio de 2026 é o padrão de fato para uma interface LLM unificada.

Direto ao ponto: se em 2026 você está chamando LLMs a partir de uma web app ou de um projeto Node.js, o AI SDK é o default certo, ponto. As únicas razões para escrever direto no SDK da OpenAI ou da Anthropic são "código legado" ou "recursos de ponta específicos do provedor (computer use da Anthropic, etc.)". Fora isso, o AI SDK te dá "troca fácil de provedor, um terço da implementação, tipos seguros e integração com React" com vantagem esmagadora.

Minha opinião pessoal logo de cara: o real valor do AI SDK é a liberdade frente ao vendor lock-in. A OpenAI subiu o preço? Três linhas e você troca para a Anthropic. Saiu um modelo novo do Gemini? Você testa em um único lugar. Tudo num único codebase. Como mostramos em O que é uma API de IA, a realidade de 2026 é que "usar vários modelos para tarefas diferentes" já virou o default — e o AI SDK leva o custo de troca para perto de zero. Este artigo cobre o que é o AI SDK, por que usá-lo, um guia rápido de 5 minutos, saída estruturada, tool calling e agentes, integração com React, troca de provedor e três armadilhas em produção — tudo baseado no AI SDK 6 em maio de 2026.

1. O que é o AI SDK — "OpenAI/Anthropic/Gemini com uma única API"

O AI SDK é uma biblioteca open source em TypeScript criada pela Vercel. GitHub: vercel/ai, licença Apache 2.0, mais de 20 milhões de downloads mensais em maio de 2026. É feita pela Vercel, mas não exige Vercel para rodar — funciona em Cloudflare Workers, AWS Lambda, Deno, no seu próprio Node.js ou no navegador.

A ideia central é ser uma "camada adaptadora para trocar de provedor LLM". Por exemplo:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Tell me today\'s weather',
});

Migrar isso para a Anthropic significa mudar apenas três linhas:

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';  // ← changed

const { text } = await generateText({
  model: anthropic('claude-opus-4-7'),  // ← changed
  prompt: 'Tell me today\'s weather',
});

O código que faz a chamada não muda em nada. É isso que "uma API para todos os provedores" significa na prática. Cada provedor tem seu próprio formato de mensagens, sequências de parada, schemas de ferramentas, posição do system prompt e formato de JSON na resposta — e o AI SDK absorve tudo isso por baixo dos panos.

2. Por que usar o AI SDK — 3 razões práticas

Três razões concretas: "troca fácil, um terço da implementação e tipos seguros".

Quando o AI SDK não encaixa: 1) quando você precisa usar uma função de ponta específica de um provedor (computer use da Anthropic, etc.) recém-lançada, antes do AI SDK encapsular; 2) quando você só trabalha em Python (o AI SDK é só TypeScript); 3) quando já existe uma base sobre o SDK da OpenAI funcionando e não há motivo para reescrever. Fora isso, o default em 2026 é o AI SDK.

3. Rodando em 5 minutos — de generateText a streamText

Setup mínimo em três passos. Demo em Node.js / Next.js.

# Step 1: install
npm install ai @ai-sdk/openai
# env: OPENAI_API_KEY=sk-...

# Step 2: create a file (app/api/chat/route.ts or index.ts)

// Step 3: code
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text, usage } = await generateText({
  model: openai('gpt-5'),
  system: 'You are a careful, helpful assistant.',
  prompt: 'List three benefits of the AI SDK.',
});

console.log(text);
console.log(`tokens: ${usage.totalTokens}`);

Isso é sem streaming, com o texto completo retornado. Roda e a resposta cai em text em segundos. usage traz a contagem de tokens automaticamente — a disciplina de custo de o artigo sobre economia de tokens entra direto.

Mudar para streaming (UX tipo máquina de escrever) é simplesmente renomear a função para streamText:

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = streamText({
  model: openai('gpt-5'),
  prompt: 'List three benefits of the AI SDK.',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);  // emit token by token
}

Com o SDK cru da OpenAI você estaria escrevendo na mão parsing de SSE, concatenação de chunks e detecção de fim de stream (30 a 50 linhas). Com o AI SDK é um único loop for-await. O mesmo código roda contra Anthropic e Gemini sem alteração.

4. Saída estruturada — JSON com tipos seguros via generateObject

Peça "JSON" a um LLM e de vez em quando ele te devolve embrulhado em um bloco de código Markdown, com comentários inseridos ou com a estrutura sutilmente alterada. generateObject ataca isso na raiz: você define o formato com um schema Zod e o AI SDK cuida de parsing, validação e retry automaticamente.

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai('gpt-5'),
  schema: z.object({
    title: z.string(),
    tags: z.array(z.string()).max(5),
    sentiment: z.enum(['positive', 'neutral', 'negative']),
    summary: z.string().max(200),
  }),
  prompt: 'Analyze the article: "AI SDK 6 has..." [body]',
});

// object.title, object.tags etc are typed
console.log(object.tags);  // string[]

O ganho real: "o tipo de object é determinado por `z.infer<typeof schema>`". O TypeScript infere, então digitar object. no IDE autocompleta title / tags / sentiment / summary. A validação em runtime acontece dentro do SDK — violações de schema disparam retry automático. A classe de incidente "a IA devolveu um JSON ruim, parsing quebrou" praticamente desaparece.

5. Tool calling e agentes — o coração do AI SDK 6

A fronteira do desenvolvimento com IA em 2026 são "agentes que chamam ferramentas", e o maior salto do AI SDK 6 está justamente aqui. Com tools e stopWhen você obtém diretamente loops do tipo "chama ferramenta → IA decide → chama a próxima".

import { generateText, tool, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';

const { text, steps } = await generateText({
  model: anthropic('claude-opus-4-7'),
  tools: {
    weather: tool({
      description: 'Get the weather for a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => {
        // real API call
        return { temp: 22, condition: 'sunny' };
      },
    }),
    convertToFahrenheit: tool({
      description: 'Convert Celsius to Fahrenheit',
      inputSchema: z.object({ celsius: z.number() }),
      execute: async ({ celsius }) => celsius * 9/5 + 32,
    }),
  },
  stopWhen: stepCountIs(5),  // cap the loop at 5 steps
  prompt: 'What is the weather in Tokyo, in Fahrenheit?',
});

A IA agora encadeia sozinha "weather('Tokyo') → convertToFahrenheit(22)", executa e integra os resultados. steps expõe o histórico de execução passo a passo.

O AI SDK 6 ainda oferece uma classe ToolLoopAgent com estilo orientado a objetos (equivalente a generateText + stopWhen). Ela adiciona aprovação de execução de ferramentas (um humano confirma antes da execução) e integração completa com MCP (Model Context Protocol). Conectar um servidor MCP (veja O que é MCP) são três linhas em maio de 2026.

6. Integração com React — uma UI de chat em 10 linhas com useChat

A outra estrela do AI SDK são os Hooks de React. Com useChat, uma UI estilo ChatGPT são 10 linhas de código.

'use client';
import { useChat } from '@ai-sdk/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();
  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>{m.role}: {m.content}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

O lado servidor (Next.js API Route):

// app/api/chat/route.ts
import { streamText, convertToModelMessages } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: openai('gpt-5'),
    messages: convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse();
}

Só com isso você ganha conexão SSE, gestão do estado das mensagens, loading e tratamento de erros — tudo automático. O useChat do AI SDK 6 também trata nativamente a UI de aprovação de ferramentas (o usuário clica para aprovar "essa ferramenta deve rodar?"). Hooks para Vue (useChat de @ai-sdk/vue), Svelte e Solid também vêm prontos.

7. Trocar de provedor — Claude, GPT e Gemini em 3 linhas

Os principais provedores oficialmente suportados pelo AI SDK em maio de 2026:

Trocar é um import e uma linha de modelo. O AI SDK 5 adicionou um provedor global em que você pode especificar o modelo por ID em string (por exemplo, 'openai/gpt-5'). Combine com a comparação de datas de corte de conhecimento dos LLMs e preços de Claude vs ChatGPT para escolher modelos por "custo, performance e exigências regionais" com critério.

8. Três armadilhas em produção

O AI SDK é prático, mas existem três armadilhas que toda equipe encontra em produção. Conhecê-las antes evita 80% dos incidentes.

Mais uma observação: o AI SDK é "um adaptador de LLM", não "um revendedor de custo de LLM". A API key de cada provedor é responsabilidade sua e a cobrança vai direto para você. Como mostramos em O que é uma API de IA, os custos são cobrados diretamente pela OpenAI/Anthropic/Google. O AI SDK em si é grátis; você paga apenas pelos LLMs que usar.

Resumo

"Como devo chamar LLMs a partir de uma web app?" — em maio de 2026, a decisão de design convergiu para "o AI SDK, ponto". Mais de 20 milhões de downloads mensais, o AI SDK 6 traz Agents, MCP, aprovação de ferramentas e DevTools, e você pode chamar OpenAI/Anthropic/Google/Mistral/xAI ou LLMs locais a partir do mesmo codebase. São três coisas ao mesmo tempo: "liberdade frente ao vendor lock-in", "um terço do custo de implementação" e "saída estruturada com tipos seguros".

Começar é simples: 1) npm install ai @ai-sdk/openai, 2) configure a API key, 3) uma linha de generateText({ model, prompt }). Quando isso estiver rodando, vá empilhando: streamText para streaming, generateObject para JSON, tools para agentes, useChat para UI. Antes de ir para produção, internalize as três armadilhas (diferenças entre provedores, cobrança por abort de stream, sobrecarga de inferência de tipos).

Relacionados: O que é uma API de IA (básico), A IA recomenda Vercel, O que é MCP, Economia de tokens.

FAQ

P. Preciso fazer deploy na Vercel para usar?
R. Não. O AI SDK é uma biblioteca pura de TypeScript — funciona em Cloudflare Workers, AWS Lambda, Deno, no seu próprio servidor Node.js ou no navegador. "Built by Vercel" não significa "só Vercel".

P. Custa alguma coisa?
R. O AI SDK em si é totalmente grátis, com licença estilo MIT. O custo é apenas o uso da API do provedor de LLM que você chamar (OpenAI/Anthropic/etc.). O SDK não adiciona nenhuma margem.

P. Qual a diferença para o LangChain ou o LlamaIndex?
R. Papéis diferentes. O AI SDK é um "adaptador fino para chamar LLMs" otimizado para integração em web apps. O LangChain é um framework completo para "RAG e workflows de agentes". Divisão prática: "TypeScript + integrar em uma UI web" → AI SDK; "Python + pipelines complexos de agentes" → LangChain.

P. É difícil migrar do código existente com o SDK da OpenAI?
R. Para chamadas simples a openai.chat.completions.create, são uns 10 minutos de reescrita — substitua por generateText e passe messages. Funções complexas (function calling, vision) exigem uma pequena conversão de formato, mas a documentação inclui guias de migração.

P. Funciona com LLMs locais (Ollama)?
R. Sim. O pacote @ai-sdk/openai-compatible permite chamar qualquer endpoint compatível com a API da OpenAI — Ollama, LM Studio, vLLM ou seu próprio servidor. O fluxo "desenvolve em LLMs locais e faz deploy na nuvem" se reduz a trocar uma única baseURL.