Executando Agents localmente

Use esta página para executar um projeto Agents extraído no seu computador. O loop ReAct, o loop de chamada de funções e a interface final usam a mesma configuração do Vite, mas mostram seus resultados em lugares diferentes. Atualize a busca da chave OpenAI e o ID do modelo legado antes de iniciar o milestone que você tem.

O que você precisa primeiro

Instale uma versão LTS suportada do Node.js. Node 24 é recomendado e inclui npm; a exportação é um projeto Vite, então Node e npm cobrem todo o ferramental que ele precisa.

Você também precisa de uma chave de API OpenAI com cobrança e acesso ao modelo habilitados. O acesso ao modelo é configurado por projeto no painel OpenAI: o projeto ao qual sua chave pertence deve permitir o modelo que você configurar abaixo. A chave em si entra em um arquivo .env em uma etapa posterior.

JunoO que você precisa primeiro Instale a versão LTS do Node.js, que traz npm junto com ela. Você também precisa de uma chave de API OpenAI de uma conta que possa fazer solicitações de modelo pagas. Reunir os dois antes de começar significa que você nunca precisará parar no meio da configuração para encontrá-los, algo que eu sempre fazia!

JunoO que você precisa primeiro A exportação é um projeto Vite, então Node LTS mais npm é todo o ferramental. Sua chave OpenAI entra em .env alguns passos adiante, e acesso ao modelo significa a lista de modelos permitidos no projeto da chave no painel OpenAI. Se você verificar essa lista agora, evita o erro mais confuso depois.

JunoO que você precisa primeiro O Vite iniciará esses projetos sem uma chave funcionando, o que torna uma chave quebrada a falha mais silenciosa nesta página. Nada relata um problema até o loop do agent fazer sua primeira solicitação de modelo e receber um erro de autenticação ou cota. Confirme cobrança e acesso ao modelo antes de culpar o código. Uma vez perdi uma manhã porque culpei o código primeiro.

Abra e instale o projeto

Abra um terminal na pasta extraída contendo package.json, então instale os pacotes:

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

JunoAbra e instale o projeto Abra a pasta extraída que contém package.json e execute npm install lá. Todos os comandos posteriores nesta página acontecem nessa mesma pasta. Manter um terminal aberto nessa pasta evita que você perca a noção de onde está, algo que me acontecia constantemente no meu primeiro mês.

JunoAbra e instale o projeto Os três milestones compartilham a configuração npm-e-Vite, então essa etapa de instalação é idêntica não importa qual você extraiu. Instale ao lado de package.json, então faça as duas mudanças de código descritas na próxima seção. Todos os comandos são executados nessa mesma pasta.

JunoAbra e instale o projeto Essas exportações não vêm com um lockfile, o package-lock.json que fixa versões exatas, então npm install resolve o SDK OpenAI e Vite novamente na sua máquina. Diferentes versões resolvidas são possíveis, mas raramente são a causa aqui. Quando algo quebra depois, verifique suas edições no código-fonte antes de começar a mudar versões de pacotes.

Atualize a chave e o modelo

Em index.js, mude:

apiKey: process.env.OPENAI_API_KEY,

para:

apiKey: import.meta.env.VITE_OPENAI_API_KEY,

O Vite lê valores de ambiente através de import.meta.env; o mesmo reparo aparece em Executando Embeddings e Vector Databases localmente, que adapta uma exportação de curso similar.

Os snapshots do curso usam IDs de modelo legados como gpt-3.5-turbo, gpt-3.5-turbo-1106 e gpt-4-1106-preview. Para esses exemplos do curso, substitua o valor do modelo em seu index.js extraído por gpt-4o-mini:

model: "gpt-4o-mini",

Crie .env ao lado de package.json:

VITE_OPENAI_API_KEY=your-openai-api-key

Crie .gitignore na mesma pasta:

.env
node_modules/

O .gitignore mantém sua chave fora de qualquer repositório que você crie a partir desta pasta; ignoring files and good habits explica por que isso importa.

Esta configuração de aprendizado expõe a chave

O SDK OpenAI está intencionalmente rodando no navegador, e o Vite coloca a chave no bundle do frontend. Use apenas uma chave temporária e restrita. Não implante ou compartilhe esta versão. Agents em produção precisam de um backend.

JunoAtualize a chave e o modelo Troque a antiga busca de chave e o nome do modelo em index.js, coloque sua chave temporária em .env e mantenha esse arquivo fora do Git. Esta versão de aprendizado mostra a chave para o navegador de propósito, então use uma chave que você pode cancelar no momento em que terminar este projeto. Nunca use uma chave da qual qualquer outra coisa dependa.

JunoAtualize a chave e o modelo O Vite expõe apenas variáveis que começam com VITE_, então o nome no código-fonte e o nome em .env devem corresponder exatamente. Procure também todo o download por IDs de modelo legados, porque diferentes milestones contêm diferentes snapshots. Se você perder um ID, um milestone funcionará enquanto outro falha.

JunoAtualize a chave e o modelo A solução em produção é arquitetônica: crie o cliente OpenAI em um backend e deixe o navegador chamar esse backend, para que a chave nunca saia do servidor. A substituição do Vite aqui pertence ao modo de aprendizado, e não é o padrão para implantação. Adicionar um backend após o lançamento custa mais do que construí-lo primeiro, e eu fiz em ambas as ordens.

Execute o projeto

$ npm start

Abra a URL exata do Local impressa pelo Vite. Para um milestone somente console, abra as ferramentas do desenvolvedor do seu navegador e selecione Console. Os loops ReAct e function imprimem seu progresso e resposta lá. No milestone da UI, envie uma mensagem e procure a resposta na página. Pare o Vite com Ctrl+C.

JunoExecute o projeto Execute npm start e abra a URL exata do Local que o Vite imprime. Para os milestones anteriores, a saída aparece no Console do navegador, então uma página que parece vazia pode estar funcionando corretamente. Pressione Ctrl+C para parar quando terminar.

JunoExecute o projeto O Vite escolhe a porta e imprime o endereço exato, então use o que ele imprime em vez de uma URL memorizada. Em um milestone somente console, uma página em branco é o que você deveria esperar; verifique o Console do desenvolvedor para a saída do loop antes de tratá-lo como uma falha de inicialização. Apenas o milestone da UI responde na página em si.

JunoExecute o projeto O Vite iniciando prova que o projeto editado compila, e nada mais; OpenAI ainda não foi contatado. Execute uma interação real, seja a saída do loop no DevTools ou uma mensagem através da interface final, antes de decidir que a configuração está completa. Um projeto que compila não é um projeto que funciona, e parei de aceitar essa conclusão anos atrás.

Solução de problemas

process is not defined: Procure em index.js pelo process.env.OPENAI_API_KEY restante e substitua-o pela forma Vite acima.

Um modelo legado não está disponível: Confirme que cada campo model usa um modelo atual disponível para seu projeto OpenAI. Os milestones baixados podem conter diferentes IDs legados.

A página parece vazia: Os milestones anteriores relatam progresso no console do desenvolvedor em vez da página. Use a lição final da UI se você quiser uma interface de chat visível.

Erro de autenticação ou cota: Verifique se .env está ao lado de package.json, reinicie o Vite e confirme cobrança e acesso à chave na conta OpenAI.

JunoSolução de problemas Combine cada sintoma com seu conserto: process is not defined significa que a busca de chave ainda precisa mudar, uma página vazia geralmente significa que a saída está no Console, e um erro de autenticação aponta para a chave ou a conta. Cada um tem um único conserto. Trabalhe através deles com calma, um de cada vez.

JunoSolução de problemas Verifique na ordem: o código-fonte lê a variável Vite, .env usa o nome correspondente, cada ID de modelo é atual, e você está observando o lugar onde esse milestone realmente imprime sua saída. Essa sequência segue a ordem em que a solicitação é construída, então o primeiro passo que falha é a causa. Conserte esse e execute novamente antes de mudar qualquer outra coisa.

JunoSolução de problemas Quando o agent fica em silêncio, há quatro possíveis causas: a chave nunca chegou ao bundle, o ID do modelo já não existe, OpenAI rejeitou a conta, ou a UI descartou a mensagem retornada. Verifique-as nessa ordem, porque uma falha no início da lista produz os mesmos sintomas que as posteriores. Verificá-las fora de ordem uma vez transformou um conserto de cinco minutos em uma noite inteira para mim.