Dal prototipo al sistema
Un risultato isolato non rende ancora il progetto mantenibile.
Un prototipo dimostra che un modello può produrre un risultato in una situazione preparata. Un sistema deve riuscirci dentro un progetto che cambia, insieme a persone, dati, strumenti, vincoli e conseguenze reali.
Un buon modello può scrivere codice, analizzare documenti e coordinare strumenti. Se ogni sessione ricomincia da una descrizione incompleta, decisioni, correzioni, criteri e attività già svolte si disperdono tra prompt, chat, file e memoria delle persone.
- l’obiettivo vive soltanto nella conversazione corrente;
- le fonti utili non sono distinte da ipotesi e materiale superato;
- il sistema non sa che cosa è già stato deciso o modificato;
- istruzioni e competenze si accumulano senza una relazione chiara;
- un agente usa strumenti senza distinguere gli effetti consentiti;
- i test controllano l’output, ma non il percorso che lo ha prodotto;
- dopo un errore o una pausa non esiste uno stato dal quale riprendere.
Un modello più grande o un prompt più lungo possono migliorare una singola risposta. La continuità richiede una struttura esterna al turno che mantenga leggibili le relazioni del progetto.
Scegliere la forma
Assistente, automazione e sistema agentico rispondono a lavori differenti.
Assistente AI
Risponde, analizza, propone o prepara oggetti mentre una persona conduce il lavoro. È adatto quando ogni passaggio richiede giudizio diretto o quando l’attività deve restare esplorabile.
Automazione con AI
Esegue una sequenza definita. Il modello può classificare, estrarre, confrontare o generare una parte del risultato, mentre percorso ed effetti restano stabiliti in anticipo.
Sistema agentico
Mantiene un obiettivo e uno stato, sceglie fra passaggi o strumenti disponibili e modifica il percorso in base a ciò che trova. Richiede fonti, responsabilità, condizioni di arresto, verifiche e recupero espliciti.
La forma più articolata non è un traguardo automatico. La scelta dipende dal lavoro che deve diventare possibile e dalla variabilità che il sistema deve interpretare senza rendere opache cause e responsabilità.
Architettura
Le nove relazioni di un progetto agentico.
Intento e risultato da mantenere
«Analizza questi file» descrive un’azione. «Mantieni aggiornata la documentazione tecnica quando cambia il comportamento verificato dell’applicazione» collega fonti, condizioni e continuità a un risultato osservabile. L’intento resta correggibile quando il progetto espone nuovi vincoli o possibilità.
Oggetto e perimetro
Il sistema deve sapere se sta operando su un repository, un’applicazione, un processo, un corpus o un servizio. Distingue inoltre ciò che è adiacente da ciò che può modificare. La comprensione può essere ampia; ogni effetto materiale conserva un proprietario preciso.
Fonti e verità corrente
Codice, stato, documentazione, database, conversazioni e servizi non hanno la stessa autorità. L’architettura indica quali fonti descrivono l’intento, quali possiedono lo stato corrente, quali sono storiche e come gestire una divergenza.
Stato e continuità
Uno stato utile conserva l’oggetto attivo, ciò che è stato verificato, le decisioni correnti, i confini e il prossimo passaggio recuperabile. Deve consentire di rientrare nel lavoro corretto senza rileggere tutto e senza inventare ciò che è accaduto.
Competenze
Una competenza stabilizza un modo di ottenere un risultato: criteri, fonti, trasformazioni, errori ricorrenti, verifiche e confini. Diventa utile quando modifica in modo riconoscibile la qualità del risultato e può migliorare attraverso l’esperienza.
Strumenti e azioni
Leggere un file, modificare codice, interrogare un servizio, inviare un messaggio e pubblicare una release producono effetti differenti. Ogni strumento ha input, output, condizioni d’uso ed effetto osservabile. Preparare una patch e pubblicarla restano due stati distinti.
Responsabilità e autorizzazioni
Per ogni effetto materiale servono una decisione responsabile, un’azione consentita, un limite di accesso e una persona che risponda del risultato nel contesto reale. Un controllo preciso lascia libero il ragionamento e governa soltanto l’effetto che può produrre conseguenze.
Verifica e traccia del risultato
Il sistema deve mostrare che cosa ha osservato, cambiato e controllato. Test, confronto con le fonti, identità dei file, comportamento dell’applicazione e revisione umana raggiungono livelli diversi. Un comando eseguito, un test passato e una funzione accettata non sono lo stesso evento.
Recupero ed evoluzione
Un sistema mantenibile sa riprendere dopo un’interruzione, correggere una decisione e sostituire una dipendenza senza perdere il progetto. Una correzione reale può migliorare una competenza, un test o una relazione senza riscrivere ogni parte per associazione.
Oggetto pratico
Agentic Project Architecture Canvas.
Usa le domande per trasformare l’idea di un agente in un primo oggetto di progetto. Le risposte possono essere provvisorie: i vuoti mostrano ciò che il sistema dovrà chiarire prima di agire.
- 01
Progetto
Quale applicazione, repository, processo o servizio deve sostenere il sistema? Chi ne possiede stato e decisioni?
- 02
Risultato
Quale cambiamento deve continuare a produrre o preservare? Come si distingue da un singolo compito?
- 03
Fonti
Quali file, dati, API, documenti e persone contengono le informazioni necessarie? Quali fonti sono correnti, storiche o da verificare?
- 04
Stato
Che cosa deve essere rileggibile dopo una pausa o un cambio di sessione? Qual è la descrizione minima della situazione e del prossimo passaggio?
- 05
Competenze
Quali trasformazioni ricorrenti richiedono un metodo stabile? Quali criteri ed errori devono entrare nella competenza?
- 06
Strumenti e azioni
Che cosa può leggere, preparare, modificare o eseguire il sistema? Qual è l’effetto finale di ogni strumento?
- 07
Responsabilità
Quali azioni sono interne e reversibili? Quali richiedono una decisione umana, un altro responsabile o un’autorizzazione esterna?
- 08
Prova
Come verranno verificati output, percorso e stato finale? Quale evidenza deve sopravvivere alla sessione?
- 09
Continuità
Come riprende il sistema dopo un’interruzione? Quali parti devono poter cambiare senza perdere intento, fonti e proprietà del progetto?
Il sistema sostiene [progetto] per mantenere [risultato]. Usa [fonti], conserva [stato] e applica [competenze] attraverso [strumenti]. Può eseguire [azioni consentite]; [persona responsabile] decide [effetti riservati]. Il risultato viene verificato con [prove] e il lavoro riprende da [punto di continuità].
Scenario
Un assistente di sviluppo che non riparte da zero.
Immaginiamo un team che mantiene un’applicazione web. Il modello sa leggere e scrivere codice, ma ogni nuova sessione deve ricostruire architettura, decisioni, bug aperti e procedure di rilascio. Le correzioni restano nelle chat e i test locali non spiegano quale versione sia online.
Una prima architettura agentica può collegare:
- 1un file di ingresso che identifica progetto, fonti e regole correnti;
- 2uno stato compatto con obiettivo, lavoro verificato e prossimo passaggio;
- 3competenze separate per diagnosi, modifica, test e pubblicazione;
- 4strumenti con effetti distinti: lettura, patch locale, commit e pubblicazione;
- 5test che verificano comportamento e confini del cambiamento;
- 6una traccia che registra file modificati, prove e stato finale;
- 7un punto di ripresa per la sessione successiva.
L’agente può così analizzare e preparare una correzione senza ottenere automaticamente il permesso di pubblicarla. Quando la pubblicazione è selezionata, l’architettura aggiunge identità della versione, percorso di rilascio, verifica online e recupero.
Il valore deriva dal fatto che comprensione, decisioni, effetti e prove restano parte del progetto.
Portabilità
Il progetto conserva la propria identità mentre modelli e ambienti cambiano.
Modelli diversi offrono qualità diverse di ragionamento, codice, velocità o costo. Intento, fonti, stato e verifiche dovrebbero vivere nel progetto, così da poter scegliere il modello adatto a un compito senza consegnargli l’intera continuità.
La portabilità richiede adattamento. Un coding agent locale, un’applicazione web e un servizio remoto hanno strumenti, permessi e superfici di stato differenti. Il nucleo del progetto resta riconoscibile mentre ogni ambiente riceve gli ingressi necessari al proprio funzionamento.
Controllo del progetto
Errori frequenti nella costruzione di agenti AI.
Usare il prompt come unica architettura
Il prompt orienta un turno. Fonti correnti, stato, strumenti, prove e recupero rendono il lavoro leggibile nel tempo.
Confondere memoria e cronologia
Conservare ogni messaggio non chiarisce che cosa sia stato deciso. Una memoria utile seleziona relazioni e stati necessari e mantiene la loro provenienza.
Aggiungere strumenti prima degli effetti
Un elenco di integrazioni non dice che cosa il sistema possa fare. Distingui prima leggere, proporre, modificare, inviare, pubblicare o spendere una risorsa.
Accumulare competenze senza prova
Una skill dichiarata non dimostra una capacità. Serve un risultato osservabile che mostri quando viene attivata, che cosa trasforma e come viene corretta.
Rendere l’autonomia un requisito iniziale
Assistenti e automazioni supervisionate possono creare valore. L’autonomia matura azione per azione, quando stato, responsabilità, prova e recupero sono leggibili.
Verificare soltanto l’ultima risposta
Un output corretto può provenire da fonti sbagliate o da un percorso irripetibile. La verifica deve raggiungere le relazioni che rendono affidabile il risultato.
Domande frequenti
Domande sui sistemi agentici.
Un agente AI deve avere una memoria vettoriale?
Non necessariamente. La memoria dipende da ciò che il progetto deve recuperare. Stato strutturato, file correnti, registri e fonti nominate possono essere più importanti di una ricerca semantica generale. La memoria vettoriale è utile quando la ricerca per significato risolve un problema reale del corpus.
Qual è la differenza fra agente AI e sistema agentico?
Un agente può essere un componente che persegue un compito e usa strumenti. Un sistema agentico comprende anche stato, fonti, competenze, coordinamento, autorizzazioni, prove e recupero che rendono quel comportamento sostenibile.
Devo usare più agenti?
Solo quando ruoli o lavori realmente distinti beneficiano di stati, strumenti o verifiche differenti. Molti compiti possono essere svolti da un solo assistente con contesto e competenze ben organizzati. Più agenti aggiungono coordinamento, costi e punti di errore.
Come capisco se il sistema mantiene davvero il contesto?
Interrompi e riprendi il lavoro da una nuova sessione. Verifica se il sistema riconosce oggetto, stato, fonti, decisioni e prossimo passaggio senza una ricostruzione manuale completa. Poi cambia una decisione a monte e osserva se gli stati derivati vengono corretti.
Posso cambiare modello o ambiente in seguito?
Sì, quando identità e continuità del progetto vivono in fonti leggibili dall’ambiente destinatario. Strumenti, formati e capacità restano specifici dell’host e richiedono un adattamento.
Quando un sistema è pronto ad agire senza conferma?
Quando l’effetto è delimitato, la responsabilità è chiara, la prova raggiunge lo stato finale e un errore ha un percorso di recupero proporzionato. Questa maturità può essere diversa per ogni azione.