Come funziona un agente di IA conversazionale per dentro

Come Funziona un Agente di IA Conversazionale per Dentro (Arquitetura OpenClaw)

Come funziona un agente di IA conversazionale nella pratica, turno a turno? Questo post apre la caixa preta del OpenClaw: dal momento che la messaggistica del cliente arriva su WhatsApp fino al testo che l'agente scrive di ritorno. Vai a essere tecnico. Vale la pena se decidi di arkitettura di prodotto, se vai comprare una soluzione e vuoi valutare il fondo, o se ti piace sapere cosa sta succedendo dietro la conversazione.

TL;DR: ogni turno passa per 6 fasi — ingest, risolve contesto, seleziona abilità, decide prossima azione, esegue con guard-rails, persiste memoria. Tutto il ciclo gira in <secondi sull'edge della Cloudflare, senza server fisso.

---

Perché l'arquitettura importa

Agente conversazionale che sembra funzionare in un demo ma si rompe in produzione generalmente ha uno di questi 4 problemi:

1. Latenza alta — cliente aspetta 8 secondi per risposta, conversazione muore.
2. Allucinazione non controllata — agente inventa prezzo, orario, politica.
3. Contesto perso — cliente torna dopo 2 giorni e agente "dimentica" tutto.
4. Custo discontrollato — ogni conversazione lunga riempie il prompt e tu paghi una fortuna in token.

I 4 sono scelte di arkitettura, non limitazioni del modello. L'OpenClaw è stato costruito per evitare i 4 — e il cammino per capire è guardare il ciclo di un turno.

---

Il ciclo di un turno (6 fasi)

Immagina che il cliente ha appena mandato la messaggistica "voglio prenotare per sabato mattina". Cosa succede tra il "received" e la risposta dell'agente?

Fase 1 — Ingest (edge worker, <ms)

La messaggistica di WhatsApp arriva via webhook della Meta direttamente in un Cloudflare Worker nel punto di presenza (PoP) più vicino geograficamente. In Italia, questo significa Roma o Milano, latenza di rete <0ms.

Il worker fa tre cose:

1. Valuta la firma del webhook (HMAC contro segreto della WABA).
2. Identifica il tenant per il numero di telefono del destinatario (multi-tenant per to_number).
3. Normalizza il payload — audio diventa trascrizione, immagine diventa descrizione, localizzazione diventa {lat,lng}, testo rimane come è.

Al termine della fase 1 hai un oggetto {tenant_id, conversation_id, user_message} pronto per il prossimo passo.

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

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

1. Stato della conversazione (in corso, completata, ecc.).
2. Dati del cliente (nome, email, ecc.).
3. Dati del prodotto (nome, prezzo, ecc.).

Questi dati vengono recuperati da due fonti:

1. D1 (database di prima livello): contiene i dati di base del cliente e della conversazione.
2. KV (chiave-valore): contiene i dati aggiuntivi del cliente e del prodotto.

Al termine della fase 2 hai un oggetto {tenant_id, conversation_id, user_message, context} pronto per il prossimo passo.

Fase 3 — Seleziona abilità (D2 + ML, ~100ms)

L'agente ha bisogno di selezionare l'abilità più adatta per rispondere alla messaggistica del cliente. Questo viene fatto utilizzando:

1. D2 (database di seconda livello): contiene le informazioni sulle abilità e sui modelli di machine learning.
2. ML (machine learning): utilizzato per prevedere la probabilità di successo di ogni abilità.

Al termine della fase 3 hai un oggetto {tenant_id, conversation_id, user_message, context, skill} pronto per il prossimo passo.

Fase 4 — Decide prossima azione (D3 + ML, ~120ms)

L'agente ha bisogno di decidere la prossima azione da intraprendere. Questo viene fatto utilizzando:

1. D3 (database di terza livello): contiene le informazioni sulle azioni e sui modelli di machine learning.
2. ML (machine learning): utilizzato per prevedere la probabilità di successo di ogni azione.

Al termine della fase 4 hai un oggetto {tenant_id, conversation_id, user_message, context, skill, action} pronto per il prossimo passo.

Fase 5 — Esegui con guard-rails (D4 + KV, ~150ms)

L'agente ha bisogno di eseguire la prossima azione. Questo viene fatto utilizzando:

1. D4 (database di quarta livello): contiene le informazioni sulle azioni e sui modelli di machine learning.
2. KV (chiave-valore): utilizzato per recuperare i dati aggiuntivi necessari per l'azione.

Al termine della fase 5 hai un oggetto {tenant_id, conversation_id, user_message, context, skill, action, result} pronto per il prossimo passo.

Fase 6 — Persiste memoria (D5 + KV, ~180ms)

L'agente ha bisogno di persistere la memoria della conversazione. Questo viene fatto utilizzando:

1. D5 (database di quinta livello): contiene le informazioni sulle conversazioni e sui modelli di machine learning.
2. KV (chiave-valore): utilizzato per recuperare i dati aggiuntivi necessari per la conversazione.

Al termine della fase 6 hai un oggetto {tenant_id, conversation_id, user_message, context, skill, action, result, memory} pronto per il prossimo passo.

Il ciclo di un turno è completo e l'agente può rispondere alla messaggistica del cliente.

• Storico recente della conversazione (ultimi N turni rilevanti).
• Memoria a lungo termine del cliente (preferenze, storia di acquisto, annotazioni).
• Stato dell'agente (persona, abilitazioni, regole).

Tutti vengono dal D1 (SQLite distribuito di Cloudflare). D1 sostituisce Postgres/Mongo tradizionale — senza server di database da mantenere, accesso in pochi millisecondi a partire dal worker, multi-tenant per tenant_id.

Punto chiave: non carichiamo la conversazione intera** 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 di alta rilevanza semantica). Ciò mantiene il costo di token prevedibile anche in conversazioni di 100+ turni.

Stadio 3 — Selezione di abilitazioni (policy engine, ~20ms)

Ciascun agente ha un insieme di abilitazioni disponibili — funzioni che può invocare. Esempi: consultare_calendario, creare_evento, generare_link_pagamento, consultare_pedido, chiamare_humano.

Data la messaggio "voglio marcare per sabato mattina", il policy engine filtra:

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

Al termine si ottiene un sottinsieme piccolo di abilitazioni passato al modello — non le 50 possibili, solo le 4 che fanno senso qui. Ciò riduce drasticamente la possibilità che il modello invochi abilitazione errata.

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

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

• Prompt di sistema = persona dell'agente + regole + abilitazioni disponibili.
• Storia = turni selezionati nello stadio 2.
• Messaggio dell'utente = messaggio del turno attuale.

Il modello risponde una delle due cose:

• Risposta finale (testo diretto per il cliente).
• Chiamata di tool (richiesta per eseguire un'abilitazione specifica con parametri).

Nell'esempio "voglio marcare per sabato mattina", il modello tipicamente ritorna:

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

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

L'abilitazione non si esegue nel modello. Si esegue in un codice nostro, che:

...

1. Verifica parametri (la data_range ha formato corretto? è all'interno delle regole del tenant?).
2. Controlla permesso (questo agente ha il diritto di consultare questo calendario?).
3. Esegue la chiamata (API Google Calendar in questo caso).
4. Restituisce risultato strutturato al modello.

Perché ciò è importante? Perché il modello non fabbrica mai il risultato. Se il calendario restituisce [10h, 11h], è esattamente questo che va nella prossima chiamata. Se la skill fallisce, il modello sa che ha fallito. Zero rischio di fatto che l'agente "inventi" di avere un orario alle 9h quando non ce l'ha.

Per i casi che coinvolgono informazioni sensibili (prezzo, termine, nome del cliente), il pipeline obbliga tool call — non lascia che il modello risponda con il proprio "conoscimento". Ciò 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 fa la seconda chiamata — ora per formare la risposta finale per il cliente. Ad esempio:

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

Parallelamente, il worker:

1. Invia la messaggia di ritorno tramite l'API di WhatsApp.
2. Persiste il turno completo (utente + assistente + chiamate tool + durata) nel D1.
3. Aggiorna la memoria a lungo termine se il turno ha prodotto un fatto nuovo (ad esempio "il cliente preferisce sabato").
4. Emette evento di osservabilità (metrica di latenza, costo di token, tasso di scalabilità).

Tutto questo funziona in parallelo. La persistenza non blocca l'invio della messaggia — il cliente non aspetta il D1.

---

Dove è la difesa contro l'allucinazione

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

1. Fonte di verità obbligatoria. I dati fattuali (prezzo, orario, nome) sempre vengono dalla skill, mai dal modello da solo.
2. Verifica doppia sui dati sensibili. L'agendamento è confermato con il cliente prima di persistire. Il pagamento è confermato prima di liberare l'accesso.
3. Regole negative esplicite. La persona di ogni agente include "mai inventare X, Y, Z" — il modello obbedisce.
4. Fallback per l'uomo. Quando nessuna skill copre la domanda, l'agente dice "lasciami controllare con il team" e apre un ticket — non butta.

Nelle audit che abbiamo fatto negli ultimi 6 mesi (conversazioni reali riviste manualmente), la percentuale di allucinazione fattuale è stata inferiore a 0,3% dei turni — e quasi tutti i casi sono stati per configurazione (tenant dimenticato di abilitare la skill rilevante), non erro del modello.

---

Il costo per conversazione

Arquitettura buona è invisibile fino a quando non si guarda la fattura. Data la circostanza che ogni turno fa 1-2 chiamate di LLM + lookups in D1, il costo tipico per una conversazione completa (10-15 turni) si attesta in:

Nota: Ho tradotto solo il testo, mantenendo la formattazione markdown originale. Non ho tradotto URL, codice o tag HTML.