Prima di eseguire il debug di un ciclo AutoGen, è importante conoscere un cambiamento di piattaforma. A partire da settembre 2026, il repository ufficiale di AutoGen è in modalità di manutenzione: si prevede che riceverà aggiornamenti di manutenzione anziché nuove funzionalità e Microsoft consiglia di utilizzare Microsoft Agent Framework per i nuovi progetti. Il repository ufficiale di AutoGen indica ancora Python 0.7.5 come versione stabile corrente, mentre Microsoft ha pubblicato una guida aggiornata alla migrazione da AutoGen ad Agent Framework il 25 agosto 2026. Tuttavia, se si utilizza già AutoGen in produzione, le tecniche di risoluzione dei problemi descritte di seguito rimangono direttamente utili. Consultare il repository ufficiale di AutoGen , le release ufficiali di AutoGen e la guida alla migrazione di AutoGen di Microsoft .
Un agente AutoGen di solito sembra "bloccato in un ciclo infinito" per uno dei cinque motivi seguenti: l'esecuzione non ha una condizione di terminazione affidabile, la policy del prossimo relatore continua a scegliere un partecipante improduttivo, una chiamata di strumento non crea progressi osservabili, gli agenti si passano il lavoro avanti e indietro, oppure l'applicazione continua a riprendere uno stato obsoleto. La soluzione più rapida non è riscrivere ogni prompt. Innanzitutto, identifica il ciclo effettivamente presente, quindi aggiungi un punto di arresto forzato e infine ripara la transizione che non funziona.
| Sintomo | Probabile causa | La prima cosa da controllare |
|---|---|---|
| Gli stessi due agenti si alternano indefinitamente | Instradamento o passaggio di consegne ping-pong | Selezione dell'oratore, obiettivi di trasferimento e limite massimo di messaggi o turni |
| Un agente chiama ripetutamente lo stesso strumento con argomenti pressoché identici | Il risultato dello strumento non dimostra né il progresso né il fallimento | max_tool_iterations, schema di ritorno dello strumento e logica di ripetizione |
| Il team continua a parlare anche dopo che il compito è visibilmente completato. | Il completamento è solo implicito nel prompt | Condizione di terminazione esplicita e segnale di completamento deterministico |
| Un selezionatore sceglie ripetutamente lo specialista sbagliato | Descrizioni ambigue degli agenti o prompt di selezione | Descrizioni dei partecipanti, insieme dei candidati eallow_repeated_speaker |
| Un nuovo compito sembra ereditare il comportamento del compito precedente | Lo stato è stato preservato intenzionalmente | Se il team o l'agente debbano essere ripristinati prima del nuovo compito. |
| Un flusso di lavoro grafico si ripete all'infinito attraverso le fasi di revisione e riscrittura. | La condizione di uscita non diventa mai vera | Premessa di uscita dal ciclo più terminazione di sicurezza indipendente |
AutoGen AgentChat fornisce condizioni di terminazione integrate specificamente per mantenere i team vincolati. La documentazione stabile include MaxMessageTermination, TextMentionTermination, TokenUsageTermination, TimeoutTermination, HandoffTermination, SourceMatchTermination, ExternalTermination, StopMessageTermination, TextMessageTermination, FunctionCallTermination, e FunctionalTermination. Consulta la documentazione ufficiale di terminazione di AutoGen .
Per la maggior parte dei flussi di lavoro di produzione, si utilizza una condizione di completamento semantica e un limite di sicurezza indipendente. L'operatore importante è solitamente OR, perché si desidera che l'esecuzione si interrompa quando l'attività termina normalmente o quando viene raggiunto il limite di sicurezza.
from autogen_agentchat.conditions import (
MaxMessageTermination,
TextMentionTermination,
)
done = TextMentionTermination("TERMINATE")
safety_cap = MaxMessageTermination(max_messages=25)
termination = done | safety_cap
Un errore comune è affidarsi solo a "di' TERMINATE quando hai finito". Questo lascia la correttezza al comportamento del modello. Un altro errore è combinare le condizioni &quando in realtà si intende "fermati in entrambi i casi". AutoGen supporta sia la composizione AND che OR, quindi scegli la semantica con attenzione.
Un limite massimo è un interruttore, non una prova che il flusso di lavoro sia corretto. Se l'esecuzione si interrompe sempre perché raggiunge il limite, significa che c'è ancora un problema di logica da risolvere.
Il segnale di terminazione più forte è quello che la tua applicazione può riconoscere senza interpretare il testo. Se il flusso di lavoro ha un evento di successo chiaro, usa la condizione di terminazione più simile. Ad esempio, un passaggio di consegne specifico può essere rilevato con HandoffTermination, il completamento di uno strumento particolare può essere rilevato con FunctionCallTerminatione la logica personalizzata può essere espressa con FunctionalTermination.
Se si utilizza TextMentionTermination("TERMINATE"), è necessario esplicitare la responsabilità: quale agente è autorizzato a dichiarare il completamento e in base a quali condizioni verificate? Evitare di dare a tutti i partecipanti istruzioni vaghe come "continuare fino a quando non si è soddisfatti". Questo tipo di istruzione può generare un comportamento infinito di critica e riscrittura perché il concetto di "soddisfatto" non ha un limite osservabile.
Un contratto di completamento utile è concreto: "Il revisore emette TERMINATO solo dopo che la bozza contiene tutte e tre le sezioni richieste e non rimangono ostacoli aperti". Meglio ancora, quando possibile, si dovrebbe fare in modo che il revisore produca uno stato strutturato che l'applicazione possa verificare.
SelectorGroupChatUtilizza un modello per scegliere il prossimo interlocutore dal contesto di conversazione condiviso. La documentazione stabile sottolinea che i nomi e le descrizioni dei partecipanti sono importanti perché vengono utilizzati nella selezione dell'interlocutore. Per impostazione predefinita, lo stesso interlocutore non viene selezionato consecutivamente a meno che non sia l'unico agente disponibile, sebbene allow_repeated_speaker=Truesia possibile modificare questo comportamento. AutoGen fornisce anche selector_funce quando è necessario un controllo più deterministico. Consultare la documentazionecandidate_func ufficiale di SelectorGroupChat .
Se viene selezionato sempre lo stesso partecipante, controlla questi elementi in ordine:
allow_repeated_speakerdisattivata a meno che non siano effettivamente necessari turni consecutivi.selector_funcquando il flusso di lavoro è in realtà una macchina a stati mascherata da conversazione.La distinzione fondamentale è semplice: utilizzare la selezione del relatore basata su LLM quando il relatore successivo richiede effettivamente un giudizio semantico. Utilizzare l'instradamento deterministico quando il relatore successivo è determinato dallo stato del flusso di lavoro.
Nell'attuale AgentChat, AssistantAgentè presente un max_tool_iterationsparametro. La documentazione API stabile afferma che il valore predefinito è 1; aumentandolo, l'agente può effettuare ulteriori chiamate sequenziali agli strumenti finché il modello non restituisce una risposta testuale o non viene raggiunto il numero massimo. Ciò significa che una singola esecuzione dell'agente è limitata da questa impostazione, ma lo stesso agente può comunque essere selezionato nuovamente da un team e ripetere lo stesso schema di strumenti falliti nei turni successivi. Consultare la documentazione ufficiale dell'API AssistantAgent .
agent = AssistantAgent(
name="worker",
model_client=model_client,
tools=[lookup_tool],
max_tool_iterations=3,
)
Se si vedono sempre gli stessi strumenti e argomenti, ridurre il limite di iterazioni serve solo a contenere i danni. La soluzione alla radice di solito risiede nel contratto dello strumento. Il modello ha bisogno di informazioni sufficienti per stabilire se la chiamata ha avuto successo, è fallita in modo permanente, è fallita temporaneamente o non ha prodotto nuove informazioni.
Preferirei un risultato compatto ed esplicito come:
{
"status": "no_new_data",
"query": "customer_123",
"retryable": false,
"reason": "record already checked",
"next_action": "return_to_planner"
}
Questo è più utile di una stringa generica come "Nessun risultato" perché il modello può capire che ripetere la stessa chiamata non rappresenta un progresso. Per gli strumenti che generano effetti collaterali, è inoltre necessario aggiungere l'idempotenza a livello di applicazione, in modo che una chiamata ripetuta non possa creare ripetutamente lo stesso ticket, pagamento, messaggio o modifica del database.
La AssistantAgentdocumentazione di riferimento stabile indica che più chiamate di strumenti possono essere eseguite contemporaneamente e che le chiamate di strumenti parallele possono essere disabilitate nei client del modello supportati. Avverte inoltre che, se vengono rilevati più passaggi di consegne, ne viene eseguito solo il primo e raccomanda di disabilitare le chiamate di strumenti parallele per evitare questa situazione. Se il flusso di lavoro presuppone transizioni di stato rigorose, una azione alla volta, le chiamate parallele possono rendere più difficile l'interpretazione dello stato risultante.
Un ciclo di handover di solito si presenta così: l'agente A decide che l'agente B è più adatto, l'agente B rileva un contesto incompleto e rimanda indietro il compito, ed entrambe le scelte rimangono localmente ragionevoli per sempre. Il problema non è che uno dei due modelli sia "sbagliato". La politica di handover manca di un responsabile e di uno stato terminale.
Risolvete il problema specificando una condizione precisa per ogni passaggio di consegne e una regola per ciò che accade quando il destinatario non può procedere. Per i flussi di lavoro interattivi con l'utente, il sistema HandoffTermination(target="user")è progettato per interrompere il team quando il controllo deve tornare all'applicazione o alla persona. La documentazione di AutoGen relativa al coinvolgimento umano spiega anche che i flussi di lavoro Swarm necessitano di un comportamento di ripresa deliberato dopo un passaggio di consegne da parte dell'utente. Consultate la documentazione ufficiale sul coinvolgimento umano .
Un buon contratto di passaggio di consegne include:
GraphFlowSupporta cicli intenzionali, diramazioni condizionali e uscite dai cicli. L'API stabile descrive i cicli come validi solo quando esiste una condizione che alla fine ne provoca l'uscita e il generatore convalida la struttura del grafo. È inoltre contrassegnata come sperimentale. Un ciclo strutturalmente valido può comunque essere eseguito troppo a lungo se la condizione di uscita è logicamente irraggiungibile, quindi è consigliabile mantenere una condizione di terminazione indipendente o limitare i cicli attorno ad essa. Consultare la documentazione ufficiale dell'API dei team di AutoGen .
Questo aspetto è particolarmente importante nei modelli di lavoro "autore → revisore → autore". Se al revisore viene chiesto di "continuare a migliorare fino alla perfezione", il predicato di uscita potrebbe non essere mai soddisfatto. È preferibile sostituire la perfezione soggettiva con una griglia di valutazione definita, come ad esempio la presenza delle sezioni richieste, il superamento dei controlli di validazione, l'assenza di difetti critici e il raggiungimento del numero massimo di revisioni.
Gli agenti e i team di AgentChat mantengono lo stato della conversazione. La documentazione stabile di AutoGen afferma che il team conserva il contesto della conversazione tra le diverse esecuzioni, in modo che le attività correlate possano proseguire, e fornisce informazioni reset()per cancellare lo stato del team e dei partecipanti. Questo comportamento è utile per la continuità, ma può apparire come un ciclo se un'attività non correlata eredita il vecchio contesto, una delega incompleta o presupposti precedenti.
await team.reset()
result = await team.run(task=new_unrelated_task)
L'API stabile dell'agente avverte inoltre i chiamanti di trasmettere solo nuovi messaggi a ogni chiamata, anziché riprodurre manualmente l'intera cronologia della conversazione. Reinserire l'intera cronologia mentre l'agente mantiene anche lo stato può duplicare il contesto e rafforzare comportamenti ripetitivi.
Quando un ciclo è difficile da riprodurre, registra informazioni sufficienti per rispondere a quattro domande per ogni turno: chi ha agito, perché è stato scelto, quale azione ha tentato e cosa è cambiato in seguito. AutoGen offre supporto per il tracciamento e l'osservabilità, e la guida al tracciamento stabile mostra come tracciare i team di AgentChat. Consulta la documentazione ufficiale di AutoGen sul tracciamento .
Come minimo, registra:
TaskResult.stop_reasonquando la corsa finisce.Un metodo diagnostico molto efficace è il rilevamento di "stessa azione, stesso stato". Se lo stesso agente invoca lo stesso strumento con argomenti equivalenti e l'hash dello stato condiviso non è cambiato per diversi cicli, interrompete l'esecuzione e contrassegnatela come un ciclo senza progressi. Questo controllo risiede nella logica della vostra applicazione anziché essere una funzionalità integrata di AutoGen, ma rileva una classe di errori che i limiti di token o messaggi riescono a individuare solo a posteriori.
Per un'applicazione AutoGen AgentChat esistente, una base di riferimento prudente è la seguente:
max_tool_iterationsle dimensioni ridotte a meno che l'agente non necessiti effettivamente di una sequenza di strumenti in più fasi.Non risolvere ogni ciclo semplicemente aumentando il valore max_messagesda 25 a 100. Questo modifica il costo del fallimento, non la logica. Non aggiungere un prompt di sistema più lungo prima di verificare se la condizione di terminazione è effettivamente integrata nel team. Non permettere a due agenti di gestire entrambi la "revisione finale". Non restituire stringhe di strumenti ambigue se la successiva chiamata al modello deve decidere se riprovare. E non dare per scontato che un'esecuzione che alla fine si interrompe sia sana: un flusso di lavoro che raggiunge sempre il suo limite di sicurezza è comunque difettoso.
Se state gestendo un'applicazione AutoGen esistente, queste correzioni sono appropriate e la documentazione aggiornata rimane disponibile. Tuttavia, per un nuovo sistema o una riscrittura importante dell'orchestrazione, lo stato della modalità di manutenzione cambia la decisione. Microsoft ora indirizza i nuovi utenti a Microsoft Agent Framework e la relativa documentazione di migrazione descrive un passaggio dal nucleo e dai team di alto livello di AutoGen basati sugli eventi a flussi di lavoro tipizzati e basati su grafi. Ciò non significa che un ciclo AutoGen debba essere migrato immediatamente, ma significa che è necessario valutare il costo di un lavoro di orchestrazione più approfondito specifico per AutoGen rispetto al passaggio al successore supportato.
Il percorso di debug più breve e affidabile è quindi il seguente: limitare l'esecuzione, identificare la transizione ripetitiva, rendere osservabile l'avanzamento e infine rendere deterministica l'uscita. Una volta che questi quattro elementi sono a posto, la maggior parte dei cicli "infiniti" di AutoGen si trasformano in normali bug del flusso di lavoro che è possibile riprodurre e correggere.
Crea un flusso di lavoro Ollama locale che generi in blocco titoli SEO strutturati e meta descrizioni, convalidi l'output e segnali i risultati per la revisione umana.
Use this free modern real estate listing presentation PowerPoint blueprint to organize pricing, marketing, property prep, agent value, and seller next steps.
Crea un modello di preventivo per lavori edili stampabile in Excel, con indicazioni chiare su manodopera, materiali, formule, ricarichi, esclusioni e totali pronti per la stampa da presentare al cliente.
Crea prompt video più efficaci per Luma Dream Machine grazie a una formula pratica di illuminazione cinematografica, ricette riutilizzabili, esempi e una rapida lista di controllo per la risoluzione dei problemi.
Crea una presentazione minimalista per la tua startup tecnologica da presentare agli investitori in PowerPoint, con il giusto ordine delle diapositive, regole di design chiare, metriche di crescita e un'appendice pronta per gli investitori.
Impedisci a Excel di convertire codici, ID e frazioni in date. Utilizza il formato Testo, gli apostrofi, i controlli di importazione e le opzioni di Microsoft 365 attualmente disponibili.
Accelera il rendering di ComfyUI SDXL riducendo il lavoro di campionamento, controllando la risoluzione e la dimensione del batch, semplificando i nodi, utilizzando la cache e ottimizzando in modo sicuro la VRAM e l'attenzione.
Crea in Excel un pratico strumento per tenere traccia delle entrate e delle uscite degli immobili in affitto, con categorie chiare, formule, riepiloghi mensili e indicazioni per la tenuta della contabilità a fini fiscali.
Crea una knowledge base locale privata basata sull'IA con Ollama, AnythingLLM, embedding locali e RAG. Impara la configurazione in quattro fasi, i controlli sulla privacy, i test e i backup.
Correggi gli errori di finestra di contesto nell'analisi di documenti lunghi troncando l'input, suddividendo i file, utilizzando il recupero delle informazioni e verificando che la risposta finale includa la fonte.
