Ogni record si spiega da sé: il serializzatore ai_context

La parte entusiasmante del software nativo IA è l'agente che fa qualcosa di utile. La parte che lo fa davvero funzionare è noiosa: il modo in cui un record si descrive a un modello.

Sbaglialo, e ogni demo a valle è costruita sulla sabbia. Azzeccalo, e l'agente smette di tirare a indovinare.

Le righe grezze sono l'input sbagliato

Una riga di database è costruita per il database. Ha chiavi esterne, enum di stato, colonne nullable, flag interni e marche temporali in UTC. Passala a un modello e gli hai chiesto due lavori in una volta sola: ricostruire che cosa significa il record e poi ragionarci sopra.

Il primo lavoro lo farà male. status: 3 non significa nulla senza la tabella di lookup. Un null in closed_at può voler dire «ancora aperto» oppure «mai tracciato». Una chiave esterna è un numero che il modello non può seguire. Così il modello inventa il significato che gli serve — con sicurezza — e l'errore si propaga a ogni passo successivo.

La soluzione non è un modello più grande. È dare al modello l'input giusto.

Che cos'è un serializzatore ai_context

In Cyril ogni entità — un cliente, una trattativa, un progetto, un ticket, una fattura — espone un serializzatore ai_context. È un unico metodo che restituisce una vista deterministica e consapevole dello schema, costruita apposta per ancorare l'IA.

Quella vista fa l'interpretazione che il modello non dovrebbe doversi fare:

• Gli enum sono risolti nel loro significato umano — status: 3 diventa "fase: negoziazione".
• Lo stato correlato è incorporato — un cliente porta con sé il numero di ticket aperti, lo stato dei progetti attivi e quello delle fatture insolute, perché è esattamente ciò di cui avrà bisogno una domanda su quel cliente.
• I campi solo interni sono eliminati — il modello non vede mai gli ID di riga, i flag di cancellazione logica o l'impianto di multi-tenancy.
• La forma è stabile — lo stesso record produce sempre lo stesso contesto, quindi i prompt sono memorizzabili in cache e il comportamento è riproducibile.

Non è, deliberatamente, né la risposta dell'API né la riga del database. È una terza rappresentazione il cui unico pubblico è un modello.

Perché «obbligatorio su ogni entità» è tutto il punto

Sarebbe facile scrivere un serializzatore ai_context per le tre entità che tocca una demo di lancio. È proprio quella la trappola. Il valore di un unico grafo di dati è che una domanda può attraversare qualsiasi confine: «quali clienti a rischio hanno anche un progetto in ritardo e una fattura non pagata?» funziona solo se clienti, progetti e fatture si spiegano tutti allo stesso modo.

Per questo in Cyril il serializzatore è un requisito, non una funzionalità. Una nuova entità non è finita finché non ne ha uno. I pattern di test lo verificano. È una disciplina poco appariscente ed è esattamente ciò che permette a un agente di attraversare la piattaforma senza incontrare un record che non sa leggere.

Il determinismo è anche una proprietà di sicurezza

Poiché il serializzatore è l'unica vista esposta all'IA, è anche il punto in cui controlliamo l'esposizione. Le decisioni a livello di campo su che cosa un agente può vedere stanno in un solo posto verificabile per entità, con scope su org_id come qualsiasi altra interrogazione. Non esiste un percorso separato di «esportazione per l'IA» che allarghi in silenzio il raggio d'azione: lo stesso serializzatore che ancora il modello è anche il confine che lo limita.

Che cosa ci guadagni

• Poni una domanda che attraversa più moduli e ottieni una risposta ancorata a dati risolti, correlati e attuali — non a righe grezze che il modello ha dovuto decifrare.
• Ti fidi della risposta abbastanza da agire, perché lo stesso record produce sempre lo stesso contesto.
• Sai che ciò che l'IA può vedere è definito in un solo posto per entità, non sparso fra le integrazioni.

Il serializzatore non sarà mai la funzionalità di punta. È lo strato che decide se le funzionalità di punta sono vere.

Domande frequenti

In che cosa è diverso dalla risposta dell'API?

La risposta dell'API è modellata per uno sviluppatore che sta assemblando una schermata: è completa, normalizzata e dà per scontato che chi la chiama conosca il dominio. Il serializzatore è modellato per un lettore che non conosce lo schema e non può seguire una chiave esterna, quindi risolve invece di rimandare.

Perché non fare semplicemente recupero sul database?

Il recupero trova testo che somiglia alla domanda. Risponde a ciò che a un certo punto è stato scritto, non a ciò che è vero adesso di un record — e per «quali clienti sono a rischio questo trimestre», ciò che è vero adesso è tutta la domanda.

Costruire questa vista rallenta le interrogazioni?

Lo stato correlato che incorpora è stato di cui una risposta vera avrebbe comunque avuto bisogno; raccoglierlo una volta sola, in modo deterministico, costa meno che farselo chiedere dal modello nell'arco di più turni. Il determinismo rende anche il risultato memorizzabile in cache, cosa che il percorso a righe grezze non è.

Che cosa succede quando si aggiunge una nuova entità?

Non è finita finché non ne ha uno. È imposto nei pattern di test invece che affidato alla memoria, perché il valore del grafo è che una domanda possa attraversare qualsiasi confine: una sola entità senza serializzatore è una buca in cui un agente cade.

---

Se vuoi essere tra i primi a usare Cyril, iscriviti alla lista d'attesa.