Come creare un agente AI

Come creare un agente AI: ciclo, tool, memoria, guardrail | We.Inc

Crea un agente AI partendo dalle basi: il ciclo decidi, agisci, osserva, le definizioni dei tool, la memoria, i limiti di passi, l'approvazione umana e i test. Include un simulatore di passi.

Come creare un agente AI

Un agente AI è un ciclo. Un modello linguistico legge l'obiettivo e tutto ciò che è successo finora, poi chiama uno dei tool che hai definito oppure dà una risposta finale. Il tuo codice esegue il tool, aggiunge il risultato e chiede di nuovo. Limiti di passi, permessi, approvazione umana e test mantengono sicuro quel ciclo.

Le cinque parti di un agente

  • Parte
  • Cosa costruisci
  • Cosa va storto senza
  • Ciclo
  • Codice che chiama il modello, esegue i tool e ripete
  • Non succede niente dopo la prima risposta
  • Tool
  • Funzioni con nome, descrizione e schema di input
  • Il modello può solo parlare, non agire
  • Memoria
  • La trascrizione in corso, più eventuali note salvate tra un'esecuzione e l'altra
  • Il modello ripete chiamate già fatte
  • Guardrail
  • Limiti di passi e di costo, privilegio minimo, approvazione per le azioni rischiose
  • Cicli fuori controllo, bollette a sorpresa, azioni dannose
  • Valutazione
  • Task di test fissi con controlli da rieseguire dopo ogni modifica
  • Scopri le regressioni dagli utenti

Avvia il simulatore per seguire un task attraverso il ciclo. Attiva e disattiva l'approvazione per vedere dove un guardrail interrompe un passo rischioso. La traccia è predefinita così puoi studiarla; un'esecuzione reale interrogherebbe un modello a ogni passo di decisione.

  • Premi Passo successivo per avanzare nel ciclo una mossa alla volta.
  • Leggi ogni riga: decidi è il modello che sceglie, agisci è il tuo codice che esegue un tool, osserva è il risultato che viene aggiunto alla memoria.
  • Attiva o disattiva l'approvazione per send_email ed eseguilo di nuovo per confrontare le due tracce.
  • Premi Reimposta per ricominciare.
  • Inizia con un tool e un task. Aggiungi tool solo quando un task di test fallisce perché ne manca uno, perché ogni tool in più è un'altra scelta che il modello può sbagliare.
  • Rendi i risultati dei tool brevi e concreti. L'intera trascrizione torna al modello a ogni passo, quindi risultati lunghi costano denaro e seppelliscono ciò che conta.
  • Metti i controlli sui permessi nel codice del tool, non nelle istruzioni. Un modello può essere convinto a ignorare un'istruzione; non può aggirare un controllo imposto dalla tua funzione.
  • Registra ogni passo con input, output e costo. Quando un'esecuzione va storta, il log è l'unico modo per capire quale decisione era sbagliata.

Domande frequenti

Mi serve un framework per creare un agente?

No. Il nucleo è un ciclo while attorno a una chiamata al modello e uno switch sui nomi dei tool, come mostra l'esempio in questa pagina. I framework aggiungono retry, tracing e integrazioni, utili più avanti ma che nascondono il ciclo mentre impari.

Come fa il modello a chiamare un tool?

Invii le definizioni dei tool con ogni richiesta. Quando il modello ne vuole usare uno, risponde con il nome del tool e gli argomenti invece che con testo semplice. Il tuo codice esegue la funzione e rimanda il risultato come messaggio successivo.

Qual è la differenza tra memoria e contesto?

Il contesto è ciò che il modello vede in questa chiamata: istruzioni, obiettivo e trascrizione finora. La memoria è tutto ciò che salvi e decidi di rimettere nel contesto più tardi, come le note di un'esecuzione precedente.

Come impedisco a un agente di girare all'infinito?

Limita il numero di passi e la spesa totale, e chiudi l'esecuzione con un messaggio chiaro quando uno dei due limiti viene raggiunto. OWASP elenca Unbounded Consumption tra i rischi 2025 per le applicazioni basate su modelli linguistici.

Come testo un agente?

Scrivi un insieme di task fissi con risultati verificabili: è stato chiamato il tool giusto, un'azione rischiosa ha atteso l'approvazione, la risposta finale contiene una cifra. Esegui l'insieme dopo ogni modifica al prompt o ai tool e confronta il numero di task superati.

Guardrail che reggono davvero

  • La lista OWASP 2025 indica Excessive Agency come rischio centrale e lo riconduce a tre cause: funzionalità eccessive, permessi eccessivi e autonomia eccessiva. Ognuna corrisponde a una correzione che controlli nel codice.
  • Dai all'agente solo i tool che servono al task, dai a ogni tool le credenziali più ristrette che funzionano, e richiedi che una persona approvi le azioni ad alto impatto come inviare, pagare o eliminare. Verifica l'autorizzazione nel sistema chiamato dal tool invece di fidarti che il modello si comporti bene.

Il testo non attendibile è la principale superficie di attacco

  • Qualsiasi cosa un tool recuperi, come una pagina web, un'email o un file, può contenere istruzioni rivolte al tuo modello. OWASP la chiama prompt injection indiretta.
  • Contrassegna chiaramente il contenuto recuperato come dati, tienilo separato dalle tue istruzioni e non lasciare mai che il testo di un risultato sblocchi da solo un tool più potente. L'approvazione umana per i passi privilegiati è l'ultima difesa quando le altre falliscono.

Il ciclo in JavaScript puro

Nessun framework e nessun SDK di un fornitore. callModel è uno stub che riproduce decisioni fisse così il file gira così com'è; sostituiscilo con una richiesta al servizio di modelli che usi.

I tool stanno in un unico oggetto, quelli rischiosi richiedono approvazione, e il ciclo si ferma a un limite di passi. Eseguilo con node agent.mjs.

Rischi da considerare nel design

Le voci di OWASP Top 10 for LLM Applications 2025 più rilevanti per gli agenti

  • Rischio
  • Come si manifesta in un agente
  • Correzione nel codice
  • LLM01:2025 Prompt Injection
  • Una pagina recuperata dice al modello di inviare i tuoi dati via email altrove
  • Separa il contenuto non attendibile, approva le azioni privilegiate
  • LLM06:2025 Excessive Agency
  • L'agente può eliminare record che doveva solo leggere
  • Meno tool, credenziali ristrette, approvazione per l'alto impatto
  • LLM10:2025 Unbounded Consumption
  • Un ciclo riprova un tool che fallisce per tutta la notte
  • Limite di passi, limite di spesa, timeout, rate limit
  • LLM05:2025 Improper Output Handling
  • L'output del modello finisce in SQL o HTML senza controlli
  • Valida ed esegui l'escape prima di qualsiasi uso a valle

Obiettivo: trovare il più economico tra tre preventivi di fornitori e inviare il riepilogo via email al responsabile d'ufficio.

Il modello sceglie read_quotes per vedere cosa è arrivato.

Il codice esegue read_quotes() e restituisce tre file.

Risultato aggiunto alla memoria: A $1,240, B $1,180, C $1,315.

Il modello ha ciò che gli serve e sceglie send_email con una bozza di riepilogo.

send_email è segnato come ad alto impatto, quindi l'esecuzione si mette in pausa perché una persona approvi la bozza.

Approvato. Il codice esegue send_email() con il testo approvato.

Risultato aggiunto alla memoria: messaggio inviato.

Il modello restituisce una risposta finale: il preventivo B è il più economico a $1,180; riepilogo inviato. 3 chiamate al modello, sotto il limite di 10 passi.

Il modello sceglie read_quotes per vedere cosa è arrivato.

Il codice esegue read_quotes() e restituisce tre file.

Risultato aggiunto alla memoria: A $1,240, B $1,180, C $1,315.

Il modello ha ciò che gli serve e sceglie send_email con una bozza di riepilogo.

Nessuna regola di approvazione, quindi il codice invia subito la bozza. Nessuno l'ha vista prima.

Risultato aggiunto alla memoria: messaggio inviato.

Il modello restituisce una risposta finale. Questa volta ha funzionato, ma anche una cifra sbagliata o un'istruzione iniettata sarebbe partita senza controlli.

Decidi

Agisci

Osserva

Guardrail

Fatto

Simulatore del ciclo dell'agente

Passo successivo

Reimposta

Richiedi approvazione prima di send_email

Passo {n} di {v}

Esecuzione terminata.

non ancora raggiunto

Inizia la prova gratuita · Prova gratuita di 7 giorni, $0 oggi

Correlati: Guide

Prodotto

Per chi è

Funzionalità

Risorse

Azienda

Mappa del sito