Blog

Como Usar Vercel AI SDK: Guia para Iniciantes

Rebecca Kovács

Rebecca Kovács

10 junho 2025

Como Usar Vercel AI SDK: Guia para Iniciantes

Bem-vindo ao guia definitivo para iniciantes do Vercel AI SDK. Em um mundo onde a inteligência artificial está transformando rapidamente o cenário digital, a capacidade de integrar IA em aplicações web deixou de ser uma especialização de nicho para se tornar uma competência essencial para desenvolvedores modernos. Este guia foi elaborado para levá-lo de um iniciante curioso a um desenvolvedor capaz de aplicações com IA.

Por muito tempo, preencher a lacuna entre um poderoso Large Language Model (LLM) e uma interface web amigável era um empreendimento complexo. Desenvolvedores precisavam lidar com APIs de provedores díspares, gerenciar estados intrincados e implementar manualmente recursos como streaming de resposta. O Vercel AI SDK foi criado para resolver exatamente esses problemas. É um toolkit TypeScript-first que oferece uma camada de abstração unificada e elegante sobre as complexidades da construção de experiências alimentadas por IA.

Este não é apenas um guia rápido. Ao longo deste tutorial, construiremos um chatbot de IA completo e rico em recursos do zero usando Next.js e o modelo Gemini do Google. Iremos muito além de um simples exemplo "hello world". Você aprenderá:

Ao final deste guia abrangente, você terá não apenas um chatbot avançado e funcional, mas também o profundo conhecimento conceitual necessário para construir com confiança suas próprias aplicações únicas e poderosas com IA usando o Vercel AI SDK.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API linda?

Quer uma plataforma integrada e All-in-One para sua Equipe de Desenvolvimento trabalhar junta com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman por um preço muito mais acessível!
button

Capítulo 1: Fundamentos e Configuração

Toda grande estrutura precisa de uma base sólida. Neste capítulo, configuraremos nosso ambiente de desenvolvimento, instalaremos as ferramentas necessárias e organizaremos nossas chaves de API. Também dedicaremos um momento para entender o "porquê" por trás de cada escolha que fizermos.

Pré-requisitos

Antes de escrevermos uma única linha de código, vamos garantir que sua caixa de ferramentas esteja pronta.

  1. Navegue até Google AI Studio.
  2. Faça login com sua conta Google.
  3. Clique em "Get API key" (Obter chave de API) e depois em "Create API key in new project" (Criar chave de API em novo projeto).
  4. Copie a chave gerada e armazene-a em algum lugar seguro por enquanto. Trate esta chave como uma senha; nunca a exponha publicamente.

Passo 1: Inicializando o Projeto Next.js

Usaremos o Next.js, o principal framework React para construir aplicações prontas para produção. Seu paradigma App Router se integra perfeitamente com a natureza centrada no servidor de aplicações de IA.

Abra seu terminal e execute este comando para criar um novo projeto:

npx create-next-app@latest vercel-ai-tutorial

O instalador solicitará várias perguntas. Use estas configurações para seguir sem problemas:

Assim que a instalação for concluída, navegue para o diretório do projeto recém-criado:

cd vercel-ai-tutorial

Passo 2: Instalando o Vercel AI SDK

Agora, vamos adicionar os pacotes do AI SDK ao nosso projeto.

npm install ai @ai-sdk/react @ai-sdk/google zod

Vamos detalhar o que cada um desses pacotes faz:

Passo 3: Protegendo Sua Chave de API

Nunca coloque uma chave de API diretamente no código da sua aplicação. É um grande risco de segurança. O padrão profissional é usar variáveis de ambiente. O Next.js tem suporte integrado para isso com arquivos .env.local.

Crie o arquivo na raiz do seu projeto:

touch .env.local

Agora, abra este novo arquivo e adicione sua chave do Google AI:

# .env.local
# Este arquivo é para desenvolvimento local e NÃO deve ser commitado para o git.
GOOGLE_GENERATIVE_AI_API_KEY=SUA_CHAVE_DE_API_DO_GOOGLE_AI

Substitua SUA_CHAVE_DE_API_DO_GOOGLE_AI pela chave que você copiou anteriormente. O Next.js carrega automaticamente este arquivo e torna a chave disponível no servidor, que é exatamente onde precisamos dela.

Capítulo 2: Construindo a Espinha Dorsal do Chatbot

Com nosso projeto configurado, é hora de construir os componentes principais da nossa aplicação: o endpoint da API do lado do servidor que conversa com a IA, e a UI do lado do cliente com a qual os usuários interagirão.

A Arquitetura Cliente-Servidor de uma Aplicação de IA

Nosso chatbot terá duas partes principais:

  1. Uma Rota de API do Lado do Servidor (/api/chat/route.ts): Este é um ambiente seguro que roda em um servidor. Sua função principal é receber o histórico do chat do navegador do usuário, adicionar nossa chave de API secreta, encaminhar a requisição para o serviço Google AI e, em seguida, transmitir (stream) a resposta de volta para o usuário. Manter essa lógica no servidor é crucial para a segurança—garante que nossa chave de API nunca seja exposta ao público.
  2. Uma UI do Lado do Cliente (page.tsx): Este é o componente React que roda no navegador do usuário. É responsável por renderizar o histórico do chat, capturar a entrada do usuário e enviar essa entrada para nossa rota de API.

Essa separação é fundamental para construir aplicações web seguras e performáticas.

Passo 4: Criando o Handler da Rota de API

Vamos criar o endpoint do lado do servidor. No seu diretório src/app, crie uma nova pasta api, e dentro dela, outra pasta chat. Finalmente, crie um arquivo chamado route.ts dentro da pasta chat.

O caminho final deve ser src/app/api/chat/route.ts.

Preencha este arquivo com o seguinte código:

// src/app/api/chat/route.ts

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

// Configuração específica do Vercel para permitir streaming de respostas por até 30 segundos
export const maxDuration = 30;

// O handler principal da rota de API
export async function POST(req: Request) {
  try {
    // Extrai o array `messages` do corpo da requisição
    const { messages } = await req.json();

    // Chama o provedor de IA com o histórico da conversa
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // O array `messages` fornece ao modelo contexto para a conversa
      messages,
    });

    // Responde com um streaming de resposta
    return result.toDataStreamResponse();
  } catch (error) {
    // É uma boa prática lidar com possíveis erros
    if (error instanceof Error) {
      return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
    return new Response(JSON.stringify({ error: 'An unknown error occurred' }), { status: 500 });
  }
}

Vamos dissecar este arquivo crucial:

Passo 5: Criando a Interface do Usuário

Agora, a parte divertida: construir a UI. Graças ao pacote @ai-sdk/react, isso é surpreendentemente simples. Abra o arquivo da página principal em src/app/page.tsx e substitua todo o seu conteúdo pelo seguinte:

// src/app/page.tsx

'use client';

import { useChat } from '@ai-sdk/react';
import { useRef, useEffect } from 'react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat();

  // Uma ref para o container rolável de mensagens
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // Efeito para rolar para o final do container de mensagens sempre que as mensagens mudam
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* Container de mensagens */}
      <div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
        {messages.map(m => (
          <div
            key={m.id}
            className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
          >
            {/* Exibe o avatar do usuário */}
            {m.role === 'user' && (
              <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-bold">U</div>
            )}

            {/* Bolha de mensagem */}
            <div
              className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
                m.role === 'user'
                  ? 'bg-blue-500 text-white rounded-br-none'
                  : 'bg-white text-black rounded-bl-none'
              }`}
            >
              <span className="font-bold block">{m.role === 'user' ? 'Você' : 'Assistente AI'}</span>
              {m.content}
            </div>

            {/* Exibe o avatar da IA */}
            {m.role !== 'user' && (
              <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
            )}
          </div>
        ))}
      </div>

      {/* Formulário de entrada */}
      <div className="p-4 bg-white border-t">
        <form onSubmit={handleSubmit} className="flex items-center gap-4 max-w-4xl mx-auto">
          <input
            className="flex-1 p-3 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
            value={input}
            placeholder="Pergunte-me qualquer coisa..."
            onChange={handleInputChange}
            disabled={isLoading}
          />
          <button
            type="submit"
            className="px-6 py-3 bg-blue-500 text-white rounded-full font-semibold hover:bg-blue-600 disabled:bg-blue-300 disabled:cursor-not-allowed"
            disabled={isLoading}
          >
            Enviar
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

Este é um código considerável, mas a maior parte é para criar uma UI polida com Tailwind CSS. Vamos focar na lógica:

Passo 6: Execute Sua Aplicação

Você agora construiu um chatbot de IA completo e bem estruturado. Vamos colocá-lo para funcionar!

npm run dev

Navegue para http://localhost:3000 no seu navegador. Você deverá ser recebido por uma interface de chat polida. Faça uma pergunta. Você verá sua mensagem aparecer instantaneamente, e a resposta da IA será transmitida token por token.

Capítulo 3: Capacidades Avançadas - Dando Superpoderes ao Seu Chatbot

Nosso chatbot é inteligente, mas seu conhecimento é limitado aos seus dados de treinamento. Ele não pode acessar informações em tempo real ou realizar ações no mundo real. Neste capítulo, daremos a ele "Ferramentas" (Tools) para superar essas limitações.

O que são Ferramentas (Tools)?

Uma Ferramenta é uma função que você define e que o LLM pode escolher executar. Você descreve a ferramenta para o modelo, e quando ele pensa que a ferramenta é necessária para responder à consulta de um usuário, ele pausa sua geração de texto e, em vez disso, produz um objeto especial de "chamada de ferramenta". Seu código então executa a função com os argumentos fornecidos pelo modelo, e o resultado é enviado de volta para o modelo. O modelo então usa esta nova informação para gerar sua resposta final e mais precisa.

Vamos capacitar nosso chatbot com duas ferramentas:

  1. Uma ferramenta para obter o clima atual de uma localização.
  2. Uma ferramenta para converter temperaturas de Fahrenheit para Celsius.

Isso permitirá que nosso bot responda a perguntas como "Qual é o clima em Londres em Celsius?"—uma tarefa que requer múltiplos passos e dados externos.

Passo 7: Atualizando a API para Suportar Ferramentas

Precisamos definir nossas ferramentas na chamada streamText no servidor. Abra src/app/api/chat/route.ts e modifique-o para incluir a nova definição de tools.

// src/app/api/chat/route.ts
import { google } from '@ai-sdk/google';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: google('models/gemini-1.5-pro-latest'),
    messages,
    // Define as ferramentas que o modelo pode usar
    tools: {
      getWeather: tool({
        description: 'Obtém o clima atual para uma localização específica. Sempre retorna a temperatura em Fahrenheit.',
        parameters: z.object({
          location: z.string().describe('A cidade e estado, por exemplo, San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // Em uma aplicação real, você buscaria de uma API de clima real
          console.log(`Buscando clima para ${location}`);
          return {
            temperature: Math.floor(Math.random() * (100 - 30 + 1) + 30),
            high: Math.floor(Math.random() * (100 - 80 + 1) + 80),
            low: Math.floor(Math.random() * (50 - 30 + 1) + 30),
            conditions: ['Ensolarado', 'Nublado', 'Chuvoso'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Converte uma temperatura de Fahrenheit para Celsius.',
        parameters: z.object({
          temperature: z.number().describe('A temperatura em Fahrenheit'),
        }),
        execute: async ({ temperature }) => {
          console.log(`Convertendo ${temperature}°F para Celsius`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

Vamos analisar o objeto tools:

Passo 8: Habilitando Chamadas de Ferramenta Multi-Passos na UI

Apenas definir as ferramentas no servidor não é suficiente. Por padrão, quando o modelo faz uma chamada de ferramenta, a conversa para. Precisamos dizer ao nosso hook useChat para enviar automaticamente o resultado dessa chamada de ferramenta de volta ao modelo para que ele possa continuar seu raciocínio e formular uma resposta final.

Isso é incrivelmente simples. Em src/app/page.tsx, atualize a inicialização do hook useChat:

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // Diz ao hook para enviar automaticamente os resultados das ferramentas de volta ao modelo
    experimental_sendExtraToolMessages: true,
  });
  // ... restante do componente
}

É isso. A propriedade experimental_sendExtraToolMessages: true ativa o fluxo de uso de ferramentas em múltiplos passos.

Passo 9: Uma UI Melhor para Invocações de Ferramentas

Nossa UI atual exibe apenas m.content. Quando uma ferramenta é chamada, a informação interessante está em uma propriedade diferente no objeto da mensagem. Vamos criar um componente dedicado para renderizar chamadas de ferramentas de forma agradável.

Primeiro, vamos atualizar o loop principal de mensagens em src/app/page.tsx para renderizar essas invocações.

// src/app/page.tsx

// ... dentro da instrução return do componente Chat
<div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
  {messages.map(m => (
    <div
      key={m.id}
      className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
    >
      {/* ... avatares ... */}
      <div
        className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
          m.role === 'user'
            ? 'bg-blue-500 text-white rounded-br-none'
            : 'bg-white text-black rounded-bl-none'
        }`}
      >
        <span className="font-bold block">{m.role === 'user' ? 'Você' : 'Assistente AI'}</span>

        {/* Renderiza invocações de ferramentas */}
        {m.toolInvocations?.map(tool => (
          <div key={tool.toolCallId} className="my-2 p-2 bg-gray-100 rounded text-sm text-gray-700">
            <p className="font-semibold">Chamada de Ferramenta: `{tool.toolName}`</p>
            <pre className="mt-1 p-1 bg-gray-200 rounded text-xs">
              {JSON.stringify(tool.args, null, 2)}
            </pre>
          </div>
        ))}

        {m.content}
      </div>
      {/* ... avatares ... */}
    </div>
  ))}
  {isLoading && messages[messages.length - 1]?.role === 'assistant' && (
      <div className="flex justify-start p-8 space-x-3">
          <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
          <div className="p-3 rounded-2xl shadow-md bg-white">
              <div className="typing-indicator">
                  <span></span><span></span><span></span>
              </div>
          </div>
      </div>
  )}
</div>
// ...

Também adicionei um indicador de digitação simples que aparece enquanto o assistente está pensando. Você precisará adicionar um pouco de CSS para isso. No seu arquivo src/app/globals.css, adicione:

/* src/app/globals.css */

.typing-indicator span {
  height: 8px;
  width: 8px;
  background-color: #9E9EA1;
  border-radius: 50%;
  display: inline-block;
  animation: a 1.2s infinite ease-in-out;
}
.typing-indicator span:nth-child(1) { animation-delay: -0.4s; }
.typing-indicator span:nth-child(2) { animation-delay: -0.2s; }
@keyframes a {
  0%, 60%, 100% { transform: scale(0.2); }
  30% { transform: scale(1); }
}

Agora, execute a aplicação novamente. Pergunte a ela: "Qual é o clima em Nova York em Celsius?" Você verá uma fascinante cadeia de eventos se desenrolar na sua UI:

  1. O modelo primeiro chamará a ferramenta getWeather. Você verá a chamada da ferramenta renderizada na UI.
  2. O resultado (uma temperatura aleatória em Fahrenheit) é enviado de volta ao modelo.
  3. O modelo, sabendo que precisa de Celsius, então chamará a ferramenta convertFahrenheitToCelsius, usando a temperatura do resultado da primeira ferramenta como sua entrada.
  4. Finalmente, com a temperatura em Celsius em mãos, ele gerará uma resposta em linguagem natural respondendo à sua pergunta original.

Este é o poder de construir Agentes de IA, e o Vercel AI SDK torna essa orquestração complexa notavelmente direta.

Capítulo 4: Para Onde Ir a Partir Daqui?

Você construiu com sucesso um chatbot avançado com IA. Você passou de uma tela em branco para uma aplicação rica em recursos que pode transmitir respostas, lidar com estados de carregamento e erro, e usar ferramentas para interagir com dados externos de forma multi-passo.

Este guia lhe deu uma base sólida, mas é apenas o começo. O Vercel AI SDK tem ainda mais a oferecer. Aqui estão alguns caminhos para sua exploração contínua:

O futuro do desenvolvimento web é inteligente, interativo e personalizado. Com o Vercel AI SDK, você agora possui as ferramentas e o conhecimento para estar na vanguarda desta revolução. Feliz construção!

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API linda?

Quer uma plataforma integrada e All-in-One para sua Equipe de Desenvolvimento trabalhar junta com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman por um preço muito mais acessível!
button

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar