Vercel AI SDK: Guia Completo para Desenvolvedores na Criação de Aplicações com IA

O Vercel AI SDK é um kit de ferramentas TypeScript para criar aplicações de IA. Ele lida com geração de texto, streaming, saídas estruturadas, chamadas de ferramentas e loops de agentes em várias etapas através de uma única API unificada — e funciona com qualquer grande provedor de LLM. Se você já tentou conectar OpenAI ou Anthropic diretamente em um app Next.js e acabou mantendo três implementações de streaming diferentes, este SDK resolve esse problema.

Este guia aborda as capacidades principais do SDK, como conectá-lo à API LLM compatível com OpenAI da Novita AI e onde os fluxos de trabalho de agente se encaixam para desenvolvedores que estão construindo mais do que 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ê chama as mesmas funções generateText, streamText ou generateObject e troca de provedor alterando uma única importação.

O SDK é distribuído 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 agentes.
• 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.

Existe também o pacote @ai-sdk/openai-compatible para conectar-se a qualquer provedor que implemente o formato OpenAI Chat Completions — que é como 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 os embeddings de LLM funcionam 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: 'Explique como configurar um app 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 lida com a injeção de prompt de sistema necessária para forçar o modelo a gerar JSON válido e faz novas tentativas em caso de saída malformada.

Ferramentas do AI SDK: Chamada de Função 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 à API de clima
        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 análise JSON manual.

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 os resultados das 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 de chamada de ferramenta → resultado → continuação. Cada etapa é exposta via onStepFinish se você precisar de visibilidade sobre o raciocínio intermediário.

Construindo Loops de Agentes de IA com o Vercel AI SDK

Um agente no AI SDK é um modelo executando em loop com ferramentas até que ele decida que tem informações suficientes para responder. O padrão é o mesmo da chamada de ferramentas em várias 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: 'Pesquisar na web por informações atuais',
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }) => searchWeb(query),
    }),
    summarize: tool({
      description: 'Resumir 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 a Novita AI como backend do 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 chat em streaming sem código boilerplate:

// 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 da Vercel AI, que o useChat no cliente entende nativamente. Para fazer streaming de objetos estruturados a partir de uma API, substitua useChat por useObject e streamText por streamObject.

Como Usar a 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 um substituto imediato para qualquer SDK que use o formato OpenAI Chat Completions — incluindo o Vercel AI SDK.

Por que Usar a 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 modelos pequenos de 7B de instrução 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 a Novita AI

Modelos que suportam chamada de funções funcionam com a interface de ferramentas do AI SDK sem nenhuma 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 divida por 3.14?',
});

Configuração de Ambiente

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

NOVITA_API_KEY=sua_chave_api_novita_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 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 chat em streaming. Modelos menores (8B–14B) produzem primeiros tokens mais rápido. Os endpoints serverless da Novita AI são otimizados para baixa latência de inicialização a frio em modelos abertos.

Custo em escala: GPT-4o é excelente, mas em altos volumes de consulta, a diferença de preço entre um modelo de fronteira e um modelo aberto bem ajustado (por exemplo, Llama 3.3 70B) torna-se significativa. O AI SDK permite que você experimente 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 contra 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.

Aprisionamento ao fornecedor: 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 elimina o trabalho repetitivo da criação de aplicações de IA — uma API para geração de texto, streaming, chamadas de ferramentas e loops de agentes em qualquer provedor de LLM. Seja construindo uma interface de chat em streaming com useChat, extraindo dados estruturados com generateObject ou executando um agente em várias etapas que chama ferramentas externas, o SDK cuida da 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 é o 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 o 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á começando 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. Ela 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 agentes 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 várias 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?

São o mesmo produto. A documentação anteriormente estava em sdk.vercel.ai e redireciona para ai-sdk.dev. O SDK é mantido pela equipe da 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 suficientes para solicitações simples e únicas. 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 várias etapas, validação de saída estruturada, troca unificada de provedores e tratamento consistente de novas tentativas e erros entre provedores. O AI SDK lida com tudo isso no nível da biblioteca, para que você não precise reconstruí-lo por projeto.

Artigos Recomendados

• Which Inference Provider Is Right for AI Agents
• Build a Multi-Agent System with Novita and CrewAI
• Best LLM API Providers in 2026