Executando o código localmente

Use esta página para executar um projeto Learn AI Agents extraído no seu computador e obter uma resposta do agente OpenSwap com sua chave de provedor. Duas coisas diferem do Scrimba: você fornece ao projeto seus três valores de IA em um arquivo .env em vez das configurações do Scrimba, e o projeto não recarrega automaticamente depois que você muda um arquivo. A versão Scrimba continua funcionando independentemente de você fazer isso.

O que você precisa primeiro

Instale uma versão LTS suportada do Node.js. Node 24 é recomendado, Node 22 também funciona, e ambos incluem npm. Verifique se ambos os comandos imprimem uma versão. Seus números de versão podem ser diferentes:

$ node --version
v24.18.0
$ npm --version
11.18.0

Você também precisa dos três valores que salvou nas configurações de ambiente do Scrimba: AI_KEY, AI_MODEL e AI_URL. Se não os tiver mais, ou nunca os configurou, configuração do provedor guia você por obter uma chave do OpenAI ou OpenRouter.

JunoO que você precisa primeiro Instale a versão LTS do Node.js, que inclui npm, e verifique se node --version e npm --version ambos imprimem uma versão.

Depois tenha sua chave, modelo e URL do Scrimba prontos para copiar. São os únicos valores que este projeto precisa.

JunoO que você precisa primeiro O projeto tem duas partes: um servidor Express que guarda sua chave e chama o provedor, e um servidor Vite que envia a página para seu navegador. Um comando inicia ambos, e os três valores são lidos apenas pela parte Express.

JunoO que você precisa primeiroenvironment.js carrega .env com loadEnvFile de node:process, que o Node adicionou na versão 20.12. Em um Node mais antigo, ele para com uma mensagem que nomeia essa versão em vez de iniciar com valores vazios, então essa mensagem sempre significa trocar de Node, não de .env.

Instale os pacotes

Abra um terminal na pasta do projeto extraído. É a que contém package.json, server.js e environment.js:

$ cd path-to-your-extracted-project

Instale os pacotes:

$ npm install
added 106 packages, and audited 107 packages in 6s

O número de pacotes depende da lição. npm também pode listar vulnerabilidades ou avisar que alguns pacotes têm scripts de instalação. Nenhum desses problemas impede o projeto de executar.

JunoInstale os pacotes Abra o terminal na pasta que contém package.json, depois execute npm install. Termina dizendo quantos pacotes foram adicionados.

Se npm disser que não consegue encontrar package.json, você está na pasta errada.

JunoInstale os pacotes O download inclui package-lock.json, então npm install obtém as mesmas versões de pacotes que a lição usou no Scrimba. Tudo que ele instala vai em node_modules nesta pasta, incluindo as ferramentas que iniciam os dois servidores.

JunoInstale os pacotesnpm start executa concurrently, que existe apenas em node_modules desta pasta. Iniciar antes de instalar falha com concurrently: command not found, não com um erro sobre seu código.

Crie seu arquivo .env

O projeto cria o arquivo para você. Inicie-o uma vez:

$ npm start

Na primeira vez, o servidor não encontra valores, cria .env ao lado de package.json e para com esta mensagem:

Error: Missing environment variables: AI_KEY, AI_MODEL, AI_URL.
Created .env with the required variable names. Complete it, then restart the app.
Setup guide: https://docs.scrimba.com/ai-agents/running-locally

Vite continua executando e imprime um endereço, mas a página ainda não pode funcionar. Pressione Ctrl+C para parar tudo, depois abra .env. Tem uma linha vazia por valor e uma linha de porta comentada no final:

AI_KEY=
AI_MODEL=
AI_URL=
GITHUB_TOKEN=
# PORT=3001

Preencha seus três valores logo após cada =, sem espaços ou aspas. Com OpenAI, o padrão do curso, fica assim:

AI_KEY=your-api-key-here
AI_MODEL=gpt-5.4-nano
AI_URL=https://api.openai.com/v1
GITHUB_TOKEN=
# PORT=3001

GITHUB_TOKEN aparece apenas em lições que verificam projetos no GitHub. Você pode deixar vazio; GitHub então responde com um limite de taxa menor. Deixe a linha # PORT=3001 como está.

Nunca faça commit do seu arquivo .env

Se você colocar este projeto no Git, crie um .gitignore ao lado de package.json antes do seu primeiro commit, para que sua chave e os pacotes instalados fiquem fora do repositório:

.env
node_modules

Uma chave que chega a um repositório fica no histórico mesmo depois que você deleta o arquivo; o único remédio é deletar a chave no seu provedor e criar uma nova. O manual do Git cobre o hábito em ignorando arquivos e boas práticas.

JunoCrie seu arquivo .env Execute npm start uma vez para que o projeto crie .env, pressione Ctrl+C, depois copie sua chave, modelo e URL nos três linhas vazias e salve.

Se disser que criou .env novamente na próxima vez, seu arquivo tem um nome diferente, como .env.txt.

JunoCrie seu arquivo .env No Scrimba, o editor passa esses valores para o projeto em execução. Aqui, environment.js executa primeiro em server.js, lê .env e se recusa a iniciar o servidor enquanto um valor necessário está vazio, então um valor ausente aparece antes de qualquer requisição ser feita.

JunoCrie seu arquivo .env O arquivo é criado apenas quando nenhum arquivo chamado .env existe, então um arquivo salvo como .env.txt é ignorado e um novo .env vazio aparece ao lado dele. Os valores são lidos uma vez, na inicialização, é por isso que cada edição precisa de uma reinicialização.

Inicie o app e envie uma requisição

Inicie o projeto novamente:

$ npm start

Ambos os servidores imprimem no mesmo terminal. Marcas de seleção para seus três valores e dois endereços significam que ambos iniciaram:

Environment check:
✓ AI_KEY: configured
✓ AI_MODEL: gpt-5.4-nano
✓ AI_URL: https://api.openai.com/v1
○ Optional environment not configured: GITHUB_TOKEN
OpenSwap server running at http://localhost:3001

  VITE v6.4.3  ready in 150 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Abra o endereço Local, não o 3001, e use a página como fez na lição. Nas lições OpenSwap, escolha um nome de software ou digite uma requisição, depois clique em Swap it. O botão mostra Loading... enquanto o agente trabalha, e uma resposta aparecendo significa que sua chave, modelo e URL funcionam. Se sua página tem um botão Run Agent em vez disso, clique nele; a saída do agente aparece no terminal, não na página.

Se a página mostra um erro ou nada acontece, o motivo está no terminal; a solução de problemas abaixo combina cada mensagem.

O projeto não recarrega automaticamente. Depois que você muda qualquer arquivo, pressione Ctrl+C, execute npm start novamente, depois atualize o navegador.

JunoInicie o app e envie uma requisição Execute npm start, abra o endereço Local e envie uma requisição.

Se a página mostra um erro, veja o terminal para as linhas que apareceram quando você clicou e encontre-as sob o heading de solução de problemas.

JunoInicie o app e envie uma requisição A página só chama endereços começando com /api no servidor Vite, e o Vite os encaminha para Express. Express envia a requisição para seu provedor com sua chave, então a chave nunca chega ao navegador.

JunoInicie o app e envie uma requisição Toda falha do servidor se torna a mesma mensagem genérica no navegador: a rota registra o erro real com console.error e responde com um 500. A observação de arquivo do Vite está desligada, então ele continua servindo a primeira versão de cada arquivo que enviou, e Express nunca recarrega, é por isso que uma mudança precisa de uma reinicialização.

Quando a porta 3001 está ocupada

Express escuta na porta 3001. Se outra coisa já a usa, mais frequentemente outra lição que você deixou rodando em um terminal diferente, o servidor ainda imprime sua linha server running at http://localhost:3001, depois sai sem um erro. As requisições da página então chegam ao outro programa: você pode ver um erro como is not valid JSON, ou respostas de outra lição.

Pare o outro projeto com Ctrl+C no seu terminal. Para rodar ambos, dê a este uma outra porta: abra .env, remova o # da última linha e mude o número:

PORT=3101

Pressione Ctrl+C e execute npm start novamente. A linha do servidor agora mostra 3101, e Vite envia as requisições da página lá, porque lê a mesma linha.

A própria porta do Vite muda sozinha. Se 5173 está ocupada, Vite imprime Port 5173 is in use, trying another one... e um endereço Local como http://localhost:5174/, então sempre abra o endereço que ele imprime.

JunoQuando a porta 3001 está ocupada Se a página mostra um erro ou respostas de outra lição, procure por outro terminal ainda executando npm start e pare-o com Ctrl+C.

Para manter ambos rodando, mude # PORT=3001 para PORT=3101 no .env deste projeto e reinicie.

JunoQuando a porta 3001 está ocupada Express e o encaminhamento do Vite ambos leem PORT do mesmo .env, então mudar essa única linha move ambos. A própria porta do Vite é separada e não precisa de configuração.

JunoQuando a porta 3001 está ocupada No Express 5, app.listen passa um erro de escuta para seu callback, e o callback deste projeto ignora o argumento e registra a linha de execução. O processo então não tem nada para mantê-lo vivo e sai, então o terminal mostra sucesso enquanto Vite encaminha para quem quer que possua 3001.

Se algo não funcionar

concurrently: command not found (no Windows, 'concurrently' is not recognized): os pacotes não estão instalados nesta pasta. Execute npm install lá, depois npm start.

Missing environment variables: seguido de nomes: aquelas linhas em .env ainda estão vazias, ou o arquivo não foi salvo. Preencha-as e inicie novamente.

Diz Created .env novamente, embora você tenha criado um: seu arquivo não tem o nome exato .env na pasta com package.json. Um arquivo salvo como .env.txt não conta. Coloque seus valores no novo .env e delete o outro arquivo.

A página mostra Unexpected end of JSON input: o servidor Express não está rodando, e o terminal mostra [vite] http proxy error. Role para cima até o primeiro erro acima das linhas do Vite; ele diz por que Express parou.

O terminal mostra 401 Incorrect API key provided (OpenAI) ou 401 Missing Authentication header (OpenRouter): o provedor rejeitou AI_KEY. Copie a chave novamente do seu provedor, salve .env e reinicie.

O terminal mostra 429 e exceeded your current quota: a chave funciona, mas a conta não tem crédito para gastar. Adicione crédito com seu provedor e tente novamente.

O terminal mostra um erro de modelo não encontrado: AI_MODEL e AI_URL pertencem a provedores diferentes, por exemplo um ID de modelo OpenAI com a URL do OpenRouter. Mude todos os três valores juntos quando você mudar de provedores.

"Local environment loading requires Node.js 20.12 or newer." Seu Node é muito antigo para o carregador .env do projeto. Instale a versão LTS atual de nodejs.org, depois execute npm start novamente.

Em lições com uma barra lateral de chat, uma requisição falhada pode deixar um chat chamado New conversation. É vazio e não causa problemas.

Tudo parece certo e ainda falha. Leve para o Discord do curso, com o que você executou e o que voltou. Problemas de configuração são quase sempre específicos de uma máquina, e alguém geralmente já enfrentou o seu.

JunoSe algo não funcionar Leia o terminal primeiro: encontre a primeira linha que começa com Error ou mostra um número como 401 e combine com um heading em negrito acima. Reinicie com npm start depois de cada mudança em .env.

JunoSe algo não funcionar As falhas vêm em ordem: pacotes ausentes, valores ausentes, Express não rodando, depois o provedor rejeitando a chave, conta ou modelo. O primeiro que você encontra diz qual passo você deve voltar.

JunoSe algo não funcionar Um 401 significa que Express iniciou com todos os três valores e alcançou o provedor em AI_URL, então .env carregou; esse provedor rejeitou a chave. Uma chave do outro provedor recebe o mesmo 401, é por isso que os três valores mudam como um conjunto.