GUIDA COMPLETA a Hermes Agent: dai a Hermes un cervello aziendale per collaborare con il tuo team

Questo articolo è stato scritto da @chriskim_dev

Gli AI agent sono fantastici quando lavorano per una singola persona. Diventano molto più interessanti quando possono collaborare con l'intero team.

Questa guida è un tutorial passo-passo per sviluppatori per fare esattamente questo: costruire un "cervello aziendale" che collega @NousResearch Hermes Agent ai file condivisi, commenti, versioni e contesto su cui il tuo team già lavora in @Box. Alla fine, avrai un'implementazione funzionante in cui Hermes non è più solo un assistente personale, ma un compagno di squadra che svolge il lavoro partendo dalla stessa fonte di verità di tutti gli altri.

Per mantenere questo tutorial focalizzato, darò per scontato che tu abbia già una certa esperienza nella configurazione di Hermes Agent Gateway su un VPS in modo che il tuo agente sia disponibile 24/7. Per una guida dettagliata, consulta la documentazione per sviluppatori di Hermes. Useremo un Droplet di DigitalOcean per ospitare la nostra istanza di Hermes, ma lo stesso schema funziona con qualsiasi provider VPS.

Guarda prima la demo

Prima di costruirlo, guarda il flusso di lavoro in azione!

https://x.com/chriskim_dev/status/2066898496842846557

Il problema: gli AI agent sono ancora troppo isolati

Se lavori in un team di marketing, contenuti, prodotto o a contatto con i clienti, questa storia probabilmente ti suona familiare. Stai lavorando a un video aziendale per un prodotto. Qualcuno lascia cadere uno ZIP in un thread di Slack, un collega chiede quali risorse contiene, arrivano altre versioni (video_progetto_v2_FINALE.zip, finale_finale_revisto.mov, copia_lancio_v3.txt), i feedback si perdono e qualcuno modifica la versione sbagliata.

Poi un AI agent entra nel loop e peggiora le cose, lavorando con sicurezza dalla sua copia locale del progetto. Strumenti come Hermes sono potenti per la produttività individuale, ma i passaggi tra agente e umano e tra agente e agente si interrompono perché tutti, umani e macchine, lavorano da contesti diversi.

La soluzione: dai ai tuoi agenti lo stesso spazio di lavoro condiviso che il tuo team usa già, un'unica fonte di verità da cui tutti attingono. È qui che entra in gioco Box.

Cosa costruirai

Alla fine di questa guida, avrai:

• Hermes Agent in esecuzione su un VPS con Slack come gateway
• Box CLI installato sullo stesso server
• Un'app Box che utilizza l'autenticazione Client Credentials Grant (CCG)
• Un account di servizio Box dedicato per Hermes
• Una cartella di progetto condivisa che diventa lo spazio di lavoro per umani e agenti
• Un modello ripetibile per flussi di lavoro agenziali in cui Hermes può caricare, leggere, analizzare e organizzare il lavoro in Box

La scelta progettuale chiave qui è non autenticare Hermes nel Box CLI come tuo account utente Box personale. Invece, creiamo un'app Box usando Client Credentials Grant (CCG), che dà al tuo agente la propria identità di servizio in Box.

Cos'è un account di servizio?

Un account di servizio è un'identità dedicata per un'applicazione o automazione. Se Hermes usa il tuo account personale, può accedere a tutto ciò a cui puoi accedere tu, il che va bene per esperimenti locali, ma è il modello sbagliato per flussi di lavoro di team o a contatto con i clienti. Con un account di servizio, Hermes ottiene la propria identità Box e condividi solo le cartelle di cui ha bisogno. Questo ti dà un confine di sicurezza pulito: Hermes agisce come Hermes e vede solo ciò che hai condiviso con esso.

Un'app Box CCG è come creiamo quell'identità lato server. CCG consente alla tua app di autenticarsi senza un accesso utente interattivo. Crei un'app nella Console per Sviluppatori di Box, la autorizzi nella Console di Amministrazione e usi il suo client ID, client secret e enterprise ID per autenticarti dal tuo server. Imparerai come creare l'app qui sotto, ma per maggiori dettagli, leggi la documentazione Box su Client Credentials Grant.

Prerequisiti

Avrai bisogno di:

• Un account sviluppatore Box gratuito
• Un account DigitalOcean (o qualsiasi altro provider VPS)
• Un workspace Slack dove puoi creare e installare app
• Hermes Agent con un provider di modelli configurato
• Familiarità di base con il terminale

Prima di tutto, registrati per un account sviluppatore Box gratuito. Dopo la registrazione, verrai reindirizzato alla Console per Sviluppatori di Box, dove creerai l'app CCG che dà a Hermes la sua identità di servizio.

Passo 1: Crea un Droplet DigitalOcean

Per questo tutorial, useremo un Droplet DigitalOcean come VPS. DigitalOcean ha una guida completa per creare un Droplet.

Per una demo di sviluppo, un piccolo Droplet Ubuntu è sufficiente:

• Ubuntu 24.04
• 1 vCPU
• 2 GB RAM
• Autenticazione tramite chiave SSH
• Monitoraggio abilitato

Una volta creato il Droplet, collegati via SSH:

1ssh root@IL_TUO_IP_DROPLET

Aggiorna i pacchetti e installa le basi:

1apt update
2apt upgrade -y
3apt install -y curl git unzip jq build-essential nodejs npm

Passo 2: Installa Hermes Agent

Installa Hermes Agent sul droplet seguendo la documentazione ufficiale di Hermes.

Dopo l'installazione, verifica che funzioni:

1hermes --version

Poi esegui la configurazione:

1hermes setup

Scegli il provider di modelli AI che vuoi utilizzare e segui le istruzioni. Hermes supporta diversi provider di modelli, quindi non ne prescriverò uno (qualsiasi provider principale funziona). La parte importante è che Hermes funzioni correttamente prima di collegarlo a Slack e Box.

Verifica rapidamente che Hermes sia configurato correttamente:

1hermes

Poi invia "Ciao" per vedere se Hermes risponde. Una configurazione funzionante risponde nel terminale; se non ottieni risposta, esegui di nuovo hermes setup e conferma che la chiave del tuo provider di modelli sia configurata.

Passo 3: Crea l'app Slack e configura il Gateway Hermes

Hermes Gateway permette al tuo agente di funzionare all'interno di piattaforme di messaggistica come Slack. Configuriamo Slack come piattaforma di messaggistica per il nostro agente Hermes. Fai riferimento alla guida dettagliata per la configurazione di Slack nella documentazione per sviluppatori di Hermes. Alla fine, dovresti avere: un token bot Slack, un token app Slack, l'app Slack installata nel tuo workspace e il gateway configurato.

Nota: Poiché Hermes è in esecuzione su un VPS, installa Hermes Gateway come servizio di sistema quando richiesto. In questo modo si avvia all'accensione e rimane in esecuzione dopo aver chiuso il terminale.

Controlla il servizio con:

1systemctl status hermes-gateway

Comandi utili:

1systemctl restart hermes-gateway          # riavvia il gateway
2journalctl -u hermes-gateway -f            # visualizza in tempo reale i log del gateway
3journalctl -u hermes-gateway -n 100 --no-pager   # mostra le ultime 100 righe di log

Una volta che l'app Slack è installata e configurata come gateway Hermes, riavvia Hermes sul VPS:

1systemctl restart hermes-gateway

Testalo in Slack inviando un messaggio con @Hermes:

1@Hermes ciao

Passo 4: Installa il Box CLI

Ora che il tuo agente Hermes funziona su Slack, colleghiamolo a Box con Box CLI. Box CLI rende Box completamente headless e permette al tuo agente Hermes di eseguire tutte le operazioni Box come leggere file, creare/caricare file e gestire contenuti su Box tramite comandi CLI.

Installa il Box CLI sul VPS (usando il terminale da cui ti sei connesso remotamente al VPS):

1npm install --global @box/cli

Verifica:

1box --version

Ottimo! Box CLI è installato sul tuo VPS. Effettueremo l'accesso più avanti. Per maggiori informazioni, consulta la documentazione Box CLI.

Passo 5: Crea un'app Box CCG

Vai alla Console per Sviluppatori di Box e crea una nuova app usando Client Credentials Grant. Questa app è l'identità di servizio che agisce per conto del tuo agente Hermes.

Una volta creata, trova la barra laterale Dettagli App a destra e localizza queste credenziali:

• clientID
• clientSecret
• enterpriseID

Ora crea un file di configurazione sul tuo VPS:

1nano /root/box-ccg-config.json

Incolla:

1{
2  "boxAppSettings": {
3    "clientID": "IL_TUO_CLIENT_ID",
4    "clientSecret": "IL_TUO_CLIENT_SECRET"
5  },
6  "enterpriseID": "IL_TUO_ENTERPRISE_ID"
7}

Salva ed esci:

1Ctrl+O or Cmd+O
2Invio
3Ctrl+X or Cmd+X

Ora configuriamo l'ambiente Box CLI per usare la nostra app CCG per l'autenticazione. Questo permetterà a Hermes di accedere al Box CLI usando l'app CCG e non un account utente personale.

Aggiungi l'ambiente al Box CLI:

1box configure:environments:add /root/box-ccg-config.json --ccg-auth --name service

Impostalo come corrente:

1box configure:environments:set-current service

Verifica l'identità del servizio:

1box users:get

Dovresti vedere un utente di automazione, non il tuo utente personale. Potrebbe assomigliare a qualcosa come:

1Nome: my-app
2Login: [email protected]

Questa è l'identità che il tuo agente Hermes userà in Box. Ora, quando dici al tuo agente Hermes di eseguire qualsiasi operazione Box, Hermes sarà in grado di usare il Box CLI per farlo.

Passo 6: Condividi una cartella di progetto con l'account di servizio

Crea una cartella in Box per il tuo progetto, ad esempio, Progetto Video Lancio Prodotto.

Vai alla pagina dell'app CCG creata nella Console per Sviluppatori di Box e copia l'email dell'utente di automazione dalla barra laterale Dettagli App.

Ora condividi quella cartella con l'utente di automazione del passo precedente.

Questo è il confine di sicurezza chiave. Hermes non ha bisogno di accedere all'intero tuo account; ha bisogno solo di accedere a questa cartella di progetto.

Verifichiamo se la configurazione ad accesso limitato funziona! Chiedi al tuo agente Hermes su Slack:

1@Hermes Puoi controllare quali cartelle e file vedi al livello principale?

Se vedi solo la cartella di progetto che hai creato in precedenza, siamo pronti per partire!

Congratulazioni! Box è ora pronto per fungere da cervello aziendale per il tuo agente Hermes. Usa questa cartella come unica fonte di verità e lascia che Hermes la utilizzi come contesto per le attività che gli assegni.

Lascia che Hermes impari il Box CLI

Ecco una delle mie parti preferite di Hermes: il suo ciclo di auto-miglioramento. Non devi scrivere perfettamente a mano ogni comando Box CLI in anticipo. Invece, dai a Hermes un'attività e lascia che impari.

Ad esempio, su Slack:

1@Hermes usa il Box CLI per scoprire come sei autenticato, poi elenca i file nella cartella di progetto condivisa.

Poi prova:

1@Hermes crea una skill riutilizzabile per le operazioni comuni del Box CLI come elencare cartelle, caricare file, scaricare file e controllare l'account di servizio corrente.

Nel video demo, Hermes ha capito come lavorare efficientemente con il Box CLI e ha costruito la sua skill box-cli riutilizzabile. Non ho creato quella skill prima. Hermes ha imparato dall'ambiente e ha migliorato il suo comportamento futuro.

Puoi comunque guidarlo con una breve istruzione:

• Usa sempre l'ambiente di servizio Box CLI.
• Opera solo all'interno della cartella di progetto approvata.
• Chiedi prima di eliminare o sovrascrivere contenuti.
• Preserva la cronologia delle versioni quando possibile.
• Tratta Box come la fonte di verità duratura.

Chiedi a Hermes di usare il Box CLI, osserva dove ha difficoltà, correggilo e lascia che crei un flusso di lavoro migliore per la prossima volta.

Dove questo brilla davvero: modi reali in cui i team mettono al lavoro il cervello condiviso

La mia demo riguardava la collaborazione su un lancio video, ma una volta che Hermes e il tuo team condividono la stessa fonte di verità in Box, puoi usarla per qualsiasi lavoro in cui umani e agenti devono essere sulla stessa pagina. Ecco alcuni scenari per darti qualche spunto. Provali, poi inventa i tuoi!

Collaborazione su contenuti e marketing (il tuo lancio video, potenziato). Il tuo editor rilascia il taglio finale in Box, uno scrittore lascia un feedback come commento e Hermes lo recepisce senza che nessuno debba rispiegare il progetto:

1@Hermes il taglio V2 è approvato — genera didascalie, una descrizione per YouTube e 3 concept per le miniature, poi salvali nella cartella di lancio.

Un secondo agente sulla macchina di un collega può successivamente prelevare quella stessa cartella per programmare i post. Nessuno chiederà mai più "qual è il file finale?".

Coordinamento del lancio del prodotto. PM, design e marketing corrono tutti verso la stessa data. Invece di un documento di lancio che diventa obsoleto nel momento in cui viene scritto, lascia che Hermes lo assembli in tempo reale dallo spazio di lavoro condiviso:

1@Hermes leggi le specifiche, gli ultimi mockup e le note di QA nella cartella Lancio, poi abbozza una checklist go/no-go e un brief di lancio di una pagina.

Quando le specifiche cambiano, riesegui l'operazione — il cervello legge sempre la verità corrente, non la copia della settimana scorsa.

Lavoro di ingegneria. Punta Hermes verso gli esport del repository, i documenti di design e le note sugli incidenti che risiedono in Box, in modo che l'intero team lavori da un unico contesto:

1@Hermes riassumi i problemi aperti e il documento di design nella cartella Auth-Service, poi abbozza le note di rilascio per il deploy v3.2.

Stai inserendo un nuovo ingegnere? Lui (e il suo agente) leggono la stessa cartella del team senior — nessuna conoscenza tribale intrappolata nei DM.

Progetti personali secondari. Anche da solo, la configurazione ripaga — il tuo "team" sei solo tu tra un laptop, un telefono e un paio di agenti:

1@Hermes ecco i miei registri di allenamento e le ricette per il mese — creami un piano alimentare e di allenamento e inseriscilo nella mia cartella Progetti Secondari.

Inizia l'idea sul telefono, finiscila sul laptop e lascia che un agente diverso la riprenda domani.

Lavoro legale e contrattuale. Il settore legale vive e muore per il controllo di versione, quindi una singola fonte di verità è un dono qui:

1@Hermes confronta la V2 con le modifiche evidenziate del MSA del fornitore con la V1, elenca ogni clausola modificata e segnala qualsiasi cosa tocchi responsabilità o risoluzione.

Il consulente commenta direttamente sul file in Box; Hermes (e l'agente di qualsiasi revisore) preleva sempre l'ultima versione firmata, non un allegato email smarrito.

Il filo conduttore di tutti questi scenari è quello verso cui hai lavorato:

Team diversi. Agenti diversi. Interfacce diverse. Lo stesso spazio di lavoro condiviso.

Scegli lo scenario più vicino al tuo mondo e provalo oggi. Poi dai sfogo alla creatività! Il caso d'uso migliore è quasi sempre quello che scopri tu una volta che l'attrito è sparito. Divertiti e condividi ciò che hai costruito nei commenti!