# Como integrar o Hermes Agent com o Atlas Cloud? > Conecte o Hermes Agent ao Atlas Cloud armazenando a chave do Atlas Cloud em ~/.hermes/.env, selecionando o provedor: custom, definindo a URL base como https://api.atlascloud.ai/v1 e escolhendo um ID de modelo ativo de /v1/models. O Agente Hermes pode usar o [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) como um provedor de inferência personalizado compatível com OpenAI. A integração precisa de três coisas: uma chave de API do Atlas Cloud, a URL base `https://api.atlascloud.ai/v1` e um [ID de modelo da lista de modelos do Atlas Cloud](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new). Uma vez que esses itens estejam na configuração atual de `model:` do Agente Hermes, o agente pode executar via Atlas Cloud sem um SDK específico do provedor. > **Principais conclusões** > > * Instale o Agente Hermes com o instalador oficial e mantenha a chave do Atlas Cloud em `~/.hermes/.env` em vez de no controle de versão. > * Configure o Agente Hermes com `provider: custom` e `base_url: https://api.atlascloud.ai/v1`. > * Consulte `/v1/models` antes de escolher um modelo. Os nomes dos modelos mudam mais rápido que o código de integração, portanto, a resposta ao vivo é mais segura do que copiar um ID antigo de um tutorial. > * Execute `hermes doctor` antes de iniciar um agente de longa duração e, em seguida, use `hermes` para testar a primeira conversa. > * A API unificada do Atlas Cloud permite alterar o modelo de linguagem posteriormente sem reconstruir a integração com o Hermes. ## O que são o Agente Hermes e o Atlas Cloud? [Agente Hermes](https://github.com/NousResearch/hermes-agent) é um agente open-source de autoaperfeiçoamento construído pela Nous Research. Ele inclui interface de terminal, memória persistente, habilidades, automações agendadas, gateways de mensagens e suporte a múltiplos provedores de inferência. A documentação atual do Agente Hermes enfatiza que os modelos podem ser alterados sem reescrever o agente. [A plataforma principal do Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) expõe centenas de modelos de linguagem, imagem, vídeo e áudio através de uma API unificada. Para o Agente Hermes, a parte importante é sua superfície de inferência compatível com OpenAI: o Hermes pode tratar o Atlas Cloud como um provedor personalizado e enviar tráfego normal de conclusão de chat para ele. Essa combinação é útil quando você deseja que o Agente Hermes permaneça independente de um único fornecedor de modelo. A configuração do agente permanece estável, enquanto o modelo do Atlas Cloud selecionado pode mudar conforme requisitos, preços ou disponibilidade. ## Antes de começar Você precisa de: 1. Um ambiente Linux, macOS, WSL2 ou Windows compatível. 2. Uma instalação funcional do Agente Hermes. 3. Uma conta do Atlas Cloud e chave de API. 4. Saldo suficiente no Atlas Cloud ou acesso à conta para o modelo selecionado. Não cole uma chave de API real em um repositório público, issue, captura de tela ou arquivo de configuração compartilhado. O Agente Hermes suporta um arquivo `.env` local especificamente para que segredos possam permanecer separados da configuração comum. ## Passo 1: Instalar o Agente Hermes No Linux, macOS ou WSL2, use o instalador publicado pela Nous Research: ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` Recarregue seu shell após a instalação: ```bash source ~/.zshrc ``` Se você usa Bash, recarregue `~/.bashrc` em vez disso. Em seguida, confirme que a CLI está disponível: ```bash hermes --help ``` O projeto oficial também suporta Windows nativo através de seu instalador PowerShell. Siga a [documentação de instalação do Agente Hermes](https://hermes-agent.nousresearch.com/docs/) atual, em vez de traduzir o comando Unix para PowerShell você mesmo. ## Passo 2: Criar uma chave de API do Atlas Cloud Faça login no console do Atlas Cloud e crie uma chave de API para esta implantação do Agente Hermes. Use uma chave dedicada quando suas permissões de conta permitirem; separar o tráfego do agente facilita a rotação futura e a revisão de uso. Armazene a chave no arquivo de ambiente local do Agente Hermes: ```bash printf '\nOPENAI_API_KEY=%s\n' 'substitua-pela-sua-chave-do-atlas-cloud' >> ~/.hermes/.env ``` Substitua o placeholder localmente. Não inclua a chave real em `config.yaml` se esse arquivo for copiado, sincronizado ou versionado. Por que usar `OPENAI_API_KEY`? O caminho atual de provedor personalizado do Agente Hermes resolve essa variável de ambiente quando uma URL base explícita compatível com OpenAI é configurada. O Atlas Cloud usa autenticação por token bearer nessa interface compatível. ## Passo 3: Obter um ID de modelo ao vivo do Atlas Cloud Não adivinhe o ID do modelo. Verifique a [lista de modelos do Atlas Cloud](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new) e, em seguida, pergunte à API pelo catálogo atual: ```bash export ATLASCLOUD_API_KEY='substitua-pela-sua-chave-do-atlas-cloud' curl https://api.atlascloud.ai/v1/models \ -H "Authorization: Bearer $ATLASCLOUD_API_KEY" ``` Escolha um modelo de texto que suporte o comportamento necessário para sua implantação do Hermes, especialmente uso de ferramentas, raciocínio, comprimento de contexto e latência esperada. Copie o `id` exato retornado pela API. Para um agente persistente, comece com um modelo de propósito geral com capacidade de ferramentas, em vez de otimizar apenas pelo menor preço de token. Após a integração funcionar, você pode testar modelos de menor custo para sumarização ou outras tarefas rotineiras. ## Passo 4: Apontar o Agente Hermes para o Atlas Cloud Abra `~/.hermes/config.yaml` e configure a seção `model:` de nível superior atual: ```yaml model: default: "substitua-por-um-id-de-modelo-do-atlas-cloud-ao-vivo" provider: "custom" base_url: "https://api.atlascloud.ai/v1" ``` Mantenha a chave em `~/.hermes/.env`; o arquivo YAML precisa apenas do provedor, endpoint e ID do modelo. Esse detalhe é importante porque exemplos mais antigos do Agente Hermes podem usar um bloco `inference:`. A amostra de configuração oficial atual usa `model:`. Se a versão instalada se comportar de forma diferente, execute `hermes update` e verifique a documentação de configuração fornecida com essa versão antes de alterar outras configurações. ## Passo 5: Diagnosticar a configuração Execute as verificações internas do Agente Hermes: ```bash hermes doctor ``` Em seguida, inicie o agente: ```bash hermes ``` Envie uma pequena solicitação de teste que não precise de ferramentas externas, por exemplo: ```text Responda com o nome do modelo que você está usando e, em seguida, resuma quais ferramentas estão disponíveis nesta sessão do Hermes. ``` Uma resposta normal em streaming confirma que o Hermes pode autenticar, alcançar o endpoint do Atlas Cloud e chamar o modelo configurado. ## Problemas comuns de integração ### Erros de autenticação Verifique se `OPENAI_API_KEY` existe em `~/.hermes/.env`, contém a chave do Atlas Cloud sem aspas extras ou espaços e está sendo carregada pela mesma instalação do Hermes que você está executando. Gire a chave se ela tiver sido exposta. ### Erros de modelo desconhecido Chame `https://api.atlascloud.ai/v1/models` novamente e copie o ID ao vivo exato. Não remova um prefixo do provedor nem encurte o identificador, a menos que a resposta da API em si use a forma mais curta. ### Hermes chama o provedor errado Confirme que a configuração ativa contém ambos: ```yaml provider: "custom" base_url: "https://api.atlascloud.ai/v1" ``` Selecionar um provedor interno pode rotear a solicitação para o endpoint desse provedor em vez do Atlas Cloud. ### A configuração corresponde a um tutorial antigo, mas falha O Agente Hermes está evoluindo rapidamente. Compare seu arquivo com a [referência oficial de configuração](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) atual e use `hermes config get` para inspecionar o perfil ativo. Em particular, verifique se sua versão espera a estrutura `model:` atual. ## Como alterar modelos sem reconstruir a integração Uma vez que o Atlas Cloud está configurado como provedor personalizado, trocar modelos requer apenas um novo ID do [catálogo de modelos ao vivo](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new): 1. Consulte `/v1/models`. 2. Atualize `model.default` em `~/.hermes/config.yaml`. 3. Execute `hermes doctor`. 4. Inicie uma nova conversa de teste. O endpoint e o tratamento de credenciais permanecem os mesmos. Este é o valor prático de uma API unificada para um agente: a avaliação do modelo se torna uma alteração de configuração em vez de uma nova integração de SDK. ## Quando essa configuração é uma boa escolha A integração com o Atlas Cloud é uma boa escolha quando: * Você deseja que o Agente Hermes acesse várias famílias de modelos através de uma única conta. * Você espera comparar ou substituir o modelo principal ao longo do tempo. * Você deseja um endpoint compatível com OpenAI em vez de código de cliente específico do provedor. * Suas futuras habilidades do Hermes podem precisar de acesso a modelos de imagem ou vídeo da mesma plataforma. Uma integração direta com o provedor de modelo pode ser mais simples se o agente usar permanentemente um provedor e você não precisar do catálogo de modelos mais amplo do Atlas Cloud. A escolha certa depende se flexibilidade e acesso centralizado são mais importantes do que ter a configuração de provedor único mais curta possível. ## Lista de verificação final Antes de deixar o Agente Hermes executando sem supervisão, verifique todos os cinco itens: - A chave do Atlas Cloud está armazenada fora do controle de versão. - `provider` está definido como `custom`. - `base_url` é exatamente `https://api.atlascloud.ai/v1`. - `model.default` corresponde a um ID do endpoint de modelos ao vivo. - `hermes doctor` e uma conversa simples são bem-sucedidos. Com essas verificações concluídas, o Agente Hermes está integrado ao Atlas Cloud. Agora você pode avaliar diferentes modelos de linguagem por trás do mesmo agente sem alterar suas ferramentas, memória, habilidades ou interface de usuário. ## FAQ ### O Hermes Agent possui um provedor Atlas Cloud integrado? Um provedor dedicado do Atlas Cloud não é necessário. O Hermes Agent pode se conectar através de seu provedor personalizado compatível com OpenAI usando a URL base e a chave de API do Atlas Cloud. ### Qual é a URL base do Atlas Cloud para o Hermes Agent? Use https://api.atlascloud.ai/v1 como a URL base compatível com OpenAI. ### Onde devo armazenar a chave da API do Atlas Cloud? Armazene-a em ~/.hermes/.env como OPENAI_API_KEY e mantenha a chave real fora de arquivos de configuração, capturas de tela e controle de versão. ### Qual modelo do Atlas Cloud o Hermes Agent deve usar? Consulte https://api.atlascloud.ai/v1/models e escolha um modelo de texto atual que atenda aos seus requisitos de uso de ferramentas, raciocínio, contexto, latência e custo. ### Como posso verificar a integração? Execute o hermes doctor, inicie o Hermes com o comando hermes e envie um pequeno prompt de teste. Erros de autenticação ou modelo desconhecido geralmente apontam para a chave da API, URL base ou ID do modelo.