Agenti AI: come funziona il ciclo e quando fermarlo

Il modello propone l'azione successiva. Il software decide se autorizzarla, registra ciò che è accaduto e stabilisce se consentire un'altra chiamata al modello. Questa divisione delle responsabilità è il punto di partenza sia per costruire un primo agente sia per capire perché uno già in uso non si è fermato.

Il comportamento dei framework descritto qui è stato verificato sulla documentazione ufficiale disponibile online il 24 ottobre 2026. Il confronto mette in relazione le diverse unità di conteggio e i punti in cui intervengono i controlli. Gli esempi sui ticket di assistenza e le regole proposte sono illustrativi: non sono risultati misurati in produzione.

Come funziona il ciclo di esecuzione degli agenti AI

Il ciclo utile è chiamata al modello → chiamata a uno strumento → osservazione → ripetizione, con un'uscita ogni volta che proseguire è superfluo o non consentito.

Si può immaginare un coordinatore che assegna il lavoro a un tecnico. Il coordinatore sceglie il prossimo intervento, il tecnico lo esegue e il rapporto che restituisce orienta la decisione successiva. Chiedere di ispezionare una macchina non equivale ad averla ispezionata; un messaggio rassicurante non dimostra che la riparazione sia riuscita.

Nel software, il coordinatore è un modello linguistico di grandi dimensioni, o LLM. Il tecnico è uno strumento: una funzione che legge un database, cerca documenti, esegue un comando o modifica un record. Il runtime è il codice che li collega.

Per un ipotetico compito di preparazione della risposta a un ticket, la traccia potrebbe essere questa: la prima chiamata al modello richiede il ticket, la seconda cerca la procedura pertinente, la terza restituisce una bozza basata su entrambi. Sono 3 chiamate al modello e 2 esecuzioni di strumenti, all'interno di una sola richiesta all'applicazione. Se l'invio richiede un'approvazione, la stesura può essere conclusa mentre l'invio resta in attesa.

Lo stato del compito va tenuto separato dalla trascrizione della conversazione. Deve indicare quale ticket si sta gestendo, quale procedura è stata accettata, se esiste una bozza e se l'invio è autorizzato. La trascrizione spiega come si è arrivati a quel punto. Chiedere ogni volta al modello di ricostruire tutto da una conversazione sempre più lunga rende il lavoro più difficile da supervisionare.

Che cosa aggiunge un agente con un ciclo adattivo

Un agente con un ciclo adattivo può scegliere l'azione successiva in base all'ultimo risultato. Un flusso fisso conosce già la sequenza: recuperare il ticket, recuperare la procedura, produrre la bozza. Il ciclo adattivo serve quando la prossima azione utile dipende da ciò che ha rivelato la precedente. Se questa incertezza non c'è, conviene usare la sequenza fissa.

Dove si colloca il ciclo ReAct

Il ciclo ReAct collega ragionamento e azione: il modello usa le osservazioni per orientare le azioni successive. Il progetto ReAct originale descrive l'alternanza tra ragionamento e azioni in un ambiente. Per monitorare l'applicazione, bisogna registrare le azioni richieste, le osservazioni e gli esiti. Un resoconto dei progressi non sostituisce una conferma di esecuzione.

Le tre condizioni di arresto necessarie in produzione

Occorre progettare tre uscite intenzionali: completamento, esaurimento dei limiti e necessità di un intervento umano. Sono categorie progettuali: non significa che ogni SDK esponga gli stessi tre interruttori. Anche i crash, le cancellazioni e gli errori irrecuperabili richiedono una gestione esplicita del fallimento.

Fermarsi quando il compito è concluso

Il significato di «concluso» va definito prima della prima chiamata al modello. Per un assistente che prepara bozze, può bastare una bozza valida con i riferimenti alle fonti pertinenti. Per un assistente che compie azioni, potrebbe servire anche una conferma dell'avvenuta scrittura.

Bisogna distinguere tra «il modello ha smesso di richiedere strumenti» e «il lavoro richiesto è riuscito». Il primo è un segnale del runtime. Il secondo richiede riscontri specifici per quel compito. Un modello può fermarsi perché non riesce a proseguire: l'applicazione deve registrare il lavoro come bloccato o incompleto, senza presentarlo come riuscito.

Se una risposta non supera la validazione, il ciclo non deve ripartire automaticamente. Un tentativo di correzione deve consumare il margine ancora disponibile per lo stesso compito; altrimenti anche il validatore può diventare una fonte di tentativi senza fine.

Fermarsi quando si raggiunge un limite

Servono limiti indipendenti per passaggi, consumo di risorse e tempo trascorso. Un tetto ai passaggi limita le ripetizioni. Un budget di token o di spesa limita i consumi. Una scadenza impedisce a un modello o a uno strumento lento di tenere aperto il lavoro a tempo indeterminato. Nessuno di questi controlli sostituisce gli altri.

I limiti vanno verificati prima di avviare nuovo lavoro; i consumi vanno aggiornati quando quel lavoro termina. Un contatore delle chiamate concluse non può impedire a una richiesta già in corso di consumare risorse. Se l'applicazione promette un tetto rigido, deve riservare capacità per l'operazione successiva e tenere conto del lavoro concorrente prima di avviarla.

I limiti devono riguardare l'intero compito applicativo, non soltanto una chiamata all'SDK. Un nuovo tentativo, la ripresa dopo un'approvazione o un agente figlio non devono creare implicitamente una nuova dotazione di risorse. Se serve altro lavoro, l'applicazione deve decidere esplicitamente di aumentarla.

Human in the loop: mettere in pausa l'agente prima dell'azione

Un agente AI con supervisione umana, o human in the loop, deve fermarsi prima dell'operazione che richiede approvazione. Occorre mostrare l'azione proposta, il suo destinatario o oggetto e gli argomenti rilevanti. Poi si salvano la chiamata in sospeso e lo stato attuale del compito, in attesa di una decisione esplicita.

Per l'assistente che gestisce i ticket, va approvata quella precisa risposta destinata a quel preciso destinatario. L'approvazione di una bozza non deve trasformarsi in un permesso generale per i messaggi successivi. Se dopo l'approvazione il modello cambia il destinatario o il contenuto, l'azione va valutata di nuovo.

Una pausa va registrata come awaiting_approval, non come completed. Un rifiuto deve portare a un'alternativa definita o all'arresto. Non deve innescare tentativi ripetuti di eseguire la stessa operazione con un altro strumento. La guida alla supervisione umana tratta le code di approvazione e le procedure di escalation.

Un ciclo minimo in pseudocodice

Il ciclo resta semplice quando i controlli sulle regole precedono e seguono ogni operazione. Questo è pseudocodice, non codice SDK eseguibile. Il limite di 8 chiamate al modello è una scelta applicativa puramente illustrativa: i limiti effettivi vanno scelti in base al compito e alle tracce osservate.

state = new_job(task, max_model_calls=8, budget, deadline)

while true:
    if limit_reached(state):
        return stop("limit", partial_result=state)

    reserve_capacity_or_stop(state, next_model_call)
    response = call_model_with_deadline(state)
    record_model_call_usage_and_response(state, response)

    if response.is_final and not response.tool_calls:
        return validate_and_finish_or_stop_incomplete(response, state)

    if not response.tool_calls:
        return stop("no_action", partial_result=state)

    for index, call in enumerate(response.tool_calls):
        decision = validate_and_authorize(call, state)
        if decision == "denied":
            return stop("denied", partial_result=state)
        if decision == "needs_human":
            return pause_and_save(state, response.tool_calls[index:])

        reserve_capacity_or_stop(state, call)
        observation = execute_with_timeout_and_retry_cap(call)
        record_tool_usage(state, observation)
        append_matching_tool_result(state, call, bounded(observation))

    if no_progress(state):
        return stop("stalled", partial_result=state)

I nomi delle funzioni ausiliarie implicano responsabilità precise. Le prenotazioni di capacità devono tenere conto del lavoro già in corso. I nuovi tentativi degli strumenti devono avere un limite. Dopo un timeout che lascia incerto l'esito di una scrittura, occorre fermarsi o accertarne l'esito prima di riprovare. Un errore fatale del modello o di uno strumento deve terminare l'esecuzione registrando il fallimento, senza lasciar proseguire il ciclo.

Quando si salva una pausa, bisogna conservare le chiamate agli strumenti ancora da eseguire, i risultati già ottenuti e le risorse già consumate. Alla ripresa si continua quel lavoro salvato, verificando di nuovo autorizzazioni e limiti. Ricominciare l'intero compito può ripetere effetti già prodotti.

Conta anche la posizione dei controlli: l'approvazione precede l'esecuzione dello strumento, la contabilizzazione dei consumi segue il lavoro completato e l'iterazione successiva non può partire solo perché il modello l'ha richiesta.

Come i framework gestiscono il ciclo

OpenAI Agents SDK, Claude Agent SDK, Vercel AI SDK e LangGraph implementano il ciclo in modi diversi. Prima di confrontare i nomi delle opzioni, occorre confrontare le unità di conteggio e i punti in cui l'esecuzione può fermarsi.

Questi nomi provengono dalle rispettive documentazioni: ciclo di OpenAI, ciclo di Claude, ciclo di Vercel e Graph API di LangGraph. I riferimenti sul comportamento delle approvazioni si trovano nelle sezioni seguenti.

OpenAI Agents SDK: è il Runner a gestire la prosecuzione

OpenAI Agents SDK è un framework il cui Runner chiama il modello, esegue gli strumenti richiesti, aggiunge i risultati e prosegue. Un handoff cambia l'agente attivo e continua l'esecuzione. La conclusione normale documentata consiste in un output del tipo atteso senza chiamate agli strumenti; il superamento di max_turns genera MaxTurnsExceeded, salvo gestione esplicita. Documentazione OpenAI sull'esecuzione degli agenti.

Per un assistente che gestisce ticket, questo offre un punto chiaro in cui limitare i turni del modello. Resta però la distinzione tra un'esecuzione conclusa e un'azione applicativa completata: occorre definire i requisiti dell'output e verificare i riscontri richiesti dal compito.

Per le approvazioni, gli strumenti Python possono dichiarare needs_approval; le chiamate in sospeso compaiono in interruptions. Si salva il RunState, si applica l'approvazione o il rifiuto e si riprende. Un'esecuzione in pausa non è una nuova richiesta dell'utente. Documentazione OpenAI sulla supervisione umana.

Il ciclo di Claude: limitare sia i turni sia la spesa

Claude Agent SDK incorpora il ciclo che fa funzionare Claude Code, compresi gli strumenti per file e comandi. L'opzione maxTurns conta i turni di utilizzo degli strumenti; maxBudgetUsd imposta una soglia di spesa stimata. Se non vengono impostati, entrambi i valori sono illimitati. In Python i nomi sono max_turns e max_budget_usd. Documentazione del ciclo di Claude.

Va controllato il sottotipo del risultato: success, error_max_turns e error_max_budget_usd indicano esiti diversi. In modalità single-shot, un risultato di errore è seguito da un'eccezione: vanno quindi gestiti sia il risultato sia il percorso di errore. Gestione dei risultati in Claude.

I confini delle autorizzazioni richiedono la stessa attenzione. allowedTools approva automaticamente gli strumenti elencati; omettere uno strumento dall'elenco non lo rimuove. Nella modalità predefinita dei permessi, le chiamate che richiedono approvazione e non corrispondono ad alcuna regola di autorizzazione arrivano a canUseTool. Prima di usare questo SDK per scritture non supervisionate, va verificata l'intera politica dei permessi. Permessi di Claude.

Per contabilizzare anche gli agenti figli, Claude distingue usage, relativo al ciclo principale, da modelUsage, che copre l'intero albero di agenti, o model_usage in Python. Per analizzare i consumi di un compito bisogna usare il totale appropriato. Documentazione di Claude su costi e consumi.

Per l'implementazione passo passo, si può partire dalla guida a Claude Agent SDK pubblicata sul sito.

Vercel AI SDK: stopWhen controlla il passaggio successivo

Vercel AI SDK espone il controllo della prosecuzione tramite stopWhen. La documentazione attuale usa isStepCount per limitare i passaggi e consente più condizioni: basta che una sia soddisfatta perché l'esecuzione si fermi. Il valore predefinito di ToolLoopAgent è 20 passaggi, mentre generateText e streamText prevedono di default una sola generazione. Il punto di ingresso scelto conta. Controllo del ciclo in Vercel, documentazione sulle chiamate agli strumenti.

Un passaggio comprende una generazione e le relative esecuzioni locali degli strumenti. Il punto decisivo è che stopWhen viene valutato quando l'ultimo passaggio contiene risultati degli strumenti. Non può annullare il lavoro degli strumenti che ha prodotto quei risultati. È quindi un controllo sulla prosecuzione, non un'approvazione preventiva dell'azione. Chiamate su più passaggi in Vercel.

Per ottenere un'approvazione esplicita dell'utente va usato il meccanismo documentato toolApproval. La documentazione attuale indica come deprecata la precedente proprietà needsApproval degli strumenti. Approvazione degli strumenti in Vercel.

Per gestire il contesto, prepareStep viene eseguito prima di ogni passaggio e può modificare messaggi o impostazioni. È il punto in cui fornire lo stato pertinente, evitando di trascinare ogni volta tutti i risultati grezzi. prepareStep in Vercel.

LangGraph e il ciclo degli agenti LangChain

LangGraph è un runtime a grafo: si collegano nodi, che svolgono il lavoro, e archi, che determinano che cosa verrà eseguito dopo. Per un ciclo di agente LangChain costruito su un grafo, occorre definire esplicitamente sia il percorso di ritorno al modello sia quello verso END. In Python, recursion_limit limita i super-step del grafo; i nodi eseguiti in parallelo condividono lo stesso super-step. Non è un contatore delle chiamate agli strumenti. Graph API di LangGraph.

recursion_limit va impostato al livello principale della configurazione di invocazione, non dentro configurable. Quando si raggiunge il limite viene generato GraphRecursionError; normalmente, un percorso di completamento progettato apposta dovrebbe concludersi prima di questa uscita di emergenza. Limite di ricorsione di LangGraph.

Per la revisione umana, interrupt() mette in pausa il grafo. Servono un checkpointer e un thread_id stabile; poi si riprende con Command(resume=...). Il vincolo da tenere presente è che la ripresa riavvia dall'inizio il nodo interrotto. Il codice prima dell'interruzione può quindi essere eseguito di nuovo. Gli effetti vanno collocati dopo l'approvazione oppure resi idempotenti, cioè tali che ripetere l'esecuzione non produca effetti aggiuntivi. Interruzioni in LangGraph.

Questa struttura esplicita a grafo è adatta quando le diramazioni e lo stato ripristinabile sono centrali per il compito. Per un primo assistente in sola lettura con un ciclo semplice di strumenti, conviene partire dal runtime più piccolo che soddisfa i requisiti.

Perché un'esecuzione arriva a 40 passaggi

Prima di alzare il limite, bisogna capire che cosa è cambiato da un passaggio all'altro. Un'esecuzione lunga può essere lavoro utile, un errore ripetuto oppure una ripartenza che ha perso traccia di ciò che era già stato fatto. Il numero, da solo, non permette di distinguere questi casi.

Cicli infiniti: ripetere senza ottenere nuovi riscontri

Un agente che gestisce ticket può cercare una procedura, ricevere un risultato vuoto e ripetere la stessa ricerca. L'osservazione successiva non aggiunge nulla, quindi la decisione seguente può riprodurre la stessa azione.

Vanno registrati il nome e gli argomenti dello strumento in forma normalizzata, un'impronta del risultato e un indicatore di avanzamento del compito. Una ripetizione senza cambiamenti di stato deve far scattare un controllo di stallo. Anche un polling legittimo può ripetersi: occorre dargli regole e limiti propri, invece di trattare ogni duplicato come un errore.

Prima di riprovare bisogna cambiare qualcosa: un termine di ricerca, un identificativo mancante, una fonte di dati disponibile o l'ambito del compito. Se non è possibile cambiare nulla di utile, va segnalato il requisito ancora irrisolto oppure chiesto aiuto. «Riprova» non è, da solo, una strategia di recupero.

Errori degli strumenti: distinguere un guasto recuperabile da un esito incerto

Un argomento malformato, un permesso negato e un disservizio temporaneo richiedono risposte diverse. Bisogna restituire un errore conciso su cui il modello possa intervenire. I tentativi di recupero devono avere un limite; se un errore non può essere risolto con i permessi del compito, ci si deve fermare subito.

Un timeout durante una scrittura è più delicato: la scrittura potrebbe essere riuscita anche se la risposta non è mai arrivata. Prima di reinviare un messaggio a un cliente o creare un altro record, occorre interrogare lo stato dell'operazione oppure usare una chiave di idempotenza, cioè un identificativo stabile che permetta al servizio di riconoscere la stessa operazione richiesta.

Durante il recupero va preservato il lavoro riuscito. Se la lettura del ticket è andata a buon fine ma il recupero della procedura è fallito, rieseguire l'intero compito aggiunge lavoro e può ripetere effetti già prodotti.

Contesto che cresce: conservare le decisioni, non ogni dato grezzo

Nella chiamata successiva al modello, ogni osservazione compete per l'attenzione con le istruzioni del compito e i riscontri precedenti. Una risposta molto grande di uno strumento può essere tecnicamente valida e, allo stesso tempo, rendere meno mirata la decisione successiva.

Occorre limitare gli output degli strumenti, archiviare gli artefatti di grandi dimensioni fuori dal prompt e restituire un risultato compatto con un riferimento che permetta di recuperarli. Vincoli accettati, approvazioni e azioni confermate vanno mantenuti nello stato persistente dell'applicazione. Un riepilogo può descrivere questi dati, ma non deve diventarne l'unica copia.

L'SDK di Claude documenta la compattazione automatica in prossimità del limite di contesto e avverte che le istruzioni iniziali possono andare perse nel riepilogo. È un motivo per conservare esplicitamente lo stato critico. Compattazione in Claude. La spiegazione del context rot chiarisce perché rientrare nella finestra di contesto non garantisca di recuperare le informazioni utili.

Una traccia che risponda alle domande di chi gestisce il sistema

Per ogni compito vanno registrati l'identificativo, il numero di chiamate al modello, i tentativi degli strumenti, i consumi, il tempo trascorso, le approvazioni in sospeso e il motivo dell'arresto. Per ogni operazione bisogna registrare che cosa è stato richiesto, che cosa è stato completato e se lo stato del compito è cambiato.

I contatori delle richieste al modello, delle esecuzioni degli strumenti e dei passaggi del runtime devono restare separati. Una dashboard che mostra «40 passaggi» senza specificare l'unità non spiega l'esecuzione. Il conteggio del compito principale deve includere anche il lavoro degli agenti figli e i nuovi tentativi. La guida all'orchestrazione degli agenti AI spiega come attribuire le responsabilità quando il lavoro passa da un agente all'altro.

Quali aspettative sugli agent loop sono eccessive?

Più iterazioni non dimostrano più progressi. Un ciclo offre occasioni ripetute di usare il feedback; sono la qualità di quel feedback e la definizione di successo a determinare se ripetere sia utile.

Un modello che dice «fatto» ha concluso la propria parte dello scambio. Un tetto ai passaggi dimostra che l'esecuzione aveva un limite. Nessuno dei due dimostra che una risposta di assistenza sia corretta o che una modifica richiesta sia stata effettuata.

Nemmeno l'uso di un framework elimina la necessità di definire permessi, persistenza e recupero dagli errori. Il framework fornisce i meccanismi di esecuzione. L'applicazione stabilisce che cosa significhi riuscire e chi abbia l'autorità per agire.

Il ciclo di test dell'agente è un compito distinto

Il ciclo di test di un agente ne valuta il comportamento rispetto a casi e criteri di accettazione. Può racchiudere il ciclo di esecuzione in un processo di verifica che accetta il risultato oppure invia feedback per un altro tentativo. La spiegazione del loop engineering di LangChain distingue l'esecuzione dalla verifica e dal lavoro attivato da eventi.

Anche il verificatore deve avere dei limiti. Chiedere ripetutamente a un altro modello se una risposta è buona può esaurire le risorse disponibili senza produrre riscontri decisivi. Dove possibile, vanno preferiti controlli concreti: i campi richiesti esistono, i record citati corrispondono, è presente una conferma di scrittura oppure un test previsto viene superato.

Da dove partire per sviluppare e gestire gli agenti

Per chi sta costruendo il primo agente: partire da un compito circoscritto in sola lettura, criteri espliciti di completamento e operazioni con limiti definiti. Le scritture si possono aggiungere quando è possibile mostrare l'azione proposta, far rispettare l'autorizzazione e gestire un risultato ambiguo. Se la sequenza è già nota, può bastare un flusso fisso.

Per chi sta analizzando un'esecuzione costosa: controllare le chiamate ripetute, le catene di nuovi tentativi e le osservazioni che crescono prima di cambiare modello o alzare i limiti. Bisogna capire quale passaggio abbia aggiunto riscontri utili e quale contatore abbia effettivamente fermato il compito.

Per i team che hanno un flusso fisso affidabile: mantenerlo finché la scelta adattiva degli strumenti non risolve un problema concreto. Un ciclo aggiunge valore quando i risultati intermedi determinano l'azione successiva; la sola ripetizione non giustifica una riprogettazione.

Il primo intervento da mettere in agenda: prendere un compito rappresentativo e provarne il percorso di completamento, l'uscita al raggiungimento del limite, la pausa per approvazione, l'azione negata e il percorso di errore di uno strumento. Verificare che ogni caso lasci uno stato chiaro e che la ripresa conservi sia il lavoro già concluso sia le risorse ancora disponibili.

Domande frequenti sul ciclo degli agenti AI

Per guide pratiche su come costruire e gestire sistemi AI, iscriviti alla newsletter.