--- title: "Gli strati di un agente AI: contesto, harness e connettori" url: https://zerofive.ai/blog/approfondimenti/contesto-harness-connettori-agenti-ai canonical: https://zerofive.ai/blog/approfondimenti/contesto-harness-connettori-agenti-ai language: it published: 2026-10-31 updated: 2026-10-28 author: "ZeroFive.AI" tags: agenti AI, context engineering, harness, connettori, MCP, architettura AI abstract: "Gli agenti AI sbagliano più per il contesto che per il modello: come separare contesto, harness e connettori e chi decide cosa in ogni strato." --- # Gli strati di un agente AI: contesto, harness e connettori **In sintesi.** Gli errori degli agenti AI in produzione dipendono più spesso da quello che il modello riceve e da quello che gli è permesso fare che dal modello stesso. Nel metodo ZeroFive.AI l'architettura di un agente si separa in tre strati: il contesto, che decide cosa il modello vede a ogni punto di decisione; l'harness, che esegue le sue proposte entro permessi, budget e cancelli di approvazione; i connettori, uno per sistema di record, che portano dati con fonte e data e propagano l'identità di chi lavora. Permessi, fonti autorevoli e approvazioni si scrivono nel codice, il modello sceglie solo dentro quel perimetro, e ogni fase di costruzione si misura su casi di valutazione presi dal processo reale. Se apriamo i log di un agente AI che ha sbagliato in produzione, il caso più frequente è un modello che ha ragionato in modo corretto su informazioni sbagliate: una policy sostituita da mesi ma ancora presente nell'indice, lo stato di un ordine letto da una copia notturna invece che dal gestionale, il record di un cliente con un nome simile a quello giusto, un'azione eseguita due volte perché dopo un'interruzione il processo è ripartito da capo. Nessuno di questi errori si corregge cambiando modello, perché dipendono da quello che il modello ha ricevuto e da quello che gli è stato permesso di fare. Rakesh Sheshadri ha pubblicato su Medium una mappa molto estesa di quello che chiama [context layer](https://medium.com/@rakesh.sheshadri44/the-context-layer-for-ai-agents-1c3510fcdbc7), cento concetti in sedici parti, dalla memoria al retrieval, dalla gestione dello stato alla sicurezza, con un obiettivo che condividiamo: dare a ogni agente l'informazione minima sufficiente, autorizzata, affidabile e aggiornata per il compito che sta svolgendo. Partiamo da lì, ma riorganizziamo il discorso intorno alla separazione che usiamo nei progetti e nella costruzione dei nostri [strumenti interni](/blog/approfondimenti/azienda-agentica-otto-strati), quella tra contesto, harness e connettori, perché è la separazione che stabilisce dove il modello può scegliere e dove deve scegliere un sistema deterministico. Il pezzo è tecnico e parla a chi progetta e costruisce agenti, ma la domanda che lo attraversa è quella che facciamo anche al management prima di qualunque progetto: quali decisioni lasciamo al modello e quali scriviamo nel codice. ## Gli strati intorno al modello La separazione che usiamo mette il modello al centro di tre strati con responsabilità distinte: il contesto stabilisce cosa il modello vede, l'harness stabilisce cosa può fare e come le sue proposte diventano azioni, i connettori stabiliscono come il sistema raggiunge i dati e le applicazioni dell'azienda. Sheshadri descrive sette strati, dalle fonti dati fino all'esecuzione dell'agente, con governance e osservabilità trasversali a tutti; la nostra versione li raggruppa per tipo di decisione, perché è su quel confine che si stabilisce cosa affidare a un [sistema probabilistico](/blog/approfondimenti/probabilistico-deterministico-architettura-ai) e cosa no. Il modello riceve un pacchetto di contesto e restituisce proposte; ogni lettura e ogni scrittura verso i sistemi di record passa dall'harness e da un connettore, mai direttamente dal modello. ## Il layer di contesto Il contesto è quello che il modello vede nel momento in cui deve decidere, e la prima scelta di progetto riguarda proprio il momento: un agente che lavora su un processo di più passaggi ha bisogno di informazioni diverse quando pianifica e quando esegue una chiamata, per cui il contesto si assembla a ogni punto di decisione e non una volta sola all'inizio della sessione. Sheshadri lo formula come un problema di ottimizzazione, scegliere tra le evidenze disponibili il sottoinsieme più utile per il compito entro vincoli di token, latenza, autorizzazione e freschezza, una formulazione che sposta l'attenzione dalla quantità alla selezione. In pratica il layer di contesto produce un pacchetto strutturato, con campi che il modello impara a riconoscere e che chi fa debug può leggere: le istruzioni del compito, lo stato corrente del workflow, le evidenze recuperate con la loro provenienza, le memorie verificate, i conflitti tra fonti e le informazioni che mancano. Gli ultimi due campi sono quelli che vediamo trascurati più spesso, e sono quelli che permettono al modello di dire che non ha abbastanza elementi invece di riempire il vuoto con una risposta plausibile. Ogni evidenza porta con sé i metadati senza cui il modello non ha modo di pesarla, cioè la fonte, il momento della lettura e l'affidabilità di quella fonte per quel tipo di dato. Lo stesso CRM può fare fede per il referente di un cliente e contare poco per lo stato di un pagamento, che dipende dalla fatturazione, e questa mappa delle fonti autorevoli va scritta prima di costruire il retrieval, perché il ranking per similarità semantica non sa nulla di autorità. Con la freschezza succede qualcosa di simile. Una descrizione di prodotto può restare valida per mesi mentre la disponibilità di magazzino cambia nell'arco di minuti, e un sistema che le mette nello stesso indice con la stessa politica di aggiornamento finisce per servire al modello numeri vecchi presentati come attuali; nei nostri progetti l'indice serve a trovare e il sistema di origine a confermare, e tutto ciò che cambia più in fretta del ciclo di indicizzazione si legge in tempo reale attraverso [un connettore](/blog/approfondimenti/rag-connettori-dati-ai). Il retrieval in senso stretto è una scelta per tipo di domanda, e un planner che sceglie la strategia e riordina i risultati prima di assemblarli produce contesti più piccoli e più precisi di qualunque pipeline unica applicata a tutto: - ricerca semantica per le domande sui concetti - ricerca per parole chiave per gli identificativi esatti, come un numero di fattura - attraversamento delle relazioni per le domande che passano da un'entità all'altra - interrogazione diretta dei sistemi operativi per i dati che cambiano ## La memoria e lo stato dei workflow Memoria e stato vengono spesso trattati come la stessa cosa, perché entrambi servono a non ricominciare da capo, ma rispondono a domande diverse e vanno progettati separatamente. La memoria conserva quello che serve sapere tra un'interazione e l'altra (una preferenza, un fatto su un cliente, l'esito di un caso già risolto), lo stato descrive a che punto si trova un processo in corso, cosa è stato fatto, cosa manca e quali azioni hanno già prodotto effetti fuori dal sistema. Per la memoria la distinzione di Sheshadri tra memoria semantica, episodica e procedurale ha conseguenze pratiche, perché ogni tipo segue una politica di aggiornamento propria: un fatto va riverificato periodicamente, un evento passato non si riscrive, una procedura arriva da una fonte controllata e l'agente non la modifica da solo. Ogni record di memoria che progettiamo porta il soggetto, la fonte che lo sostiene, un livello di confidenza, un perimetro di accesso e una data di revisione, e soprattutto distingue quello che l'utente ha detto da quello che il sistema ha dedotto. Una memoria senza questi campi diventa, nel giro di qualche mese, un archivio di supposizioni che nessuno è più in grado di verificare. La scrittura in memoria passa dall'harness, come ogni altra scrittura. Il modello propone cosa ricordare, un controllo deterministico verifica tipo, perimetro e conservazione, e per le informazioni più delicate decide una persona; è lo schema che usiamo anche internamente, dove le note che un agente ricava da riunioni e posta entrano nello spazio di lavoro dei progetti solo dopo un'approvazione esplicita, raccolte in un pacchetto che si accetta o si rifiuta. Lo stato chiede strumenti diversi. Un workflow che dura ore, magari fermo in attesa di un'approvazione umana, ha bisogno di checkpoint persistenti per riprendere dopo un'interruzione, di un registro degli eventi da cui ricostruire cosa è successo e di chiavi di idempotenza sulle azioni esterne, perché un agente che riparte da un checkpoint non deve emettere due volte lo stesso ordine o inviare due volte la stessa mail. Quando il lavoro passa [da un agente all'altro](/blog/approfondimenti/sistemi-multi-agente-quanti-agenti-servono), il passaggio di consegne è un oggetto strutturato con l'obiettivo, i risultati verificati, le ipotesi aperte e le azioni consentite; la trascrizione del ragionamento dell'agente precedente aggiunge token e quasi mai informazioni utili a chi riceve. ## L'harness Chiamiamo harness l'ambiente di esecuzione che sta intorno al modello, il ciclo che gli passa il contesto, riceve la sua proposta, esegue le chiamate agli strumenti, osserva il risultato e decide se continuare, fermarsi o coinvolgere una persona. Nella mappa di Sheshadri queste funzioni sono distribuite tra il gateway, l'orchestrazione e la gestione dello stato; noi preferiamo tenerle insieme, perché sono le parti del sistema in cui un errore esce dal perimetro della risposta e produce effetti su clienti, ordini e documenti. L'harness stabilisce quali strumenti sono disponibili per quel compito e con quale identità vengono chiamati. Il controllo dei permessi avviene qui, in codice, prima di ogni chiamata, e non dipende da quello che il modello ha capito o da quello che è scritto in un documento recuperato. È anche la difesa strutturale contro la prompt injection: un testo dentro una mail o una pagina web che chiede all'agente di esportare dati non può allungare l'elenco degli strumenti autorizzati, perché quell'elenco non passa dal modello. Un filtro sul testo riduce il rischio, un perimetro di strumenti stretto ne limita i danni anche quando il filtro fallisce. Le azioni si dividono in due famiglie con regole diverse. Le letture possono procedere in autonomia entro un budget di passi e di costo, mentre le scritture, e in particolare quelle irreversibili, passano da un cancello di approvazione la cui posizione dipende dal [livello di delega](/blog/strategia/ai-assisted-ai-first-ai-native-livelli-delega) scelto per quel processo. Nel nostro lessico un processo AI-assisted lascia il lavoro alla persona e usa l'agente ai margini, uno AI-first fa lavorare l'agente e fa rivedere ogni output, uno AI-native affida all'agente l'esecuzione completa e chiede alle persone di scrivere policy e guardrail. Tecnicamente il passaggio da un livello all'altro è una modifica alla configurazione dell'harness, a dove stanno i cancelli e a chi li apre, con lo stesso modello di prima. Ci sono poi responsabilità meno visibili ma decisive in produzione: regole di terminazione che impediscono cicli di retrieval senza fine, gestione dei tentativi ripetuti con chiavi di idempotenza, un log completo di ogni chiamata insieme al contesto che l'ha preceduta. Quel log permette di rispondere, dopo un errore, a domande come quale versione della policy l'agente aveva letto o se aveva il permesso di vedere quel record, senza chiedere al modello di ricostruire il proprio ragionamento a posteriori. ## I connettori Un connettore è l'adattatore tra il sistema e una singola fonte di record, il gestionale, il CRM, l'archivio documentale o la posta. MCP ha reso molto più economico costruirli, perché standardizza il modo in cui un'applicazione AI scopre e invoca strumenti e risorse esposti da un server esterno; il protocollo però definisce come si parla con il sistema, e lascia a chi progetta tutte le scelte che determinano se quel connettore è sicuro e utile. Sull'identità si decide buona parte del rischio. Un connettore che usa un account di servizio con accesso completo trasferisce al modello permessi che nessun utente del processo possiede, mentre un connettore che propaga l'identità di chi ha avviato il compito eredita i controlli già presenti nel sistema di origine, compreso l'isolamento tra clienti o tra società del gruppo. Sul perimetro valgono le stesse cautele: strumenti di sola lettura e strumenti di scrittura separati, ciascuno con i parametri strettamente necessari, perché un'interfaccia generica del tipo «esegui una query» lascia al modello decisioni che spettano a chi progetta. Ogni risposta di un connettore dovrebbe arrivare con i metadati che servono al layer di contesto (identificativo del record, momento della lettura, fonte) e con limiti espliciti su paginazione e dimensione, in modo che una risposta troncata o un errore di formato vengano riconosciuti come tali invece di finire nel prompt come dati validi. Quanti connettori costruire è una scelta architetturale. Se ogni agente ha il suo accesso al CRM, il suo indice dei documenti e la sua memoria dei clienti, nel giro di qualche mese l'azienda si ritrova con più versioni della stessa realtà e nessun punto da cui revocare un permesso una volta sola. Il modello che seguiamo prevede un connettore per sistema di record, condiviso tra gli agenti e governato da un unico insieme di regole, ed è la logica con cui abbiamo esposto agli agenti i nostri strumenti interni, il gestionale e lo spazio di lavoro dei progetti, entrambi via MCP e con le scritture sempre subordinate a un'approvazione. ## La separazione delle responsabilità La separazione tra gli strati diventa operativa quando ogni decisione dell'agente ha un responsabile esplicito, che può essere il modello, una regola scritta nel codice o una persona. La tabella è quella che usiamo come lista di controllo nella progettazione. | Decisione | Chi decide | Strato | | --- | --- | --- | | Quali informazioni sono rilevanti per il compito | Modello, su candidati già filtrati | Contesto | | Quale fonte fa fede per un certo dato | Regola scritta a monte | Contesto | | Se le evidenze sono sufficienti | Modello, con segnalazione obbligatoria delle lacune | Contesto | | Se l'utente può vedere un record | Codice deterministico | Connettore | | Quale strumento chiamare tra quelli consentiti | Modello | Harness | | Se un'azione irreversibile può partire | Persona o regola, secondo il livello di delega | Harness | | Cosa entra in memoria | Il modello propone, regola o persona approvano | Harness | | Quando fermarsi | Regola di terminazione e budget | Harness | Ogni riga in cui la colonna centrale dice «modello» dove dovrebbe dire «codice» o «persona» è un rischio che nessun benchmark sul modello farà emergere, perché il modello in quel caso funziona esattamente come è stato configurato. ## Le fasi di costruzione Un layer di contesto non si progetta tutto in una volta, e la sequenza che proponiamo parte dalla misura prima che dal codice. Prima di scrivere il retrieval si costruisce un insieme di casi di valutazione presi dal processo reale, con le risposte attese, le fonti che dovrebbero sostenerle e i confini di accesso, includendo di proposito i casi difficili che Sheshadri elenca in chiusura del suo pezzo: documenti in conflitto, una policy appena sostituita, un permesso revocato, un contenuto recuperato che contiene istruzioni, un workflow interrotto a metà, un passaggio tra due agenti. Su quella base le fasi seguono l'ordine che propone anche lui. 1. Retrieval ibrido con citazioni e permessi a livello di fonte. 2. Stato persistente, checkpoint e memoria con politiche di conservazione. 3. Connettori ai sistemi operativi, con regole di freschezza e separazione tra letture e scritture. 4. Contesto condiviso tra più agenti, con contratti di passaggio e spazi di memoria separati. 5. Relazioni tra entità, retrieval adattivo e ragionamento temporale. La differenza sta nel criterio di passaggio. Si va alla fase successiva quando la precedente supera la soglia concordata sui casi di valutazione, e la metrica che decide è il completamento corretto del compito, con precisione e copertura del retrieval usate come diagnostica per capire dove intervenire. Applicato così, il percorso si ferma spesso prima della quinta fase, perché per molti processi un grafo di conoscenza o un retrieval agentico aggiungono costo e latenza senza spostare il risultato, ed è un'informazione che conviene avere prima di finanziarli. ## Gli errori di progetto più frequenti Gli errori che incontriamo più spesso, compresi quelli che abbiamo fatto nei nostri primi agenti, nascono quasi tutti da una responsabilità messa nello strato sbagliato. - Permessi affidati al prompt, con istruzioni come «non mostrare dati di altri clienti» al posto di un filtro applicato dal connettore. - Un indice usato come fonte di verità per dati che cambiano in fretta, come prezzi, giacenze o stato degli ordini. - Una memoria che conserva tutto, senza distinguere i fatti dichiarati dalle deduzioni e senza date di revisione. - Un retrieval diverso per ogni agente, con indici che divergono e permessi da revocare in più punti. - Riassunti usati al posto delle fonti in decisioni dove conta l'eccezione, come una clausola contrattuale. - Azioni esterne senza idempotenza, che dopo un'interruzione vengono eseguite di nuovo. - Connettori con account di servizio onnipotenti, che danno all'agente più accesso di chiunque lo stia usando. In questa architettura il modello è il componente destinato a cambiare più spesso, per costo, per prestazioni o per vincoli su dove devono stare i dati. Se contesto, harness e connettori sono separati, il cambio tocca una configurazione e si verifica rilanciando i casi di valutazione; se le regole vivono nei prompt e i permessi nelle istruzioni, ogni nuovo modello riapre un progetto da validare da capo. Contare quante decisioni dell'agente sarebbero ancora valide il giorno in cui si cambia modello è il modo più rapido per capire quanta parte del sistema è stata progettata e quanta è stata lasciata al caso.