Come Funziona un Agente di IA Conversazionale Internamente

Come Funziona un Agente di IA Conversazionale Internamente (Architettura OpenClaw)

Come funziona un agente di IA conversazionale nella pratica, turno dopo turno? Questo post apre la scatola nera di OpenClaw: dal momento in cui il messaggio del cliente arriva su WhatsApp fino al testo che l'agente scrive in risposta. Sarà tecnico. Vale la pena se decidi l'architettura di prodotto, se stai per acquistare una soluzione e vuoi valutarne il fondo, o se ti piace sapere cosa succede dietro la conversazione.

TL;DR: ogni turno passa attraverso 6 stadi — ingest, risolvi contesto, seleziona skill, decidi prossima azione, esegui con guard-rail, persisti memoria. L'intero ciclo gira in <2 secondi sull'edge di Cloudflare, senza server fisso.

---

Perché l'architettura conta

Un agente conversazionale che sembra funzionare in una demo ma si rompe in produzione generalmente ha uno di questi 4 problemi:

1. Latenza alta — il cliente aspetta 8 secondi per la risposta, la conversazione muore.
2. Allucinazione non controllata — l'agente inventa prezzo, orario, policy.
3. Contesto perso — il cliente torna dopo 2 giorni e l'agente "dimentica" tutto.
4. Costo fuori controllo — ogni conversazione lunga riempie il prompt e paghi una fortuna in token.

Tutti e 4 sono scelte di architettura, non limitazioni del modello. OpenClaw è stato costruito per evitare tutti e 4 — e il modo per capirlo è osservare il ciclo di un turno.

---

Il ciclo di un turno (6 stadi)

Immagina che il cliente abbia appena inviato il messaggio "quero marcar pra sábado de manhã". Cosa succede tra il "received" e la risposta dell'agente?

Stadio 1 — Ingest (edge worker, <50ms)

Il messaggio di WhatsApp arriva via webhook di Meta direttamente su un Cloudflare Worker nel punto di presenza (PoP) più vicino geograficamente. In Brasile, questo significa San Paolo o Rio, latenza di rete < 20ms.

Il worker fa tre cose:

1. Valida la firma del webhook (HMAC contro il segreto della WABA).
2. Identifica il tenant dal numero di telefono del ricevente (multi-tenant per to_number).
3. Normalizza il payload — l'audio diventa trascrizione, l'immagine diventa descrizione, la posizione diventa {lat,lng}, il testo resta com'è.

Alla fine dello stadio 1 hai un oggetto {tenant_id, conversation_id, user_message} pronto per il passo successivo.

Stadio 2 — Risolvi contesto (D1 + KV, ~80ms)

L'agente ha bisogno di 3 pezzi di contesto prima di decidere:

• Storico recente della conversazione (ultimi N turni rilevanti).
• Memoria a lungo termine del cliente (preferenze, storico acquisti, annotazioni).
• Stato dell'agente (persona, skills abilitate, regole).

Tutti provengono dal D1 (SQLite distribuito di Cloudflare). D1 sostituisce Postgres/Mongo tradizionale — nessun server di database da mantenere, accesso in pochi ms dal worker, multi-tenant tramite tenant_id.

Punto chiave: noi non carichiamo l'intera conversazione nel prompt. Il Memory Manager v2 di OpenClaw (descritto nella nostra documentazione interna) seleziona solo i turni rilevanti per il turno attuale (ultimi N + N ad alta rilevanza semantica). Questo mantiene il costo dei token prevedibile anche in conversazioni di 100+ turni.

Stadio 3 — Selezione delle skills (policy engine, ~20ms)

Ogni agente ha un insieme di skills disponibili — funzioni che può invocare. Esempi: consultar_calendario, criar_evento, gerar_link_pagamento, consultar_pedido, chamar_humano.

Dato il messaggio "quero marcar pra sábado de manhã", il policy engine filtra:

• Skills compatibili con l'intenzione rilevata (prenotazione).
• Skills consentite per questa fase della conversazione (non tutte le skills sono disponibili in ogni momento).
• Skills che questo tenant ha abilitato (calendar appare solo se il tenant l'ha integrato).

Alla fine si ottiene un sottoinsieme ridotto di skills passato al modello — non le 50 possibili, solo le 4 che hanno senso qui. Questo riduce drasticamente la probabilità che il modello invochi la skill sbagliata.

Stadio 4 — Decisione (LLM call, 400-1200ms)

Ora entra in gioco il modello. OpenClaw effettua una singola chiamata a un LLM di frontiera (Anthropic Claude, OpenAI GPT, Google Gemini — configurabile per tenant) con:

• System prompt = persona dell'agente + regole + skills disponibili.
• History = turni selezionati nello stadio 2.
• User message = messaggio del turno attuale.

Il modello risponde con una di due cose:

• Risposta finale (testo diretto al cliente).
• Tool call (richiesta di eseguire una skill specifica con parametri).

Nell'esempio "quero marcar pra sábado de manhã", il modello tipicamente restituisce:

{
  "tool": "consultar_calendario",
  "args": { "date_range": "2026-04-19 06:00 to 12:00" }
}

Stadio 5 — Esecuzione con guard-rails (variabile, ~100-500ms)

La skill non viene eseguita nel modello. Viene eseguita nel nostro codice, che:

1. Valida i parametri (date_range ha il formato corretto? rientra nelle regole del tenant?).
2. Verifica i permessi (questo agente ha il diritto di consultare questo calendario?).
3. Esegue la chiamata (Google Calendar API in questo caso).
4. Restituisce il risultato strutturato al modello.

Perché è importante? Perché il modello non fabbrica mai il risultato. Se il calendario restituisce [10h, 11h], è esattamente quello che viene passato alla chiamata successiva. Se la skill fallisce, il modello sa che ha fallito. Zero rischio che l'agente "inventi" che c'è un orario alle 9h quando non c'è.

Per i casi che coinvolgono informazioni sensibili (prezzo, scadenza, nome del cliente), il pipeline forza tool call — non lascia che il modello risponda dalla propria "conoscenza". Questo elimina la classe di allucinazione più comune negli agenti commerciali.

Stadio 6 — Risposta e persistenza (~50ms)

Con il risultato della skill in mano, il modello effettua la seconda chiamata — questa volta per formulare la risposta finale al cliente. Es:

"Ho sabato alle 10h e 11h. Quale preferisce?"

Parallelamente, il worker:

1. Invia il messaggio di ritorno tramite l'API di WhatsApp.
2. Persiste il turno completo (user + assistant + tool calls + durata) nel D1.
3. Aggiorna la memoria a lungo termine se il turno ha prodotto un fatto nuovo (es: "il cliente preferisce sabato").
4. Emette un evento di osservabilità (metrica di latenza, costo dei token, tasso di escalation).

Tutto questo gira in parallelo. La persistenza non blocca l'invio del messaggio — il cliente non aspetta il D1.

---

Dove si trova la difesa contro l'allucinazione

Un agente che allucina in produzione perde fiducia rapidamente. OpenClaw ha 4 linee di difesa:

1. Source-of-truth forzata. I dati fattuali (prezzo, orario, nome) provengono sempre dalla skill, mai dal modello da solo.
2. Verifica doppia sui dati sensibili. L'appuntamento viene confermato con il cliente prima di essere persistito. Il pagamento viene confermato prima di concedere l'accesso.
3. Regole negative esplicite. La persona di ogni agente include "non inventare mai X, Y, Z" — il modello obbedisce.
4. Fallback verso l'umano. Quando nessuna skill copre la domanda, l'agente dice "lasciami verificare con il team" e apre un ticket — non tira a indovinare.

Nelle audit che abbiamo condotto negli ultimi 6 mesi (conversazioni reali revisionate manualmente), il tasso di allucinazione fattuale è rimasto sotto lo 0,3% dei turni — e quasi tutti i casi erano dovuti a configurazione (il tenant ha dimenticato di abilitare la skill pertinente), non a errori del modello.

---

Il costo per conversazione

Una buona architettura è invisibile finché non guardi la fattura. Dato che ogni turno effettua 1-2 chiamate LLM + lookup su D1, il costo tipico per conversazione completa (10-15 turni) si aggira su: