The AI Engineer PathExecutando o código localmente
Esta página coloca um projeto extraído de Intro to AI Agents em funcionamento no seu computador: um servidor Express que se comunica com seu provedor de IA e um frontend Vite que você abre no navegador. Nada depois nesta parte do curso depende disso, e a versão Scrimba continua funcionando independentemente de você fazer isso ou não.
O que você precisa primeiro
Uma versão LTS suportada do Node.js. Node 24 é recomendado, e Node 22 também funciona. Verifique o que você tem:
$ node --version
v24.18.0Se isso disser "command not found", instale a versão marcada como LTS em nodejs.org.
npm. Node inclui npm, e os downloads do Scrimba são projetos npm. Verifique se está disponível:
$ npm --version
11.18.0
Se um deles disser "command not found", esse é o problema todo, e instalar Node resolve os dois de uma vez.
Abra a pasta do projeto
Abra um terminal na pasta extraída contendo package.json:
$ cd path-to-your-downloaded-projectDê uma olhada no que há lá. Os arquivos exatos variam de acordo com a lição. package.json sempre está lá e lista os comandos que o projeto espera; as lições de aplicação também incluem arquivos como server.js, environment.js e vite.config.js.
cd para entrar na pasta extraída que contém package.json. Todo comando nesta página é executado a partir de lá. Quando um comando diz que um arquivo está faltando, verifique em qual pasta seu terminal está antes de alterar qualquer coisa.
Instale e execute
No Scrimba, AI_URL, AI_KEY e AI_MODEL são armazenados nas configurações da sua conta, e Scrimba os injeta no projeto em execução. É por isso que não há arquivo .env na versão do navegador: ele não é necessário lá, e seria um lugar inadequado para manter uma chave em um editor compartilhado mesmo assim. Na sua máquina nada os injeta, portanto um arquivo .env faz esse trabalho.
Instale as dependências do projeto baixado, então o inicie:
$ npm install
$ npm startNa primeira execução, environment.js percebe que os valores necessários estão faltando, cria .env ao lado de package.json e para o servidor Express com uma mensagem que inclui estas linhas:
Missing environment variables: AI_KEY, AI_MODEL, AI_URL.
Created .env with the required variable names. Complete it, then restart the app.Vite pode continuar em execução, então pressione Ctrl+C para pará-lo antes de editar o novo arquivo. O .env gerado tem uma linha vazia por variável e uma linha de porta comentada no final:
AI_KEY=
AI_MODEL=
AI_URL=
# PORT=3001Preencha seus valores reais logo após cada =, sem espaços ao redor:
AI_KEY=your-api-key-here
AI_MODEL=gpt-5.4-nano
AI_URL=https://api.openai.com/v1
# PORT=3001Estes são os mesmos valores que você coloca nas variáveis de ambiente do Scrimba. Se precisar deles novamente, veja configuração do provedor. Deixe a linha # PORT=3001 como está; o projeto usa a porta 3001 a menos que você a altere.
Algumas lições posteriores adicionam linhas opcionais como GITHUB_TOKEN= ao arquivo gerado. O servidor pode iniciar sem elas e imprime ○ Optional environment not configured: GITHUB_TOKEN. Sem um token GitHub, as requisições GitHub usam o limite de taxa anônima mais baixo.
Nunca faça commit do seu arquivo .env
Se você colocar este projeto em Git, liste .env em um .gitignore na pasta do projeto antes do seu primeiro commit. Uma chave enviada para um repositório público é uma chave que você precisa revogar, e scrapers automatizados a encontram em poucos minutos. node_modules também pertence lá, porque é grande e npm install o reconstrói:
.env
node_modules.env.example é o arquivo que é seguro fazer commit, porque contém texto de placeholder em vez da sua chave. O manual do Git cobre o hábito mais amplo em ignorando arquivos e boas práticas.
Reinicie o projeto após salvar .env:
$ npm startNode carrega o arquivo através do environment.js gerado. O vite.config.js baixado chama loadEnv do Vite, portanto Vite lê o mesmo arquivo quando configura o proxy do navegador para o servidor. Você não precisa instalar dotenv ou editar server.js.
npm start executa dois processos ao mesmo tempo: o servidor Express que mantém sua chave de API e faz requisições de modelo, e o servidor de desenvolvimento Vite que serve o frontend. Você verá a saída de ambos intercalados no mesmo terminal. Uma verificação de ambiente marcada e ambas as linhas de endereço significam que funcionou:
Environment check:
✓ AI_KEY: configured
✓ AI_MODEL: gpt-5.4-nano
✓ AI_URL: https://api.openai.com/v1
OpenSwap server running at http://localhost:3001
VITE v6.4.3 ready in 214 ms
➜ Local: http://localhost:5173/Abra o URL do Vite, não o do Express. O frontend é com o que você interage, e ele encaminha suas chamadas de API para o Express nos bastidores.
Pare os dois com Ctrl+C.
npm install uma vez, depois npm start. O primeiro início cria .env e para; pressione Ctrl+C, preencha os três valores que você usa no Scrimba, salve e inicie novamente. Quando você ver os ticks de verificação de ambiente e o endereço do Vite, abra esse endereço. Se você usar Git, crie o .gitignore antes do seu primeiro commit, não depois.
Como os dois servidores se encontram
Seu código de frontend chama caminhos como /api/swaps, sem nome de host e sem porta. Isso funciona por causa do proxy em vite.config.js:
import { defineConfig, loadEnv } from "vite";
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "");
const port = env.PORT || process.env.PORT || 3001;
return {
server: {
hmr: false,
watch: {
ignored: ["**/*"],
},
proxy: {
"/api": {
target: `http://localhost:${port}`,
},
},
},
};
});Qualquer coisa começando com /api é encaminhada para o Express. É por isso que o código de frontend nunca precisa saber em qual porta o backend está, e também é por isso que você não enfrenta erros de origem cruzada em desenvolvimento.
Os playgrounds do curso desabilitam intencionalmente o comportamento de recarga automática do Vite para que um save não possa apagar a saída atual enquanto você trabalha em uma lição. Atualize o navegador manualmente quando quiser carregar uma mudança.
http://localhost:5173, no seu navegador. Chamadas começando com /api são passadas para o servidor Express para você, então você nunca abre a porta 3001 diretamente. Após editar um arquivo, atualize o navegador você mesmo; a página não recarrega automaticamente.
Quando a porta 3001 está em uso
Se algo mais na sua máquina já usa a porta 3001, o Express falha ao iniciar com EADDRINUSE. Abra .env, remova o # da linha # PORT=3001 no final (ou adicione a linha se não estiver lá) e altere o número:
PORT=3101Depois pare o projeto com Ctrl+C e execute npm start novamente. Essa é a única mudança que você precisa fazer. server.js lê PORT para decidir onde escutar, e Vite lê o mesmo valor antes de configurar seu proxy.
A porta de frontend se comporta diferentemente. Se 5173 está ocupada, Vite se move para a próxima porta livre e imprime esse endereço em seu lugar, portanto leia a linha Local: em vez de digitar localhost:5173 de memória. Para escolher a porta de frontend você mesmo, passe para Vite:
$ npm run client -- --port 5180O simples -- diz ao npm para passar a flag depois dele para o Vite em vez de tratá-la como uma opção npm.
EADDRINUSE, abra .env, altere # PORT=3001 para PORT=3101 (o # desaparece) e reinicie. O frontend pega automaticamente a nova porta de backend. Para o próprio frontend, apenas abra o endereço que o Vite imprime.
Se algo não funcionar
EADDRINUSE significa que a porta já está em uso. Veja a seção acima.
Missing environment variables: seguido por nomes significa que essas linhas em .env ainda estão vazias, ou o arquivo não foi salvo. Preencha-as e reinicie.
Um erro de credenciais ausentes ou autenticação significa que AI_KEY não está chegando ao código, ou o provedor o rejeitou. Verifique se seu arquivo é nomeado exatamente .env e não .env.txt, que fica na mesma pasta que package.json, que o valor está preenchido e que você reiniciou o servidor após editá-lo.
"Local environment loading requires Node.js 20.12 or newer." Seu Node é muito antigo para o carregador .env integrado do projeto. Instale a versão LTS atual, Node 24, em nodejs.org, depois execute npm start novamente. Você não precisa de dotenv.
Um erro de modelo não encontrado geralmente significa que AI_MODEL e AI_URL discordam, por exemplo um ID de modelo OpenAI contra a URL do OpenRouter. Altere as três variáveis juntas quando você mudar de provedor.
Chamadas de API retornam 404 do frontend sugere que Express não está em execução ou está em uma porta diferente da que o proxy espera. Olhe seu terminal: você deve ver a linha do Express e a linha do Vite. Se apenas Vite iniciou, Express travou, e o motivo estará logo acima.
A instalação é concluída, mas npm start não consegue encontrar um pacote. Execute npm install novamente e inclua a saída completa ao pedir ajuda. O download inclui package-lock.json, portanto pnpm e uma configuração de workspace não estão envolvidas.
Tudo parece certo e ainda assim falha. Leve para o Discord do curso, com o que você executou e o que voltou. Problemas de setup são quase sempre específicos de uma máquina, e alguém geralmente já enfrentou o seu.
.env, e um 404 de frontend geralmente significa que Express não está em execução. Reinicie com npm start após cada mudança em .env.