Porta il tuo agente IA su WhatsApp: collega qualsiasi framework (LangGraph, ADK, personalizzato) con un endpoint webhook

Puoi collegare quasi qualsiasi agente IA a WhatsApp senza riscriverlo. Esegui il tuo agente, creato con LangGraph, Google ADK, CrewAI o con il tuo codice, dietro un endpoint HTTPS, poi aggiungilo in MonoChat come Harness IA con il provider Personalizzato: un URL endpoint e un segreto condiviso. Inserisci un nodo Agente IA in un flusso, collega il tuo numero WhatsApp e il tuo agente risponde ai clienti su WhatsApp e su ogni altro canale collegato a MonoChat, con un’inbox condivisa e il passaggio a un operatore attorno.

Questa guida è per i team che hanno già un agente, o vogliono il pieno controllo su come funziona. Spiega quando ha senso portare il proprio agente, di cosa è responsabile il tuo endpoint, la configurazione in MonoChat e i dettagli che contano in produzione.

Perché portare il proprio agente?

La maggior parte delle piattaforme di messaggistica con i clienti include un solo agente IA integrato. È comodo, finché:

• Il tuo agente è già stato creato. I tuoi sviluppatori hanno speso mesi su un grafo LangGraph o su una configurazione multi-agente ADK, con valutazioni e test. Ricostruirlo nel bot builder di un fornitore significa buttare via quel lavoro.
• Ti serve la tua logica. Regole di prezzo, controlli di idoneità, passaggi di conformità o sistemi interni che solo il tuo codice può raggiungere.
• Vuoi scegliere il framework. I framework cambiano in fretta. Oggi è LangGraph; l’anno prossimo potrebbe essere qualcos’altro. I tuoi canali e la tua inbox non dovrebbero cambiare con lui.
• I dati devono restare con te. Alcune organizzazioni vogliono che il ragionamento e le chiamate agli strumenti dell’agente girino sulla propria infrastruttura.

Agent Harness di MonoChat è pensato per questo: porta il tuo framework di agenti e mantieni tutto ciò che c’è attorno, i canali, l’inbox, le persone, in un unico posto.

Come funziona l’harness Personalizzato

Pensalo come una divisione del lavoro.

MonoChat gestisce il livello della conversazione:

• Le connessioni ufficiali a WhatsApp, Instagram, Messenger, TikTok, Telegram, chat web, SMS e voce (MonoChat è un Meta Business Partner ufficiale).
• Il flusso che decide quando richiamare l’agente, tramite il nodo Agente IA.
• L’inbox condivisa del team, dove una persona può subentrare con tutta la cronologia.

Il tuo endpoint gestisce l’agente:

• Ricevere la conversazione da MonoChat.
• Eseguire il tuo agente: il suo ragionamento, i suoi strumenti, la sua memoria.
• Restituire la risposta dell’agente.

Tra i due c’è un segreto condiviso, un valore che entrambe le parti conoscono, così il tuo endpoint può verificare che una richiesta provenga dal tuo account MonoChat. MonoChat definisce il formato esatto di richiesta e risposta che il tuo endpoint implementa; se non lo hai ancora, parla con noi e lo condivideremo con i tuoi sviluppatori.

Cosa dovrebbe fare il tuo endpoint

Qualunque framework tu usi, un endpoint di agente pronto per la produzione ha alcuni compiti.

Verifica ogni richiesta

Controlla il segreto condiviso a ogni chiamata e rifiuta tutto ciò che non corrisponde. Conserva il segreto nel tuo gestore di segreti o nelle variabili d’ambiente, non nel codice, e ruotalo se viene mai esposto.

Tieni separata ogni conversazione

I clienti scrivono in parallelo. Assicurati che lo stato, la memoria e gli eventuali file di lavoro del tuo agente siano limitati a una sola conversazione, così i dati di un cliente non finiscono mai nella risposta di un altro.

Rispondi con messaggi a misura di chat

Gli agenti pensati per le app web tendono a scrivere risposte lunghe e formattate. WhatsApp si legge sul telefono. Chiedi al tuo agente messaggi brevi, una domanda alla volta, e tieni il Markdown pesante fuori dalle risposte.

Fallisci in modo evidente, non in silenzio

Se uno strumento va in timeout o il tuo provider di modelli restituisce un errore, restituisci un errore chiaro invece di una risposta a metà. Un errore prevedibile permette al flusso di fare la cosa giusta, ad esempio passare la conversazione a una persona.

Sii rapido

I clienti si aspettano una risposta in pochi secondi. Tieni fuori dal percorso della risposta il lavoro di lunga durata, dove possibile, e rendi i tuoi strumenti veloci o asincroni.

Passo dopo passo in MonoChat

1. Distribuisci il tuo agente dietro HTTPS

Ospita il tuo agente LangGraph, ADK, CrewAI o personalizzato sul tuo server o sul tuo cloud, raggiungibile via HTTPS. Implementa il formato di richiesta e risposta di MonoChat e la verifica del segreto condiviso.

2. Aggiungi un Harness IA con il provider Personalizzato

In MonoChat aggiungi un Harness IA, scegli Personalizzato e inserisci l’URL endpoint e il segreto condiviso. Aggiungi l’harness una sola volta e puoi usarlo in quanti flussi vuoi.

3. Aggiungi un nodo Agente IA a un flusso

Nel flusso che riceve le conversazioni in arrivo, aggiungi un nodo Agente IA e seleziona il tuo harness personalizzato. Usa il flusso attorno a lui per ciò che i flussi fanno meglio: saluto, instradamento per lingua o argomento, orari di lavoro e percorso verso una persona.

4. Imposta un budget per esecuzione

Ogni nodo Agente IA supporta limiti di budget per esecuzione. Usali come rete di sicurezza accanto ai limiti che già applichi nel tuo codice.

5. Collega WhatsApp e gli altri canali

Collega il tuo numero WhatsApp Business, poi collega lo stesso flusso agli altri canali che usi. Non c’è lavoro di integrazione aggiuntivo per canale: il tuo endpoint vede conversazioni, non API dei canali.

6. Testa, poi vai online

Riproduci nel flusso messaggi reali dei clienti. Controlla chiamate agli strumenti, tempi di risposta, tono e passaggio a un operatore. Segui con attenzione i primi giorni di traffico reale, poi amplia ciò che l’agente può fare.

Note sui framework

LangGraph. Un grafo di nodi e archi si adatta in modo naturale ai percorsi di assistenza (triage, ricerca, risoluzione, escalation). Racchiudi il grafo compilato in un piccolo servizio HTTP, carica lo stato della conversazione a ogni richiesta e restituisci il messaggio finale.

Google ADK. Gli alberi multi-agente di ADK, con un coordinatore e sotto-agenti specializzati, si adattano bene ai team di assistenza, vendite e fatturazione. Esponi l’agente radice tramite il tuo endpoint e lascia che ADK instradi al suo interno.

CrewAI. I crew di agenti basati su ruoli funzionano bene per compiti con passaggi di consegne chiari, come ricerca e poi risposta. Tieni i crew piccoli per la chat: ogni agente in più aggiunge latenza.

Il tuo codice. Un semplice ciclo con un’API di modello e poche funzioni spesso basta. Mantieni il controllo totale, e MonoChat ti dà i canali e l’inbox.

Passaggio a un operatore: decidilo nel flusso

Decidi nel flusso quali conversazioni vanno a una persona e quale team le riceve, e scrivi il tuo agente in modo che dica onestamente al cliente quando non può aiutare invece di tirare a indovinare. Il flusso passa poi la conversazione al team giusto nell’inbox condivisa con tutta la cronologia. Anche la Business Messaging Policy di WhatsApp si aspetta che le risposte automatiche offrano una via chiara verso una persona.

Mantieni anche il tuo agente nell’ambito della tua attività. Dal 15 gennaio 2026 WhatsApp esclude dalla piattaforma gli assistenti IA generici; gli agenti che servono i tuoi clienti vanno bene. La nostra guida alla policy WhatsApp sui chatbot IA spiega la regola.

Quando non creare il proprio

Un agente personalizzato è l’opzione più flessibile ed è anche quella che mantieni tu. Se parti da zero, un’opzione integrata ti mette online più in fretta, senza nulla da ospitare:

• L’harness integrato di MonoChat sui tuoi modelli IA di MonoChat.
• OpenAI Agents SDK, eseguito all’interno di MonoChat (guida).
• Claude Agent SDK o Pi, eseguiti sull’agent runner di MonoChat (guida a Claude).
• Agenti ospitati: OpenAI Agents API o Claude Managed Agents, con la tua chiave.

Poiché ogni opzione usa lo stesso nodo Agente IA, puoi iniziare con una e passare al tuo agente più avanti senza toccare i canali o il passaggio a un operatore. Confrontale nella pagina Agent Harness.