Come eseguire un agente Claude Agent SDK su WhatsApp (con MonoChat)

Claude Agent SDK è l’agent harness di Anthropic: lo stesso ciclo di ragionamento, uso degli strumenti e autoverifica che alimenta Claude Code, confezionato perché gli sviluppatori possano creare i propri agenti. Per eseguirne uno su WhatsApp servono altre tre cose attorno: un collegamento alla piattaforma WhatsApp Business, un modo per dare all’agente gli strumenti della tua azienda e un percorso sicuro verso una persona quando l’agente deve fermarsi. Con Agent Harness di MonoChat, aggiungi Claude Agent SDK come Harness IA, inserisci un nodo Agente IA in un flusso, colleghi il tuo numero WhatsApp e fai la prova. Nessun server da gestire.

Questa guida spiega cosa porta Claude Agent SDK nelle conversazioni con i clienti, come funziona la configurazione in MonoChat e cosa curare prima che i clienti inizino a scrivere.

Cos’è Claude Agent SDK (e perché è adatto all’assistenza)

Gran parte dell’IA su WhatsApp oggi è una singola chiamata a un modello: arriva un messaggio, il modello scrive una risposta, fine. Va bene per “Qual è il vostro orario di apertura?”. Non funziona per “Il mio ordine non è arrivato e venerdì sono in viaggio.”

Un harness esegue il modello in un ciclo. Il modello decide cosa fare dopo, l’harness esegue quel passaggio (cercare qualcosa, chiamare uno strumento, leggere un file), restituisce il risultato e ripete finché il compito è concluso o serve una persona. Claude Agent SDK è la versione di Anthropic di questo ciclo. È alla base di Claude Code e include gli elementi su cui gli sviluppatori contano lì: uso degli strumenti, supporto MCP, sotto-agenti, gestione del contesto per le sessioni lunghe e controlli dei permessi.

Per la messaggistica con i clienti, quel ciclo è ciò che trasforma una risposta in una soluzione:

• Verifica prima di promettere. Scorte, stato della consegna, slot degli appuntamenti o una regola di rimborso vengono cercati al momento della risposta invece di essere indovinati.
• Segue un caso in più passaggi. Trova l’ordine, controlla il corriere, vede che il pacco è bloccato, propone una sostituzione, il tutto in una sola conversazione.
• Sa quando fermarsi. Un buon harness passa il caso a una persona invece di improvvisare quando arriva al limite di ciò che può fare.

Se vuoi approfondire la differenza tra harness e semplice inferenza, leggi cos’è un agent harness e perché l’assistenza su WhatsApp ne ha bisogno.

Tre modi per usare gli agenti Claude in MonoChat

MonoChat supporta tre strade verso un agente basato su Claude. Tutte e tre usano lo stesso nodo Agente IA, gli stessi canali e lo stesso passaggio a un operatore.

Opzione	Dove viene eseguito	Cosa ti serve
Claude Agent SDK	L’agent runner di MonoChat; ogni esecuzione è un processo agente isolato in stile Claude Code	Niente di extra; i tuoi modelli IA tramite il gateway di MonoChat
Claude Managed Agents	Il cloud di Anthropic	La tua chiave API Anthropic
Personalizzato (il tuo servizio Claude Agent SDK)	Il tuo server	Un URL endpoint e un segreto condiviso

Per la maggior parte dei team la prima opzione è il punto di partenza giusto: ottieni l’harness Claude Agent SDK senza distribuire né mantenere nulla. Scegli Claude Managed Agents se già lavori con gli agenti ospitati di Anthropic e vuoi tenerli lì. Scegli Personalizzato se i tuoi sviluppatori hanno creato e testato un proprio agente con l’SDK e vogliono continuare a eseguirlo sulla propria infrastruttura; la nostra guida per collegare il tuo agente IA a WhatsApp copre questo percorso.

Passo dopo passo: un agente Claude Agent SDK su WhatsApp

1. Aggiungi un Harness IA

In MonoChat, un Harness IA è una definizione di servizio che aggiungi una volta e riutilizzi. Aggiungine uno e scegli Claude Agent SDK come provider. Per il provider in sé non c’è altro da configurare: gira sull’agent runner di MonoChat e raggiunge i tuoi modelli IA tramite il gateway di MonoChat.

2. Aggiungi un nodo Agente IA a un flusso

Apri il flusso che gestisce le conversazioni in arrivo, oppure creane uno nuovo, e aggiungi un nodo Agente IA. Seleziona l’harness che hai appena creato. È qui che l’agente riceve il suo compito: scrivi istruzioni che descrivano chi serve, cosa può fare e quando deve passare la mano.

3. Scegli i modelli principale, di fallback e veloce

Ogni nodo Agente IA ha tre ruoli dei modelli:

• Modello principale: ragiona, decide e scrive le risposte.
• Modello di fallback: subentra dopo un limite soft o quando il modello principale fallisce, così il cliente riceve comunque una risposta.
• Modello veloce: gestisce il lavoro in background.

Imposta anche un limite di budget per esecuzione. Una conversazione con un cliente raramente richiede una lunga catena di passaggi, e un budget impedisce che un caso insolito diventi costoso. Il nostro articolo su perché il tuo agente a contatto con i clienti ha bisogno di un modello di fallback spiega come scegliere la coppia.

4. Dai gli strumenti all’agente

Un agente senza strumenti può solo parlare. In MonoChat l’agente può usare:

• Gli strumenti di funzione IA per richiamare le tue API con input strutturati, ad esempio “ottieni stato ordine” o “crea un reso”.
• I server MCP per portare strumenti da qualsiasi sistema compatibile con MCP.
• La base di conoscenza IA per risposte fondate sulle tue policy e sui tuoi documenti.
• Le funzioni personalizzate per la logica di business che gira all’interno della conversazione.

Inizia con due o tre strumenti che coprano le richieste più comuni. Ogni strumento che aggiungi è una cosa in più che l’agente può fare, e una cosa in più da testare.

5. Collega WhatsApp e gli altri canali

Collega a MonoChat il tuo numero WhatsApp Business, se non l’hai già fatto (MonoChat è un Meta Business Partner ufficiale e usa la piattaforma ufficiale WhatsApp Business). Poiché l’agente vive in un flusso, puoi collegare lo stesso flusso a Instagram, Messenger, TikTok, Telegram, chat web, SMS e voce senza ricostruire nulla.

6. Testa, poi vai online

Invia all’agente i messaggi che i tuoi clienti mandano davvero: brevi, con errori di battitura, in più di una lingua, con tre domande in un solo messaggio. Verifica che usi lo strumento giusto, rispetti le tue regole e passi la mano al momento giusto. Poi attiva il flusso per il traffico reale.

Scrivere le istruzioni per un agente WhatsApp

Claude Agent SDK è nato nel mondo della programmazione, dove le risposte lunghe e dettagliate sono benvenute. WhatsApp è l’opposto. Alcune regole fanno una grande differenza:

• Mantieni le risposte brevi. Due o tre frasi per messaggio, una domanda alla volta. I clienti leggono sul telefono.
• Conferma prima di agire. “Posso annullare l’ordine 4821 e rimborsare €39. Procedo?” prima di qualsiasi azione che costi denaro o non sia reversibile.
• Indica esplicitamente la regola di passaggio. Ad esempio: “Passa a una persona per reclami sul personale, minacce legali, rimborsi superiori a €100 o quando il cliente chiede un operatore.”
• Resta nell’ambito della tua attività. Dal 15 gennaio 2026 i termini di WhatsApp escludono dalla piattaforma gli assistenti IA generici. Un agente che serve i tuoi clienti va bene; uno che scrive saggi su qualsiasi argomento no. La nostra guida alla policy WhatsApp sui chatbot IA spiega la regola.
• Rispetta la finestra di 24 ore. Le risposte libere sono consentite entro 24 ore dall’ultimo messaggio del cliente. Dopo, un messaggio richiede un template approvato.

Passaggio a un operatore: la parte che decide la fiducia

I clienti perdonano un agente che dice “Ti passo un collega.” Non perdonano uno che gira in tondo. In MonoChat l’agente passa la conversazione al tuo team nell’inbox condivisa con tutta la cronologia: cosa ha chiesto il cliente, cosa ha cercato l’agente e cosa ha già provato. La persona che la prende in carico non deve chiedere al cliente di ricominciare da capo.

Pianifica le regole di passaggio prima di pianificare gli strumenti. Decidi quali casi l’agente non deve mai gestire da solo, chi li riceve e cosa dice l’agente al cliente nel frattempo.

Costi e controllo

Con un agente ci sono due voci di costo oltre al tuo piano MonoChat: l’uso dei modelli IA e le tariffe WhatsApp di Meta. Dal 1° ottobre 2026 Meta addebita le risposte di assistenza dopo le prime 1.000 per numero aziendale ogni mese; la nostra guida ai prezzi delle API WhatsApp ne illustra i dettagli.

Sul lato IA, MonoChat non aggiunge alcun ricarico quando usi le chiavi del tuo provider. Un limite di budget per esecuzione, un modello di fallback sensato e un modello veloce per il lavoro in background mantengono l’utilizzo prevedibile al crescere del volume.

Quando scegliere un altro harness

Claude Agent SDK è un’ottima scelta predefinita per gli agenti che devono ragionare in più passaggi. Ma Agent Harness è pensato perché tu non resti vincolato. Se il tuo team lavora già con OpenAI Agents SDK, Pi, un agente OpenAI o Anthropic ospitato o un proprio framework, puoi aggiungere un altro Harness IA e spostare il nodo Agente IA, senza toccare canali, strumenti o passaggio a un operatore. Scopri tutte le opzioni nella pagina Agent Harness.