Portabilità degli agenti
La portabilità va misurata per strati: artefatti, configurazione, capacità operative e dipendenze esterne non viaggiano nello stesso modo.
In breve
Sezione intitolata “In breve”“Clone riuscito” e “agente equivalente” sono promesse molto diverse. La portabilità si valuta per strati: sorgenti disponibili, installazione ricostruita, canali operativi e comportamento atteso. Ogni strato deve dichiarare cosa viaggia nel repository, cosa viene derivato, cosa richiede consenso e cosa resta un prerequisito esterno. Un singolo bollino portabile/non portabile nasconde proprio i gap che servono durante una migrazione.
Quattro livelli di promessa
Sezione intitolata “Quattro livelli di promessa”- Sorgente: codice, manifesti e procedure sono clonabili.
- Installato: il setup verificabile ricrea gli artefatti che possiede.
- Operativo: prerequisiti, autorizzazioni e trasporti superano probe reali.
- Equivalente: regole, capacità e confini producono il comportamento dichiarato.
Il livello superiore include quelli inferiori, ma non ne deriva automaticamente. Una macchina può avere lo stesso launcher e un profilo diverso; oppure configurazione identica e nessun accesso al servizio richiesto. La frase utile è quindi “ricostruisce il livello 2 e verifica tre capacità del livello 3”, non “funziona ovunque”.
Matrice di portabilità
Sezione intitolata “Matrice di portabilità”| Dipendenza | Strategia | Prova su una macchina nuova |
|---|---|---|
| Script e launcher | versionare | hash o test di struttura |
| Versioni dei runtime | fissare oppure registrare | confronto compatibilità |
| Configurazione del toolkit | frammenti con merge idempotente | valore letto dal consumer |
| Preferenze personali | non copiare | assenza dichiarata, nessun default inventato |
| Permessi e trust | consenso esplicito | probe non interattivo controllato |
| Identità e segreti | mantenere fuori dal repository | presenza verificata senza mostrare il valore |
| Rete e servizi | contratto ambientale | handshake sul target logico |
| Memoria e stato | migrazione separata o nuovo seed | test semantico circoscritto |
La matrice impedisce due errori opposti: versionare stato personale perché “serve al comportamento”, oppure tacere una dipendenza perché “non può stare nel repo”. Un segreto resta esterno, ma il nome logico della capacità che abilita, il modo per verificarne la presenza e il comportamento in sua assenza devono essere documentati.
Caso: installato ma inerte
Sezione intitolata “Caso: installato ma inerte”Un toolkit ricostruiva correttamente script e hook e la verifica confermava che i file esistessero. Sulla nuova macchina, però, il comando scelto per eseguire un handler risolveva uno shim privo del runtime necessario. L’hook non produceva alcun evento, mentre il report restava verde. Il repository era portabile al livello “installato”, non al livello “operativo”.
La correzione ha separato risoluzione e capacità: il preflight identifica un interprete compatibile; il probe invoca l’handler con un evento sintetico e controlla che l’effetto atteso compaia. Verificare il canale eseguito evita che il test cada su un interprete o una copia differenti. Questo episodio mostra perché Test-Path misura inventario, non funzionamento.
Compilare la scheda di migrazione
Sezione intitolata “Compilare la scheda di migrazione”Per ogni agente conviene produrre una scheda breve con: livello promesso, sistemi operativi provati, runtime compatibili, artefatti posseduti, prerequisiti esterni, probe disponibili e gap noti. Le versioni collaudate possono essere registrate senza bloccare automaticamente ogni drift; la scelta tra pin ed avviso dipende dalla stabilità dell’interfaccia.
La dichiarazione esplicita delle dipendenze sostiene la parte inventariale della scheda. Non prova però equivalenza di profili, permessi o canali. Questi richiedono test funzionali. Allo stesso modo, la parità tra ambienti riduce differenze intenzionali, ma non trasforma servizi esterni in artefatti clonabili.
La matrice fotografa un momento: vendor, permessi e interfacce cambiano. Un test non può autorizzare l’utente, replicare una rete privata o garantire equivalenza semantica della memoria. Alcune transizioni restano deliberatamente manuali. La portabilità migliora quando ogni esclusione è esplicita e verificabile, non quando si accumulano copie di configurazioni esterne.
Voci correlate
Sezione intitolata “Voci correlate”- The Twelve-Factor App: Dependencies, riferimento generale sulla dichiarazione e sull’isolamento delle dipendenze; non prova portabilità di plugin, permessi o profili di agenti.
- The Twelve-Factor App: Dev/Prod Parity, riferimento generale sulla parità tra ambienti; non stabilisce equivalenza dei canali di esecuzione.