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. Ne vale la pena se decidi l'architettura del prodotto, se stai per acquistare una soluzione e vuoi valutarne il fondo, o se ti piace sapere cosa sta succedendo dietro la conversazione.

TL;DR: ogni turno passa attraverso 6 fasi — ingest, risoluzione del contesto, selezione delle skills, decisione della prossima azione, esecuzione con guard-rails, persistenza della memoria. L'intero ciclo viene eseguito in <2 secondi sull'edge di Cloudflare, senza server fisso.

---

Perché l'architettura è importante

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

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

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

---

Il ciclo di un turno (6 fasi)

Immagina che il cliente abbia appena inviato il messaggio "voglio prenotare per sabato mattina". Cosa succede tra il "received" e la risposta dell'agente?

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

Il messaggio di WhatsApp arriva tramite webhook di Meta direttamente in un Cloudflare Worker nel punto di presenza (PoP) geograficamente più vicino. 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 WABA).
2. Identifica il tenant tramite il numero di telefono del ricevitore (multi-tenant per to_number).
3. Normalizza il payload — l'audio diventa trascrizione, l'immagine diventa descrizione, la posizione diventa {lat,lng}, il testo rimane com'è.

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

Fase 2 — Risoluzione del contesto (D1 + KV, ~80ms)

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

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

Tutti provengono da 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.

Fase 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 (pianificazione).
• Skills consentite per questa fase della conversazione (non tutte le skills sono disponibili sempre).
• Skills che questo tenant ha abilitato (calendar appare solo se il tenant ha integrato).

Alla fine hai un piccolo sottoinsieme 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.

Fase 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 nella fase 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" }
}

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

La skill non viene eseguita nel modello. Viene eseguita in un 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 questo che passa alla chiamata successiva. Se la skill fallisce, il modello sa che è fallita. 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), la pipeline forza tool call — non lascia che il modello risponda dalla propria "conoscenza". Questo elimina la classe di allucinazione più comune negli agenti commerciali.

Fase 6 — Risposta e persistenza (~50ms)

Con il risultato della skill in mano, il modello effettua la seconda chiamata — ora per formare la risposta finale per il cliente. Es:

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

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 nuovo fatto (es: "il cliente preferisce sabato").
4. Emette un evento di osservabilità (metrica di latenza, costo dei token, tasso di escalation).

Tutto questo viene eseguito 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 alluci in produzione perde rapidamente la fiducia. 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 all'umano. Quando nessuna skill copre la domanda, l'agente dice "lascia che verifichi con il team" e apre un ticket — non tira a indovinare.

Negli audit che abbiamo condotto negli ultimi 6 mesi (conversazioni reali riviste manualmente), il tasso di allucinazione fattuale è rimasto sotto lo 0,3% dei turni — e quasi tutti i casi sono stati dovuti alla configurazione (il tenant ha dimenticato di abilitare una skill rilevante), non a un errore del modello.

---

Il costo per conversazione

L'architettura buona è invisibile finché non guardi la fattura. Dato che ogni turno fa 1-2 chiamate LLM + lookup in D1, il costo tipico per conversazione completa (10-15 turni) è di: