Executando o curso do Vercel AI SDK localmente

Use esta página para rodar o agente de suporte ao cliente extraído no seu computador. Você conecta seu servidor Express ao OpenAI e aos dados do Supabase criados no curso, depois faz uma mudança no script de inicialização para que o Node carregue esses valores de .env. O guia Embeddings and Vector Databases executa um projeto relacionado com o mesmo tipo de configuração de vector do Supabase.

O que você precisa primeiro

Instale uma versão LTS suportada do Node.js. Node 24 é recomendado. Você também precisa de:

• uma chave de API OpenAI com cobrança e acesso ao modelo;
• o projeto do Supabase e os dados criados durante o curso;
• uma chave com acesso ao banco de dados do lado do servidor: uma chave secreta do Supabase (começa com sb_secret_) ou a chave legada service_role.

Uma chave secreta do Supabase e a chave legada service_role contornam Row Level Security. Uma chave de qualquer um desses tipos pertence apenas ao .env do lado do servidor, nunca em código de navegador. O Supabase está descontinuando as chaves legadas até o final de 2026; ainda funcionam, mas uma chave secreta é a que durará. Veja Supabase API keys.

JunoO que você precisa primeiro Instale o Node.js LTS, depois reúna sua chave OpenAI, o projeto Supabase do curso e sua chave secreta.

Essa chave do Supabase funciona como uma chave mestra para todo o banco de dados, então ela só vai no arquivo .env do servidor.

JunoO que você precisa primeiro O servidor lê o Supabase com uma chave que tem permissões elevadas, e a recuperação não retorna nada útil sem as linhas criadas durante o curso. Ambos os serviços e esses dados têm de existir antes da sua primeira execução.

JunoO que você precisa primeiro Uma chave secreta e a chave legada service_role contornam Row Level Security, então quem as tem age com permissões completas do banco de dados do servidor. Em código de navegador, todo visitante que abrir devtools as teria também. Mantenha apenas no Express.

Abra e instale o projeto

Abra um terminal na pasta extraída que contém package.json, depois instale os pacotes fixados:

$ cd path-to-your-downloaded-project
$ npm ci

JunoAbra e instale o projeto Execute npm ci na pasta extraída, aquela que contém package.json. Ela instala exatamente as versões de pacotes com as quais o curso foi construído, então não há nada para escolher aqui.

JunoAbra e instale o projetonpm ci instala a partir do lockfile incluído, então suas versões correspondem exatamente ao projeto de agente de suporte ao cliente extraído. Isso é importante porque o AI SDK e o código do modelo foram escritos para essas versões.

JunoAbra e instale o projeto Instale a partir do lockfile baixado antes de mexer em qualquer outra coisa. Depois altere apenas o script de inicialização, para que uma atualização de dependência não relacionada não seja confundida com a correção do arquivo de ambiente.

Faça o Node carregar .env

Abra package.json e altere o script start de:

"start": "node server.js"

para:

"start": "node --env-file=.env server.js"

O código usa o nome de variável legado SUPABASE_SERVICE_ROLE_KEY. Você pode armazenar uma chave secreta atual do Supabase nessa variável sem renomear nada no código. O valor tem de ser uma chave secreta ou a chave legada service_role, não uma chave publicável.

Crie .env ao lado de package.json:

OPENAI_API_KEY=your-openai-api-key
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-server-side-secret-key
PORT=3000

Crie .gitignore:

.env
node_modules/

O manual do Git aborda esse hábito em ignoring files and good habits.

Mantenha a chave do Supabase no servidor

Nunca renomeie a chave secreta do Supabase com um prefixo VITE_ ou a mova para client.js. Essa chave tem acesso elevado ao banco de dados. Não faça commit de .env nem o compartilhe em um ZIP.

JunoFaça o Node carregar .env Adicione --env-file=.env ao script start, crie .env com todos os quatro valores e mantenha-o fora do Git.

Crie o .gitignore antes do seu primeiro commit, para que a chave nunca tenha chance de chegar ao repositório.

JunoFaça o Node carregar .env Node não lê .env por conta própria, então o projeto extraído inicia sem configuração. A flag --env-file é integrada ao Node: nenhum pacote extra, e os valores ficam no servidor onde o Express os lê.

JunoFaça o Node carregar .env A flag carrega os quatro nomes de variáveis existentes em process.env antes que server.js execute. Apenas o Express os lê, então os segredos do OpenAI e Supabase nunca aparecem em código enviado ao navegador, e nenhuma dependência dotenv é necessária.

Mantenha os modelos fornecidos

O constants.js baixado usa gpt-4o para geração e classificação de respostas e text-embedding-3-small para embeddings. A configuração local não requer alterar nenhum dos modelos. Mantenha-os inalterados a menos que o OpenAI rejeite um para seu projeto.

Se você depois substituir um modelo, teste o fluxo completo do agente. Substituir o modelo de embedding requer cuidado extra: um modelo com a mesma contagem de dimensões, mas um espaço vetorial diferente retorna correspondências ruins e não relata nenhum erro, então regenere os vetores armazenados do Supabase depois de alterar.

JunoMantenha os modelos fornecidos Deixe ambos os nomes de modelo em constants.js como estão. Se seu projeto OpenAI rejeitar um, verifique a lista de modelos atual antes de editar o código e teste todo o agente novamente.

JunoMantenha os modelos fornecidos Os papéis de resposta, classificação e embedding têm necessidades de compatibilidade diferentes, então substituir um modelo nunca é uma mudança de uma linha. Uma substituição tem de funcionar com esse SDK e manter compatibilidade com os vetores já armazenados no Supabase.

JunoMantenha os modelos fornecidos Os embeddings de consulta são comparados com os vetores armazenados, então ambos têm de vir do mesmo modelo. Um modelo de embedding diferente com a mesma contagem de dimensões quebra a recuperação silenciosamente: as respostas pioram e nada gera erro. Alterar significa regenerar os vetores armazenados, não apenas editar constants.js.

Execute o agente

$ npm start

Abra http://localhost:3000, ou use a porta que você definiu em .env. Pare o servidor com Ctrl+C.

O carregamento da página mostra que o servidor local está em execução. Faça uma pergunta coberta pelos dados do curso: uma resposta útil mostra que a recuperação do Supabase e a geração do OpenAI também funcionam. O capítulo RAG explica por que o agente baseia suas respostas nos dados recuperados do curso.

JunoExecute o agente Execute npm start e abra o endereço local no seu navegador. O carregamento da página prova que o servidor executa.

Uma resposta completa também precisa do OpenAI e dos dados do Supabase do curso, então trate-os como uma segunda verificação separada.

JunoExecute o agente Trate a inicialização do servidor e a geração de respostas como verificações separadas: um servidor em execução com respostas falhando aponta para OpenAI, Supabase ou as chaves que você deu a eles, não para o código. Pare com Ctrl+C e defina PORT em .env se outro processo já usar a porta 3000.

JunoExecute o agente Um processo Express serve a página e a API, então uma página carregada prova apenas servir HTTP. As respostas ainda dependem de chamadas OpenAI e recuperação do Supabase, e qualquer uma pode falhar muito depois que a inicialização foi bem-sucedida.

Solução de problemas

Missing OPENAI_API_KEY: Confirme que o script start inclui --env-file=.env, que .env está ao lado de package.json e que o nome da variável corresponde exatamente.

Erro de autenticação ou relação do Supabase: Confirme que a URL e a chave secreta do Supabase pertencem ao mesmo projeto, depois complete as etapas de schema e dados do curso. Essa operação do lado do servidor precisa de uma chave secreta ou da chave legada service_role; uma chave publicável, que é feita para código de navegador, não tem o acesso que requer.

A porta 3000 já está em uso: Altere PORT em .env, reinicie o servidor e abra a nova porta.

A página carrega mas as respostas falham: Verifique o terminal do servidor quanto ao primeiro erro de provedor ou banco de dados. O carregamento da página não prova que OpenAI ou Supabase responderão.

JunoSolução de problemas Uma chave faltante aponta para o script start ou .env, um erro do Supabase aponta para o projeto ou seus dados, e uma página carregada com respostas falhando aponta para um serviço externo. Corresponda o sintoma a um daqueles primeiro.

JunoSolução de problemas Leia o primeiro erro do terminal do servidor, não o último; falhas posteriores são geralmente consequências dele. Esse primeiro erro separa carregamento de ambiente, acesso ao banco de dados, ligação de porta e acesso OpenAI.

JunoSolução de problemas Verifique em ordem: Node carregou .env, Supabase retornou os dados do curso, OpenAI gerou uma resposta? Nunca troque uma chave publicável para fazer um erro desaparecer; isso esconde uma tabela ou política faltante em vez de consertar.