Build a Support Agent with Vercel AI SDKExecutando o curso do Vercel AI SDK localmente
Use esta página para executar o agente de suporte ao cliente extraído do curso do Vercel AI SDK no seu computador e obter uma resposta com sua própria chave OpenAI e o projeto Supabase que você construiu no curso. Um servidor Node executa todo o projeto: ele serve a página de chat e responde suas perguntas, para que suas chaves permaneçam nesse servidor e nunca cheguem ao navegador. Uma coisa difere do editor do Scrimba: o Node não lê .env automaticamente, então o script de inicialização precisa de um sinalizador.
O que você precisa primeiro
Instale uma versão LTS suportada do Node.js. A versão 24 do Node é recomendada e inclui npm.
Verifique se ambos os comandos funcionam. Seus números de versão podem ser diferentes:
$ node --version
v24.18.0
$ npm --version
11.18.0Você também precisa de três valores:
- uma chave de API OpenAI, em uma conta com faturamento configurado, porque o OpenAI escreve cada resposta;
- a URL do seu projeto Supabase, mostrada no diálogo Connect do projeto;
- a chave secreta desse projeto, que começa com
sb_secret_, em Settings > API Keys.
Use o projeto Supabase do curso. O agente busca os documentos de ajuda do Scrimba armazenados lá através da função match_documents do projeto. Se você não tiver mais esse projeto, o servidor ainda precisa de uma URL e chave secreta do Supabase para iniciar, e os valores de um novo projeto funcionarão. Apenas as perguntas sobre o Scrimba usam Supabase, então perguntas gerais ainda recebem respostas de busca na web, enquanto as perguntas sobre Scrimba não encontram nada para buscar.
A chave legada service_role também funciona até o Supabase descontinuá-la, previsto para o final de 2026. Consulte Chaves de API do Supabase.
node --version e npm --version imprimem uma versão. Depois reúna três coisas: sua chave OpenAI, a URL do seu projeto Supabase e a chave secreta desse projeto. Use o projeto Supabase que você construiu no curso; um novo não tem documentos para o agente pesquisar.
Instale os pacotes
Abra um terminal na pasta extraída, a que contém package.json e server.js, e instale as versões exatas de pacotes que o curso usou:
$ cd path-to-your-extracted-project
$ npm ci
added 94 packages, and audited 95 packages in 4sO npm também relata algumas vulnerabilidades nesses pacotes. Elas não impedem o projeto de funcionar no seu computador. Não execute npm audit fix; isso atualiza pacotes contra os quais o código do curso foi escrito.
npm ci na pasta com package.json. Ele termina dizendo quantos pacotes foram adicionados. Se o npm disser que só consegue instalar com um package-lock.json existente, você está na pasta errada.
Altere o script de inicialização
No Scrimba, o editor passava suas chaves para o servidor. No seu computador, o Node lê .env apenas quando você pede, e config.js para o servidor imediatamente se a chave OpenAI estiver faltando. Abra package.json e altere o script de inicialização de:
"start": "node server.js"para:
"start": "node --env-file=.env server.js"O sinalizador já está integrado ao Node, então não há nada extra para instalar.
package.json, adicione --env-file=.env ao script de inicialização exatamente como mostrado e salve o arquivo. Nada mais no projeto muda. Adicione suas chaves ao .env
Crie .env ao lado de package.json com seus três valores:
OPENAI_API_KEY=your-openai-api-key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-supabase-secret-key
PORT=3000O código ainda usa o nome legado SUPABASE_SERVICE_ROLE_KEY; coloque sua chave secreta lá sem renomear nada. Tem que ser a chave secreta ou a chave legada service_role, não a chave publicável, que é feita para código de navegador e não tem o acesso que o servidor precisa. PORT é opcional: sem ele, o servidor usa 3000.
Crie .gitignore ao lado de package.json e adicione:
.env
node_modules/Uma chave que chega a um repositório Git fica no histórico dele mesmo depois que você delete o arquivo. O manual do Git cobre o hábito em ignorando arquivos e boas práticas.
Mantenha a chave Supabase no servidor
Sua chave secreta Supabase pode ler e mudar tudo no seu banco de dados. Neste projeto apenas o servidor a lê, e esse é o único lugar seguro para ela: nunca a copie para client.js e nunca comita ou compartilhe .env.
.env ao lado de package.json com seus valores nas três primeiras linhas, depois liste .env em .gitignore para que o Git nunca o salve. Inicie o agente e faça uma pergunta
Inicie o servidor:
$ npm start
> start
> node --env-file=.env server.js
Server listening at http://localhost:3000Abra http://localhost:3000, ou a porta que você definiu em .env. A página Support AI Chatbot tem uma caixa para sua pergunta e um botão Ask. Faça uma pergunta sobre Scrimba, como redefinir sua senha. A página mostra Thinking… enquanto o agente trabalha, depois a resposta. Quando a resposta vem dos seus documentos Supabase, View Sources abaixo dela lista as passagens que usou, cada uma com um score de similaridade: OpenAI e Supabase funcionam. Uma pergunta geral, sobre notícias por exemplo, é respondida com busca na web e lista páginas web em vez disso; essa precisa apenas do OpenAI. O capítulo RAG explica por que o agente procura as coisas antes de responder.
Se a resposta diz I encountered an error while processing your request using tool calling. Please try again later., a página não consegue contar por quê. O motivo está no terminal onde o servidor funciona, sob a linha [ToolBased] Error in RAG process:.
Pare o servidor com Ctrl+C.
npm start, espere por Server listening at http://localhost:3000 e abra esse endereço. Faça uma pergunta sobre Scrimba e espere pela resposta. Se a resposta diz que encontrou um erro, leia o terminal, não a página.
Solução de problemas
O servidor para imediatamente com Missing OPENAI_API_KEY environment variable: O Node não carregou .env. Verifique se o script de inicialização diz node --env-file=.env server.js e se o nome em .env é exatamente OPENAI_API_KEY. SUPABASE_SERVICE_ROLE_KEY is missing or invalid e SUPABASE_URL is missing or invalid significam o mesmo para esses nomes.
node: .env: not found: O script de inicialização está certo, mas não há .env ao lado de package.json. Verifique se o arquivo é nomeado exatamente .env, não .env.txt.
Invalid supabaseUrl: Must be a valid HTTP or HTTPS URL.: SUPABASE_URL tem que ser o endereço completo do diálogo Connect, começando com https://.
Error: listen EADDRINUSE: address already in use :::3000: Outro programa está usando a porta 3000, geralmente uma execução anterior deste servidor em outro terminal. Pare-o com Ctrl+C, ou defina PORT=3001 em .env, inicie novamente e abra http://localhost:3001.
A resposta diz que encontrou um erro, e o terminal diz Incorrect API key provided: OpenAI rejeitou a chave com um 401. Copie-a novamente da sua conta OpenAI, verifique se não foi deletada e reinicie o servidor.
O terminal diz You exceeded your current quota: A chave funciona, mas a conta OpenAI não tem crédito para gastar. Adicione faturamento na sua conta OpenAI e pergunte novamente.
Uma pergunta sobre Scrimba recebe uma resposta sem fontes, e o terminal mostra uma linha começando com [Tool:KB] Error: OpenAI funciona, mas Supabase não retornou os documentos do curso. Verifique se a URL e a chave secreta vêm do mesmo projeto, se a chave é a chave secreta ou service_role em vez da publicável, e se o projeto ainda tem os documentos do curso e sua função match_documents.
O terminal diz que o modelo gpt-4o não está disponível: OpenAI encerra gpt-4o em 14 de janeiro de 2027 e nomeia gpt-6-luna como seu substituto. Altere ANSWERING_MODEL em constants.js para o substituto na página de descontinuações do OpenAI. Deixe EMBEDDING_MODEL_NAME como text-embedding-3-small: os documentos no Supabase foram incorporados com ele, e um modelo de embedding diferente encontra correspondências fracas sem nenhum erro.
npm start, o problema está em package.json ou .env. Se a página responde com um pedido de desculpas, o motivo está no terminal do servidor.