Configuração do provedor

Antes que qualquer código de agente possa ser executado, ele precisa saber para onde enviar uma requisição, qual chave a autoriza e qual modelo pedir. Esta página coloca esses três valores no lugar.

Sua chave de API é uma credencial

Trate-a como trataria uma senha. Nunca cole em um arquivo JavaScript, nunca faça commit dela, nunca a publique em uma mensagem no Discord pedindo ajuda. Quem tiver sua chave pode gastar seu crédito.

Essa regra também explica por que o curso mantém toda chamada de API em um servidor, em vez de no navegador. Código no navegador é visível para qualquer pessoa que abra as ferramentas de desenvolvedor do navegador, então uma chave usada ali é uma chave que você entregou de bandeja.

Verifique o que você já tem

Se você já fez o Intro to AI Engineering, essas variáveis podem ainda estar salvas na sua conta Scrimba.

Abra Settings no editor do Scrimba e depois selecione Edit Environment. Procure por três entradas com exatamente os nomes AI_URL, AI_KEY e AI_MODEL.

Se as três estiverem lá e apontarem para um provedor no qual você ainda tem crédito, é bem provável que já esteja pronto. Vá direto para modelos recomendados e confirme se o modelo em AI_MODEL suporta tool calling, já que esse requisito é mais rígido neste curso do que era no anterior.

Se alguma estiver faltando, ou se você quiser trocar de provedor, continue lendo.

JunoVerifique o que você já tem Antes de se cadastrar em qualquer lugar, olhe em Settings e depois em Edit Environment. O Intro to AI Engineering usava exatamente esses três nomes, então eles podem já estar ali esperando por você.

Verificar leva dez segundos e pode te salvar de criar uma segunda conta que você nem precisa!

JunoVerifique o que você já tem Confira os valores existentes antes de criar qualquer coisa nova. Os nomes vêm sem alteração do Intro to AI Engineering.

Uma coisa para confirmar em vez de simplesmente supor: que o modelo em AI_MODEL suporta tool calling. O curso anterior não exigia isso, então um conjunto de variáveis que funcionava perfeitamente lá ainda pode falhar aqui, já na lição três.

JunoVerifique o que você já tem Aproveitar os valores anteriores é a atitude certa, com uma ressalva sobre a própria chave. Se essa chave está numa conta compartilhada ou de longa duração desde o curso anterior, este é um bom momento para rotacioná-la, porque você não tem registro de onde ela foi colada desde então.

Rotacionar custa um minuto e zera o que você sabe sobre sua exposição. Reaproveitar uma chave de aprendizado antiga é aceitável; reaproveitar uma da qual você perdeu o rastro é o hábito que vale a pena não criar.

Qual provedor escolher

A OpenAI é o padrão usado por este curso. É a API da qual a Responses API se origina, e usá-la exige crédito de API. Os custos dependem do modelo, do tamanho da requisição e de quanto você experimenta, então confira o preço atual antes de adicionar um valor com o qual se sinta confortável.

A OpenRouter é a alternativa se você não pode ou não quer usar a OpenAI. É uma única API que direciona para muitos provedores, incluindo modelos gratuitos, e ela usa o mesmo formato compatível com a OpenAI, então o código do curso não muda.

De qualquer forma, a configuração segue o mesmo formato: criar uma conta, gerar uma chave e depois armazenar a URL do provedor, sua chave e um ID de modelo.

JunoQual provedor escolher Os dois provedores funcionam em todas as lições, então não existe resposta errada aqui. A OpenAI foi a usada nas gravações das lições, o que a torna a mais fácil de acompanhar.

Escolha a OpenRouter se pagar diretamente à OpenAI for complicado onde você está, ou se quiser experimentar um modelo gratuito primeiro.

JunoQual provedor escolher O código do curso não muda entre os dois, porque a OpenRouter usa o mesmo formato de requisição compatível com a OpenAI. Essa é a única razão pela qual ela é oferecida como alternativa.

Divisão prática: OpenAI se você quiser acompanhar exatamente as gravações, OpenRouter se você quiser uma única conta com acesso a muitos provedores ou precisar de um nível gratuito para começar.

JunoQual provedor escolher "Compatível com a OpenAI" é uma afirmação forte que se sustenta bem para o formato da requisição, mas menos bem nas bordas, e é justamente nas bordas que vive o trabalho com agentes. Tipagem estrita de argumentos, forçar a escolha de tool-choice e a imposição de saída estruturada são os três pontos que variam conforme o provedor de origem, e a OpenRouter passa sua requisição para quem estiver servindo aquele modelo.

Isso funciona para este curso nas rotas indicadas na página de modelos. Mantenha essa ressalva em mente quando levar o padrão para outro lugar: a compatibilidade é por rota, não por gateway.

Configurando a OpenAI

Vá até a plataforma de desenvolvedores da OpenAI e faça login ou crie uma conta.

O ChatGPT Plus não é crédito de API

A plataforma de desenvolvedores é cobrada separadamente de uma assinatura do ChatGPT. Ter o ChatGPT Plus não dá nenhum crédito à sua conta de API, e isso pega quase todo mundo pelo menos uma vez.

Abra Billing nas configurações da plataforma e adicione crédito se sua conta não tiver nenhum. Confira o preço atual dos modelos e defina um orçamento adequado ao seu uso.

Agora abra API keys nas configurações da plataforma e selecione Create new secret key. Dê a ela um nome que ainda vá fazer sentido para você em três meses. Quando a chave for criada, copie-a imediatamente, porque o valor completo é mostrado apenas uma vez e não pode ser recuperado depois.

De volta ao Scrimba, abra Edit Environment e defina:

AI_URL=https://api.openai.com/v1
AI_KEY=sua-chave-de-api-aqui
AI_MODEL=gpt-5.4-nano

Veja modelos recomendados se quiser algo diferente do padrão. Salve as variáveis de ambiente depois que as três estiverem no lugar.

JunoConfigurando a OpenAI A chave secreta aparece uma única vez e nunca mais é mostrada, então copie-a para o Scrimba enquanto a janela ainda estiver aberta. Se você fechá-la antes da hora, terá que excluir aquela chave e criar uma nova, o que é chato, mas inofensivo.

Defina um orçamento de cobrança enquanto estiver lá. Leva um minuto e garante que um loop fora de controle nunca vire uma surpresa desagradável!

JunoConfigurando a OpenAI Duas coisas para fazer de uma vez: copiar a chave direto para o Scrimba enquanto ela ainda está visível, e definir um limite de gastos em Billing antes de saber.

Dê à chave um nome que você vai reconhecer em três meses. Quando você tiver várias e precisar revogar uma, uma lista de chaves chamadas "key1" e "test" é um pequeno problema por si só.

JunoConfigurando a OpenAI Um orçamento por chave e um nome sensato são o que permite revogar com precisão depois. A falha contra a qual eles protegem não é o gasto excessivo, é a impossibilidade de saber qual chave foi exposta, obrigando você a revogar tudo e reconstruir todas as integrações que possui.

Para uma conta de aprendizado, isso é um pequeno incômodo. Mas o hábito vale a pena ser criado aqui, porque na primeira vez que isso realmente importar, você estará fazendo isso sob pressão de tempo.

Configurando a OpenRouter

Crie uma conta na OpenRouter, abra a página API Keys e crie uma chave.

A OpenRouter oferece sim modelos gratuitos, e eles são úteis para aprender. Fique atento a duas coisas antes de depender de um deles.

Endpoints gratuitos não têm garantia de disponibilidade, e seu comportamento pode variar de uma execução para outra, o que dificulta saber se um resultado estranho veio do seu código ou do modelo. Endpoints gratuitos também podem direcionar suas requisições para provedores com políticas de dados diferentes, então abra as configurações de Privacy e tome uma decisão consciente antes de habilitá-los.

Se você quiser resultados consistentes, vale o mesmo conselho da OpenAI: carregue um pouco de crédito e escolha um modelo pago leve.

No Scrimba, defina:

AI_URL=https://openrouter.ai/api/v1
AI_KEY=sua-chave-de-api-aqui
AI_MODEL=mistralai/ministral-3b-2512

Salve as variáveis de ambiente.

JunoConfigurando a OpenRouter Uma conta e uma chave, com acesso a muitos provedores. O código do curso não muda em nada para usá-la.

Preste atenção ao formato do ID do modelo: ele inclui o provedor na frente, então é mistralai/ministral-3b-2512, e não apenas o nome curto isoladamente. Esse prefixo confunde as pessoas o tempo todo!

JunoConfigurando a OpenRouter O prefixo do provedor faz parte do ID na OpenRouter, e essa é a diferença a observar ao copiar o nome de um modelo de qualquer outro lugar.

Abra as configurações de Privacy antes de habilitar modelos gratuitos. Essa página controla quais provedores de origem suas requisições podem alcançar, e é a configuração que as pessoas costumam pular no caminho até o nível gratuito.

JunoConfigurando a OpenRouter A página de Privacy importa mais do que sua posição sugere. Rotas gratuitas são subsidiadas por alguém, e os termos ligados a isso variam conforme o provedor de origem, incluindo se seus prompts podem ser retidos ou usados para treinamento.

Para os exercícios do curso, essa é uma decisão de baixo risco. Mesmo assim, tome-a de forma consciente, porque a mesma conta e o mesmo padrão ainda vão estar lá no dia em que você colar algo do trabalho.

Os três valores caminham juntos

A falha de configuração mais comum é um conjunto incompatível, e não um único valor errado. Uma chave válida da OpenAI usada com a URL da OpenRouter falha. Uma configuração válida da OpenRouter com um ID de modelo exclusivo da OpenAI falha. Ambas produzem erros de autenticação ou de modelo não encontrado que dão a impressão de que algo está quebrado no código do curso.

Então, sempre que você trocar de provedor, altere AI_URL, AI_KEY e AI_MODEL como um conjunto só, e salve-os juntos.

Vai executar o código na sua própria máquina?

O Scrimba armazena esses valores como variáveis de ambiente da conta, e é por isso que não existe um arquivo .env no projeto do navegador. Na sua própria máquina, você vai colocar esses mesmos três valores em um arquivo .env. Executando o código localmente explica isso em detalhes.

JunoOs três valores caminham juntos Se você vir um erro de autenticação ou de modelo não encontrado, verifique esses três valores antes de checar qualquer coisa que você escreveu. Em nove de cada dez vezes, um deles ficou esquecido de uma configuração anterior.

As mensagens de erro não ajudam muito aqui, porque descrevem o que deu errado no provedor, então parecem indicar que o código do curso está quebrado. Geralmente não está!

JunoOs três valores caminham juntos Trate uma troca de provedor como uma única edição com três partes, salvas juntas. Alterar apenas duas das três é exatamente o erro que esta seção existe para evitar.

Quando um erro aparecer, leia os três valores de cima a baixo antes de abrir qualquer código. É mais rápido do que depurar, e é a causa muito mais vezes do que qualquer coisa que você tenha escrito.

JunoOs três valores caminham juntos As duas falhas produzem mensagens de erro que apontam para um lugar diferente da causa real. Uma chave enviada para a URL base errada retorna um 401, que parece indicar uma chave inválida. Um modelo que o provedor não oferece retorna um 404 no nome do modelo, que parece um erro de digitação.

A causa subjacente em ambos os casos é o conjunto estar inconsistente, e nenhuma das mensagens diz isso claramente. Esse descompasso entre o sintoma e a causa é o motivo de esta seção existir por conta própria, em vez de ser apenas uma nota de rodapé.

Para onde ir a partir daqui

Modelos recomendados explica o que torna um modelo adequado para trabalho com agentes e quais já foram testados neste curso. Se você preferir ver como a própria requisição é montada, Chat Completions and Responses compara os dois formatos de API.