Vercel AI SDK: Guia Completo para Desenvolvedores Criarem Aplicações de IA

O Vercel AI SDK é um kit de ferramentas TypeScript para construir aplicações de Inteligência Artificial. Ele lida com geração de texto, streaming, saídas estruturadas, chamadas de ferramentas e loops de agente de múltiplas etapas por meio de uma única API unificada — e funciona com qualquer grande provedor de LLM. Se você já tentou conectar OpenAI ou Anthropic diretamente a um aplicativo Next.js e acabou mantendo três implementações diferentes de streaming, este SDK resolve esse problema.

Este guia aborda as capacidades principais do SDK, como conectá-lo à API compatível com OpenAI da Novita AI e onde fluxos de trabalho de agente se encaixam para desenvolvedores construindo algo além de um simples chatbot.

O que é o Vercel AI SDK?

O Vercel AI SDK (pacote: ai no npm) é uma biblioteca de código aberto que abstrai as diferenças entre provedores de LLM. Em vez de aprender protocolos de streaming separados para OpenAI, Anthropic e Google, você usa as mesmas funções generateText, streamText ou generateObject e troca de provedor alterando uma única importação.

O SDK é dividido em duas camadas:

• AI SDK Core lida com interações com o modelo: geração de texto, streaming, objetos estruturados, chamadas de ferramentas, embeddings e loops de agente.
• AI SDK UI fornece hooks React (useChat, useCompletion, useObject, useAssistant) além de adaptadores para Next.js, SvelteKit e Nuxt que gerenciam o estado de streaming no navegador.

Também existe o pacote @ai-sdk/openai-compatible para conectar-se a qualquer provedor que implemente o formato Chat Completions da OpenAI — é assim que a Novita AI se integra.

O SDK funciona em Node.js, Deno, runtimes de borda (Cloudflare Workers, Vercel Edge) e ambientes de navegador.

AI SDK Core: generateText, streamText e generateObject

Instale o SDK e um pacote de provedor:

npm install ai @ai-sdk/openai

generateText

Para conclusões sem streaming — processamento em lote, classificação, geração única:

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

const { text } = await generateText({
  model: openai('gpt-4o-mini'),
  prompt: 'Explique como funcionam os embeddings de LLM em duas frases.',
});

console.log(text);

streamText

Para interfaces de chat onde a latência importa:

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

const result = streamText({
  model: openai('gpt-4o-mini'),
  messages: [
    { role: 'user', content: 'Me guie na configuração de um aplicativo Next.js.' },
  ],
});

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

generateObject

Quando você precisa de saída JSON estruturada em vez de texto bruto — a validação de esquema é tratada automaticamente usando Zod:

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

const { object } = await generateObject({
  model: openai('gpt-4o-mini'),
  schema: z.object({
    name: z.string(),
    skills: z.array(z.string()),
    experienceLevel: z.enum(['junior', 'mid', 'senior']),
  }),
  prompt: 'Gere um perfil fictício de engenheiro de software.',
});

console.log(object.name, object.skills);

O SDK cuida da injeção de prompt de sistema necessária para forçar o modelo a produzir JSON válido e tenta novamente em caso de saída malformada.

AI SDK Tools: Chamada de Funções e Uso de Ferramentas

Ferramentas permitem que os modelos chamem funções externas — APIs de busca, consultas a bancos de dados, calculadoras — durante uma geração. O parâmetro tools do SDK recebe um objeto onde cada chave se torna uma função chamável:

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

const { text, toolCalls } = await generateText({
  model: openai('gpt-4o-mini'),
  tools: {
    getWeather: tool({
      description: 'Obter clima atual para uma localização',
      parameters: z.object({
        city: z.string().describe('Nome da cidade'),
        unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
      }),
      execute: async ({ city, unit }) => {
        // Substitua por uma chamada real de API climática
        return { city, temperature: 22, unit, condition: 'ensolarado' };
      },
    }),
  },
  prompt: 'Como está o clima em Tóquio agora?',
});

console.log(text);

O helper tool() fornece inferência de tipo do esquema Zod para os parâmetros da função execute. Sem necessidade de parsing manual de JSON.

Chamadas de Ferramentas em Múltiplas Etapas

Por padrão, generateText para após uma rodada de chamadas de ferramentas. Defina maxSteps para permitir que o modelo use resultados de ferramentas em raciocínios subsequentes:

const { text } = await generateText({
  model: openai('gpt-4o'),
  maxSteps: 5,
  tools: { getWeather, searchWeb, lookupCalendar },
  prompt: 'Planeje minhas atividades ao ar livre para este fim de semana em Berlim.',
});

O SDK lida automaticamente com o loop chamada de ferramenta → resultado → continuação. Cada etapa é exposta via onStepFinish se você precisar de visibilidade no raciocínio intermediário.

Construindo Loops de Agente com o Vercel AI SDK

Um agente no AI SDK é um modelo executando em loop com ferramentas até que decida ter informações suficientes para responder. O padrão é o mesmo da chamada de ferramentas em múltiplas etapas, mas com mais ferramentas e um maxSteps maior:

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

const result = await generateText({
  model: openai('gpt-4o'),
  maxSteps: 10,
  system: 'Você é um assistente de pesquisa. Use as ferramentas disponíveis para responder de forma completa.',
  prompt: 'Quais são as principais diferenças entre Llama 3.1 e Qwen3?',
  tools: {
    search: tool({
      description: 'Pesquise na web por informações atualizadas',
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }) => searchWeb(query),
    }),
    summarize: tool({
      description: 'Resuma uma URL',
      parameters: z.object({ url: z.string() }),
      execute: async ({ url }) => fetchAndSummarize(url),
    }),
  },
  onStepFinish({ stepType, toolCalls, toolResults }) {
    console.log('Etapa:', stepType, toolCalls?.map(t => t.toolName));
  },
});

Para pipelines de agente em produção, conecte Novita AI como backend de modelo para controlar custo e throughput em escala — abordado na próxima seção.

AI SDK React: Hook useChat e Integração com Next.js

O hook useChat gerencia o estado de streaming do chat sem código repetitivo:

// app/chat/page.tsx
'use client';
import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id} className={m.role === 'user' ? 'user' : 'assistant'}>
          {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Pergunte algo..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading}>Enviar</button>
      </form>
    </div>
  );
}

O manipulador de rota correspondente:

// app/api/chat/route.ts
import { streamText } 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-4o-mini'),
    messages,
  });

  return result.toDataStreamResponse();
}

toDataStreamResponse() lida com o protocolo de stream do Vercel AI, que o useChat no cliente entende nativamente. Para streaming de objetos estruturados a partir de uma API, troque useChat por useObject e streamText por streamObject.

Como Usar Novita AI com o Vercel AI SDK

A Novita AI fornece uma API compatível com OpenAI em https://api.novita.ai/v3/openai, o que a torna uma substituição direta para qualquer SDK que utilize o formato Chat Completions da OpenAI — incluindo o Vercel AI SDK.

Por que Usar Novita AI com o AI SDK

A Novita AI hospeda mais de 70 modelos de código aberto — Llama 3.3 70B, Qwen3, DeepSeek V3, Mistral e Gemma 3 — através de um único endpoint de API. Sem necessidade de gerenciar infraestrutura de GPU. Para fluxos de trabalho de agente, a API serverless escala de pequenos modelos de instrução de 7B até grandes modelos de raciocínio sem alterações de configuração.

Configuração

Instale o pacote de provedor compatível com OpenAI:

npm install ai @ai-sdk/openai-compatible

Configure o provedor:

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

const novita = createOpenAICompatible({
  name: 'novita',
  baseURL: 'https://api.novita.ai/v3/openai',
  apiKey: process.env.NOVITA_API_KEY,
});

Essa é a configuração completa. Agora use exatamente como qualquer outro provedor do AI SDK:

import { generateText } from 'ai';

const { text } = await generateText({
  model: novita('meta-llama/llama-3.3-70b-instruct'),
  prompt: 'Quais são os tradeoffs entre RAG e fine-tuning para um bot de suporte ao cliente?',
});

Streaming funciona da mesma forma:

import { streamText } from 'ai';

const result = streamText({
  model: novita('qwen/qwen3-235b-a22b-instruct-2507'),
  messages: [
    { role: 'system', content: 'Você é um assistente de codificação útil.' },
    { role: 'user', content: 'Mostre-me como construir uma API REST com FastAPI.' },
  ],
});

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

Chamadas de Ferramentas com Novita AI

Modelos que suportam chamada de funções funcionam com a interface de ferramentas do AI SDK sem configuração extra. Llama 3.3 70B Instruct e Qwen3 suportam chamadas de ferramentas através da API da Novita:

import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text } = await generateText({
  model: novita('meta-llama/llama-3.3-70b-instruct'),
  maxSteps: 5,
  tools: {
    calculator: tool({
      description: 'Avaliar uma expressão matemática',
      parameters: z.object({ expression: z.string() }),
      execute: async ({ expression }) => {
        return { result: eval(expression) }; // use um parser matemático seguro em produção
      },
    }),
  },
  prompt: 'Quanto é 12% de 847, depois dividido por 3.14?',
});

Configuração de Ambiente

Adicione sua chave de API da Novita ao .env.local:

NOVITA_API_KEY=sua_chave_novita_api_aqui

Obtenha uma chave em novita.ai — novas contas incluem créditos gratuitos para testar a API.

Agent Sandbox para Cargas de Trabalho de Longa Duração

Para tarefas de agente que executam código, acessam sistemas de arquivos ou executam fluxos de trabalho de vários minutos, o Agent Sandbox da Novita AI fornece ambientes de execução isolados sobre a API LLM. O AI SDK lida com a camada de raciocínio do modelo. O sandbox lida com a execução com estado que não pode ser executada dentro de um timeout de função de borda.

Escolhendo um Provedor de LLM para o Vercel AI SDK

O AI SDK facilita a troca de provedores, o que é útil — mas vale a pena entender os tradeoffs antes de escolher um para produção.

Latência: O tempo até o primeiro token importa mais do que a velocidade total de geração para streaming de chat. Modelos menores (8B–14B) produzem primeiros tokens mais rapidamente. Os endpoints serverless da Novita AI são otimizados para baixa latência de cold start em modelos abertos.

Custo em escala: GPT-4o é excelente, mas em grandes volumes de consulta a diferença de preço entre um modelo de fronteira e um modelo aberto bem ajustado (ex.: Llama 3.3 70B) torna-se significativa. O AI SDK permite experimentar ambos sem reescrever a lógica da aplicação.

Suporte a chamadas de ferramentas: Nem todos os modelos suportam chamada de funções de forma confiável. Teste seu modelo específico com seus esquemas de ferramentas — o comportamento varia entre provedores mesmo para a mesma família de modelos.

Janela de contexto: Para RAG com muitos documentos ou longos históricos de conversa, verifique os limites de contexto. Muitos modelos abertos suportam 128K tokens, o que cobre a maioria dos casos de uso práticos.

Vendor lock-in: A abstração de provedor do AI SDK com o endpoint compatível com OpenAI da Novita AI significa que você pode trocar de modelos ou adicionar um provedor de fallback sem tocar no código da aplicação.

Conclusão

O Vercel AI SDK remove o código repetitivo da construção de aplicações de IA — uma API para geração de texto, streaming, chamadas de ferramentas e loops de agente em qualquer provedor de LLM. Seja construindo uma interface de chat em streaming com useChat, extraindo dados estruturados com generateObject ou executando um agente de múltiplas etapas que chama ferramentas externas, o SDK lida com a infraestrutura para que você possa focar na lógica da aplicação.

Para inferência com modelos abertos, a API compatível com OpenAI da Novita AI se encaixa diretamente no SDK via @ai-sdk/openai-compatible. Você obtém acesso a mais de 70 modelos — Llama, Qwen3, DeepSeek, Mistral — sem gerenciar infraestrutura de GPU, e pode trocar de modelos ou adicionar fallbacks de provedor sem tocar no código da aplicação.

Comece em novita.ai — novas contas incluem créditos gratuitos.

FAQ

O que é ai sdk react?

A integração React do AI SDK está no pacote ai/react. Ela fornece hooks — useChat, useCompletion, useObject, useAssistant — que conectam um frontend React a uma rota de streaming no servidor. Os hooks gerenciam estado de streaming, histórico de mensagens, indicadores de carregamento e tratamento de erros, para que você não precise gerenciar ReadableStream no estado do componente.

O que o ai sdk 5 adiciona?

O AI SDK 5 (lançado como beta em meados de 2025) redesenhou a especificação do provedor para melhor segurança de tipos, separou o gerenciamento de estado da UI da lógica de interação com o modelo e introduziu um formato de mensagem revisado que facilita a serialização do estado de UI agentiva. Se você está iniciando um novo projeto em 2026, verifique ai-sdk.dev para a versão estável mais recente — o SDK continuou evoluindo através das versões 6 e 7.

Existe documentação do ai sdk que eu possa consultar?

A documentação canônica está em ai-sdk.dev. Inclui guias de configuração de provedores, referências de API para todas as funções principais, tutoriais de integração com frameworks (Next.js, Nuxt, SvelteKit) e exemplos de receitas para padrões comuns como RAG, loops de agente e extração estruturada.

Posso usar as ferramentas do ai sdk com modelos que não são da OpenAI?

Sim. Qualquer provedor que suporte chamada de funções funciona com a interface tool() do AI SDK. A Novita AI hospeda vários modelos abertos com suporte a chamada de funções. A qualidade do comportamento varia — Llama 3.3 70B e Qwen3 são os mais confiáveis para uso de ferramentas em múltiplas etapas entre os modelos abertos disponíveis através da API da Novita.

Qual é a diferença entre a documentação do vercel ai sdk e a documentação do ai-sdk.dev?

É o mesmo produto. A documentação anteriormente estava em sdk.vercel.ai e redireciona para ai-sdk.dev. O SDK é mantido pela equipe Vercel, mas é de código aberto e não está vinculado à implantação na infraestrutura da Vercel.

Como os SDKs de inteligência artificial se comparam a chamar a API LLM diretamente?

Chamadas diretas à API são adequadas para requisições únicas simples. Um SDK se torna útil quando você precisa de várias coisas ao mesmo tempo: streaming integrado a um framework de UI, loops de chamadas de ferramentas em múltiplas etapas, validação de saída estruturada, troca unificada de provedores e tratamento consistente de repetições/erros entre provedores. O AI SDK lida com tudo isso no nível da biblioteca, para que você não precise reconstruí-lo a cada projeto.

Artigos Recomendados

• OpenAI Python SDK: Instalação, Configuração e Integração Prática
• Qual Provedor de Inferência é Ideal para Agentes de IA
• Construa um Sistema Multiagente com Novita e CrewAI
• Melhores Provedores de API LLM em 2026