# Come si integra Hermes Agent con Atlas Cloud? > Collega Hermes Agent ad Atlas Cloud memorizzando la chiave di Atlas Cloud in ~/.hermes/.env, selezionando provider: custom, impostando l'URL di base su https://api.atlascloud.ai/v1 e scegliendo un ID modello attivo da /v1/models. Hermes Agent può utilizzare [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) come provider di inferenza personalizzato compatibile con OpenAI. L'integrazione richiede tre elementi: una chiave API di Atlas Cloud, l'URL di base `https://api.atlascloud.ai/v1` e un [ID modello dall'elenco dei modelli di Atlas Cloud](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new). Una volta inseriti nella configurazione `model:` corrente di Hermes Agent, l'agente può funzionare tramite Atlas Cloud senza un SDK specifico del provider. > **Punti chiave** > > * Installa Hermes Agent con l'installer ufficiale, poi conserva la chiave di Atlas Cloud in `~/.hermes/.env` anziché nel controllo versione. > * Configura Hermes Agent con `provider: custom` e `base_url: https://api.atlascloud.ai/v1`. > * Interroga `/v1/models` prima di scegliere un modello. I nomi dei modelli cambiano più rapidamente del codice di integrazione, quindi la risposta live è più sicura che copiare un vecchio ID da un tutorial. > * Esegui `hermes doctor` prima di avviare un agente a lunga durata, poi usa `hermes` per testare la prima conversazione. > * L'API unificata di Atlas Cloud consente di cambiare il modello linguistico in seguito senza dover ricostruire l'integrazione di Hermes. ## Cosa sono Hermes Agent e Atlas Cloud? [Hermes Agent](https://github.com/NousResearch/hermes-agent) è un agente open-source auto-migliorante sviluppato da Nous Research. Include un'interfaccia a terminale, memoria persistente, competenze, automazioni programmate, gateway di messaggistica e supporto per più provider di inferenza. La documentazione attuale di Hermes Agent sottolinea che i modelli possono essere cambiati senza riscrivere l'agente. [La piattaforma principale di Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud) espone centinaia di modelli linguistici, per immagini, video e audio tramite un'API unificata. Per Hermes Agent, la parte importante è la sua superficie di inferenza compatibile con OpenAI: Hermes può trattare Atlas Cloud come un provider personalizzato e inviare normali richieste di completamento chat. Questa combinazione è utile quando si desidera che Hermes Agent rimanga indipendente da un singolo fornitore di modelli. La configurazione dell'agente rimane stabile, mentre il modello Atlas Cloud selezionato può cambiare al variare dei requisiti, dei prezzi o della disponibilità. ## Prima di iniziare È necessario disporre di: 1. Un ambiente Linux, macOS, WSL2 o Windows supportato. 2. Un'installazione funzionante di Hermes Agent. 3. Un account Atlas Cloud e una chiave API. 4. Credito Atlas Cloud sufficiente o accesso all'account per il modello selezionato. Non incollare una chiave API reale in un repository pubblico, issue, screenshot o file di configurazione condiviso. Hermes Agent supporta un file `.env` locale proprio per mantenere i segreti separati dalla configurazione ordinaria. ## Passaggio 1: Installare Hermes Agent Su Linux, macOS o WSL2, utilizza l'installer pubblicato da Nous Research: ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` Ricarica la shell dopo l'installazione: ```bash source ~/.zshrc ``` Se usi Bash, ricarica invece `~/.bashrc`. Quindi conferma che la CLI sia disponibile: ```bash hermes --help ``` Il progetto ufficiale supporta anche Windows nativo tramite il suo installer PowerShell. Segui la [documentazione di installazione attuale di Hermes Agent](https://hermes-agent.nousresearch.com/docs/) invece di tradurre manualmente il comando Unix in PowerShell. ## Passaggio 2: Creare una chiave API di Atlas Cloud Accedi alla console di Atlas Cloud e crea una chiave API per questa installazione di Hermes Agent. Usa una chiave dedicata quando i controlli dell'account lo consentono; separare il traffico dell'agente semplifica la rotazione e la revisione dell'utilizzo successivi. Archivia la chiave nel file di ambiente locale di Hermes Agent: ```bash printf '\nOPENAI_API_KEY=%s\n' 'sostituisci-con-la-tua-chiave-atlas-cloud' >> ~/.hermes/.env ``` Sostituisci il segnaposto localmente. Non includere la chiave reale in `config.yaml` se tale file verrà sottoposto a backup, sincronizzato o versionato. Perché usare `OPENAI_API_KEY`? Il percorso del provider personalizzato attuale di Hermes Agent risolve tale variabile d'ambiente quando viene configurato un URL di base esplicito compatibile con OpenAI. Atlas Cloud utilizza l'autenticazione bearer token su quell'interfaccia compatibile. ## Passaggio 3: Ottenere un ID modello live di Atlas Cloud Non indovinare l'ID modello. Controlla l'[elenco dei modelli di Atlas Cloud](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new), quindi chiedi all'API il catalogo corrente: ```bash export ATLASCLOUD_API_KEY='sostituisci-con-la-tua-chiave-atlas-cloud' curl https://api.atlascloud.ai/v1/models \ -H "Authorization: Bearer $ATLASCLOUD_API_KEY" ``` Scegli un modello di testo che supporti il comportamento richiesto dalla tua installazione Hermes, in particolare l'uso di strumenti, il ragionamento, la lunghezza del contesto e la latenza prevista. Copia l'esatto `id` restituito dall'API. Per un agente persistente, inizia con un modello generico in grado di usare strumenti, anziché ottimizzare solo per il prezzo per token più basso. Dopo che l'integrazione funziona, puoi testare modelli a costo inferiore per riassunti o altre attività di routine. ## Passaggio 4: Puntare Hermes Agent verso Atlas Cloud Apri `~/.hermes/config.yaml` e configura la sezione `model:` di primo livello corrente: ```yaml model: default: "sostituisci-con-un-id-modello-atlas-cloud-live" provider: "custom" base_url: "https://api.atlascloud.ai/v1" ``` Mantieni la chiave in `~/.hermes/.env`; il file YAML necessita solo del provider, dell'endpoint e dell'ID modello. Questo dettaglio è importante perché alcuni esempi precedenti di Hermes Agent potrebbero utilizzare un blocco `inference:`. L'esempio di configurazione ufficiale corrente usa `model:`. Se la versione installata si comporta diversamente, esegui `hermes update` e controlla la documentazione di configurazione fornita con quella versione prima di modificare altre impostazioni. ## Passaggio 5: Diagnosticare la configurazione Esegui i controlli integrati di Hermes Agent: ```bash hermes doctor ``` Quindi avvia l'agente: ```bash hermes ``` Invia una piccola richiesta di test che non richieda strumenti esterni, ad esempio: ```text Rispondi con il nome del modello che stai utilizzando, poi riassumi quali strumenti sono disponibili in questa sessione Hermes. ``` Una risposta in streaming normale conferma che Hermes può autenticarsi, raggiungere l'endpoint di Atlas Cloud e chiamare il modello configurato. ## Problemi comuni di integrazione ### Errori di autenticazione Verifica che `OPENAI_API_KEY` esista in `~/.hermes/.env`, contenga la chiave Atlas Cloud senza virgolette o spazi extra e venga caricata dalla stessa installazione Hermes che stai eseguendo. Ruota la chiave se è stata esposta. ### Errori di modello sconosciuto Chiama di nuovo `https://api.atlascloud.ai/v1/models` e copia l'esatto ID live. Non rimuovere un prefisso del provider né abbreviare l'identificatore a meno che la risposta API stessa non utilizzi la forma più breve. ### Hermes chiama il provider sbagliato Conferma che la configurazione attiva contenga entrambi: ```yaml provider: "custom" base_url: "https://api.atlascloud.ai/v1" ``` Selezionare un provider integrato può instradare la richiesta all'endpoint di quel provider invece che ad Atlas Cloud. ### La configurazione corrisponde a un vecchio tutorial ma fallisce Hermes Agent si evolve rapidamente. Confronta il tuo file con il [riferimento di configurazione ufficiale corrente](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) e usa `hermes config get` per ispezionare il profilo attivo. In particolare, verifica se la tua versione prevede la struttura `model:` corrente. ## Come cambiare modelli senza ricostruire l'integrazione Una volta configurato Atlas Cloud come provider personalizzato, cambiare modello richiede solo un nuovo ID dal [catalogo modelli live](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=integrate-hermes-agent-atlascloud&sort=new): 1. Interroga `/v1/models`. 2. Aggiorna `model.default` in `~/.hermes/config.yaml`. 3. Esegui `hermes doctor`. 4. Avvia una nuova conversazione di test. L'endpoint e la gestione delle credenziali rimangono invariati. Questo è il valore pratico di un'API unificata per un agente: la valutazione del modello diventa una modifica della configurazione, non una nuova integrazione SDK. ## Quando questa configurazione è adatta L'integrazione con Atlas Cloud è particolarmente indicata quando: * Desideri che Hermes Agent acceda a più famiglie di modelli tramite un unico account. * Prevedi di confrontare o sostituire il modello principale nel tempo. * Desideri un endpoint compatibile con OpenAI invece di codice client specifico del provider. * In futuro, le competenze di Hermes potrebbero aver bisogno di accedere a modelli di immagini o video dalla stessa piattaforma. Un'integrazione diretta con un provider di modelli potrebbe essere più semplice se l'agente utilizzerà permanentemente un unico provider e non hai bisogno del catalogo modelli più ampio di Atlas Cloud. La scelta giusta dipende dal fatto che la flessibilità e l'accesso centralizzato siano più importanti rispetto all'avere la configurazione più breve possibile con un singolo provider. ## Lista di controllo finale Prima di lasciare Hermes Agent in esecuzione senza supervisione, verifica tutti e cinque i punti: - La chiave Atlas Cloud è archiviata al di fuori del controllo versione. - `provider` è impostato su `custom`. - `base_url` è esattamente `https://api.atlascloud.ai/v1`. - `model.default` corrisponde a un ID dell'endpoint modelli live. - `hermes doctor` e una semplice conversazione hanno entrambi successo. Con questi controlli completati, Hermes Agent è integrato con Atlas Cloud. Ora puoi valutare diversi modelli linguistici dietro lo stesso agente senza modificare i suoi strumenti, la memoria, le competenze o l'interfaccia utente. ## FAQ ### Hermes Agent dispone di un provider Atlas Cloud integrato? Non è necessario un provider dedicato di Atlas Cloud. Hermes Agent può connettersi tramite il suo provider personalizzato compatibile con OpenAI utilizzando l'URL di base e la chiave API di Atlas Cloud. ### Qual è l'URL di base di Atlas Cloud per Hermes Agent? Utilizza https://api.atlascloud.ai/v1 come URL base compatibile con OpenAI. ### Dove dovrei conservare la chiave API di Atlas Cloud? Conservalo in ~/.hermes/.env come OPENAI_API_KEY e tieni la chiave reale fuori dai file di configurazione, screenshot e controllo versione. ### Quale modello di Atlas Cloud dovrebbe usare Hermes Agent? Interroga https://api.atlascloud.ai/v1/models e scegli un modello di testo attuale che soddisfi i tuoi requisiti di utilizzo degli strumenti, ragionamento, contesto, latenza e costo. ### Come posso verificare l'integrazione? Esegui hermes doctor, avvia Hermes con il comando hermes e invia un piccolo prompt di test. Errori di autenticazione o di modello sconosciuto di solito indicano la chiave API, l'URL di base o l'ID del modello.