A2A tra due macchine: facciamo lavorare insieme due Hermes su computer diversi

Un Hermes su un computer non ce la fa più e vuole che un altro Hermes su un’altra macchina gli dia una mano: è esattamente questo lo scopo di A2A. Ma quali sono le insidie nella configurazione? Utenti reali le hanno già incontrate al posto tuo.

Quando serve davvero avere due macchine

Prima di tutto, chiarisci una cosa: ti servono davvero due computer, o vuoi solo far collaborare due agenti?

Se i due agenti vivono sulla stessa macchina, bastano delega o una bacheca condivisa — è come nello stesso ufficio: basta alzare la voce e chiamare il collega alla scrivania accanto, non serve mica telefonare. A2A è pensato per scenari “cross-macchina / cross-processo / cross-framework”: il tuo desktop e il server eseguono ciascuno un Hermes, con le proprie memorie, i propri strumenti e le proprie credenziali di accesso. Solo in questo caso ti serve il ponte di A2A.

Passi per iniziare

Passo 1: attiva la piattaforma A2A su entrambe le macchine. Durante l’installazione di Hermes scegli A2A, oppure modifica il file di configurazione impostando gateway.platforms.a2a.enabled su true. La porta predefinita è la 9900. Questo passaggio equivale a installare su ogni computer una porta d’ingresso con controllo accessi.

Passo 2: configura il token (la chiave del controllo accessi). Sul server imposta A2A_PEER_TOKENS o A2A_BEARER_TOKEN. Se stai solo facendo test in locale, puoi anche non impostare il token, ma in quel caso la porta sarà aperta solo per 127.0.0.1 — come se il badge fosse valido solo per chi abita nello stesso stabile.

Passo 3: esponi l’indirizzo. Per comunicare tra macchine diverse devi impostare A2A_HOST, ad esempio 0.0.0.0 o l’IP della rete locale. Questo passaggio sposta la porta da “corridoio interno” a “vetrina sulla strada”, così l’altro computer può trovarti.

Passo 4: abbina i peer. Sul client configura a2a_agents, oppure usa direttamente a2a_discover("http://indirizzo-server:9900") per vedere l’Agent Card dell’altro — è come scambiarsi i biglietti da visita: prima verifichi chi è e che cosa sa fare.

Passo 5: verifica. Abilita il toolset a2a e usa a2a_call per inviare un task semplice come prova. Attenzione ai timeout: il client ha un default di 330 secondi, la finestra di risposta del server è di 300 secondi. Per i task lunghi devi aumentare questi valori, altrimenti il lavoro viene interrotto a metà per timeout. Al termine, controlla il log di audit in ~/.hermes/a2a_audit.jsonl.

Caso reale 1: come si presenta una configurazione riuscita

La documentazione ufficiale descrive uno scenario ideale: il tuo Hermes sul desktop affida un task all’Hermes sul server — il server ha più potenza di calcolo, una rete più stabile e un database più completo. Viceversa, l’Hermes sul server può affidare al desktop compiti come “controlla un file locale”. Ciascuno ha le proprie memorie e i propri strumenti, ognuno fa il proprio lavoro, si scoprono le reciproche capacità tramite l’Agent Card, le conversazioni sono indicizzate per contextId e supportano più turni.

È come due reparti della stessa azienda: il reparto marketing (il desktop) ha bisogno di un report di analisi dati, manda una mail al reparto dati (il server), il reparto dati lo prepara e lo rispedisce. Ognuno archivia i propri documenti, senza interferenze.

Caso reale 2: una configurazione fallita

Nella community c’è un caso reale (#82910): un utente ha configurato due nodi su due macOS — un gateway rivolto agli utenti + un worker. Sembrava simile al caso di successo qui sopra, ma il risultato è stato un disastro, e alla fine il team ha dismesso l’intera configurazione.

Il problema era che i ruoli di “coordinatore” e “worker” non erano stati definiti chiaramente. L’agente padre (il coordinatore) accumulava troppo nella propria sessione: ogni operazione del worker, ogni risultato intermedio, ogni passaggio del ragionamento rifluiva nella sessione padre, causando espansione del contesto — l’agente padre veniva sommerso da un’enorme quantità di informazioni e diventava sempre più lento. La trascrizione tra agenti appesantiva le prestazioni complessive, e i task complessi innescavano loop di recupero, sprofondando sempre di più.

La lezione è chiara: la collaborazione A2A tra macchine richiede prima di tutto una progettazione chiara dei confini di responsabilità — chi coordina, chi esegue, a chi appartiene quale memoria. Non accumulare tutto nella sessione padre: il worker deve avere il proprio “taccuino personale”.

Checklist per evitare le trappole nella configurazione

Collasso dell’identità dietro il reverse proxy (#80534/#80779): se usi nginx, Ingress K8s o un CDN come reverse proxy, tutti i peer condividono lo stesso bearer token e le identità collassano tutte nell’indirizzo del proxy. La soluzione è far sì che il proxy inoltri X-Forwarded-For e dedurre l’identità reale dopo il proxy affidabile. È come quando il portiere del palazzo ritira i pacchi per conto tuo: deve scrivere sul pacco il vero destinatario, altrimenti si accumulano tutti in portineria.

Rifiuto del routing con più profili di configurazione (#80884/#80956): se usi multiplex_profiles per eseguire più configurazioni, i messaggi A2A in entrata instradati verso un profilo secondario possono essere rifiutati dal layer di autorizzazione del gateway. La soluzione è catturare il contesto di sicurezza dell’adattatore immutabile all’avvio, preservando per ogni profilo le proprie policy di autenticazione, trust, binding e Agent Card. Ogni porta deve avere le proprie regole di accesso, non si può condividere un’unica policy.

Impostazioni di timeout: default di 330 secondi sul client contro 300 sul server: per i task lunghi ricordati di aumentarli. Altrimenti è come una telefonata interurbana: ti staccano la linea prima che tu abbia finito di parlare.

Modalità worker con output limitato (#82503): è la ricetta ufficiale contro l’espansione del contesto. Le route A2A servite non-root possono eseguire sottoprocessi configurati o worker RPC versionati, con output limitato, terminazione dell’albero dei processi, cancellazione e terminazione exactly-once — il worker finisce il lavoro e si ferma, senza riversare tutto il processo nella sessione padre.

Cosa significa per te

La configurazione A2A su due macchine non è semplice come “collegare due computer”. È più come aprire una filiale: vetrina (Agent Card), controllo accessi (token), divisione dei compiti (chi coordina e chi esegue), magazzino (memorie separate) — tutto va pensato per bene. Una configurazione riuscita fa emergere i punti di forza di entrambe le macchine; una fallita sommerge il coordinatore di informazioni.

Ricorda tre regole: prima definisci i confini di responsabilità, poi pensa ai dettagli tecnici; con un reverse proxy gestisci il problema dell’identità; per i task lunghi aumenta i timeout, per quelli complessi usa worker con output limitato. Se fai tutto questo, i due Hermes su computer diversi potranno davvero diventare buoni colleghi, e non compagni di squadra che si trascinano a vicenda.