為什麼您的自動生成代理會陷入無限循環——以及如何解決

在調試 AutoGen 循環之前，需要了解一項重要的平台變更。自 2026 年 9 月起，官方 AutoGen 程式碼庫已進入維護模式：預計主要進行維護工作，而非新增功能。微軟建議新專案使用 Microsoft Agent Framework。官方 AutoGen 程式碼庫仍將 Python 0.7.5 列為目前穩定版本，而微軟已於 2026 年 8 月 25 日發布了更新的 AutoGen 到 Agent Framework 遷移指南。不過，如果您已在生產環境中使用 AutoGen，以下故障排除技巧仍然有效。請參閱官方 AutoGen 程式碼庫、官方 AutoGen 版本發布說明以及微軟的AutoGen 遷移指南。

AutoGen 代理程式通常看起來“陷入無限循環”，原因有以下五點之一：運行沒有可靠的終止條件；下一位發言者的策略總是選擇無效的參與者；工具調用沒有產生可觀察的進展；代理程序來回重複工作；或者應用程序不斷恢復到過時的狀態。最快的解決方法並非重寫每個提示。首先確定實際存在的循環，然後加入一個硬性停止，最後修復失敗的轉換。

快速診斷：你看到的是哪種類型的循環？

1. 在偵錯任何其他內容之前，先新增一個硬停止點。

AutoGen AgentChat 提供內建的終止條件，專門用於約束團隊。穩定版文件包含以下終止條件：[此處MaxMessageTermination應TextMentionTermination列出終止條件TokenUsageTermination] 。請參閱 AutoGen 官方終止文件。TimeoutTerminationHandoffTerminationSourceMatchTerminationExternalTerminationStopMessageTerminationTextMessageTerminationFunctionCallTerminationFunctionalTermination

對於大多數生產工作流程，請使用語意完成條件和獨立的安全上限。重要的運算子通常是“或”，因為您希望在任務正常完成或達到安全限制時停止運行。

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

done = TextMentionTermination("TERMINATE")
safety_cap = MaxMessageTermination(max_messages=25)

termination = done | safety_cap

一個常見的錯誤是只依賴「完成後說終止」這樣的指令。這樣就忽略了行為的正確性。另一個錯誤是將條件與&實際想要表達的「滿足任一條件就停止」的意圖結合。 AutoGen 同時支援 AND 和 OR 組合，因此請仔細選擇語意。

這樣可以解決什麼問題？

• 一個永遠無法得出預期結果的團隊。
• 一個選擇器，即使有用的工作已經停止，它仍然會不斷找到另一個揚聲器。
• 一條沒有自然終點的交接鏈。
• 出乎意料的模型或工具行為，否則會消耗無限的回合數。

設定硬性上限只是一個斷路器，並不能證明工作流程正確。如果運行總是因為達到上限而停止，那麼你仍然需要修復邏輯問題。

2. 使完成操作能夠被機器偵測到，而不僅僅是對話中能夠偵測到。

最有效的終止訊號是應用程式無需解讀文字即可識別的訊號。如果工作流程有明確的成功事件，則使用最接近的符合終止條件。例如，可以使用 `<handoff>` 檢測特定的交接HandoffTermination，可以使用 `<toolcomplete>` 檢測特定的工具完成FunctionCallTermination，可以使用 `<customlogic>` 表達自訂邏輯FunctionalTermination。

如果使用此功能TextMentionTermination("TERMINATE")，請明確責任劃分：哪個代理可以聲明完成，以及在什麼已驗證的條件下可以聲明完成？避免向每位參與者發出諸如「繼續直到滿意為止」之類的模糊指令。這類指令會導致無止盡的修改和重寫行為，因為「滿意」沒有可觀察的界線。

有效的完成協議應該具體明確：「審核人員只有在草稿包含所有三個必需部分且不存在任何未解決的問題後才能發出終止通知。」更好的做法是，在條件允許的情況下，要求審核人員產生應用程式可以檢查的結構化狀態。

3. 在重寫所有客服提示之前，先修正 SelectorGroupChat 路由問題。

SelectorGroupChat使用模型從共享的對話上下文中選擇下一個發言者。穩定版文件指出，參與者的姓名和描述很重要，因為它們用於發言者選擇。預設情況下，除非是唯一可用的代理，否則不會連續選擇同一個發言者，但可以透過allow_repeated_speaker=True更改設定來改變此行為。 AutoGen 也提供了selector_func更多功能，candidate_func以滿足您更精確的控制需求。請參閱SelectorGroupChat 的官方文件。

如果總是選取同一位參與者，請依序檢查以下各項：

• 代理描述：每個描述都應該說明代理的功能以及何時應該選擇它。描述重疊會導致路由不穩定。
• 選擇器提示：請確保路由規則足夠簡短，以便模型可靠地應用。 AutoGen 文件明確建議，當提示資訊開始累積大量條件時，應考慮使用自訂選擇器。
• 重複播放設定：allow_repeated_speaker除非確實需要連續播放，否則請勿關閉。
• 候選限制：如果在特定狀態下只有兩個有效代理人，則限制候選集，而不是要求模型從每個參與者中進行選擇。
• 確定性轉換：selector_func當工作流程實際上是偽裝成對話的狀態機時使用。

關鍵區別很簡單：當下一個發言者確實需要語義判斷時，使用基於LLM的發言者選擇；當下一個發言者由工作流程狀態決定時，使用確定性路由。

4. 透過顯示進度來避免重複呼叫工具

在目前的 AgentChat 中，AssistantAgent有一個max_tool_iterations參數。穩定的 API 文件指出，預設值為 1；增加此值後，代理程式可以進行更多連續的工具調用，直到模型返回文字回應或達到最大值為止。這意味著單一代理的運行次數受此設定的限制，但團隊仍然可以再次選擇同一個代理，並在多輪操作中重複相同的失敗工具呼叫模式。請參閱官方的AssistantAgent API 參考文件。

agent = AssistantAgent(
    name="worker",
    model_client=model_client,
    tools=[lookup_tool],
    max_tool_iterations=3,
)

如果重複出現相同的工具和參數，降低迭代次數限制只能暫時緩解問題，根本原因通常在於工具的機制。模型需要足夠的資訊來判斷呼叫是成功、永久失敗、暫時失敗，還是沒有產生任何新資訊。

傾向於簡潔明了的結果，例如：

{
    "status": "no_new_data",
    "query": "customer_123",
    "retryable": false,
    "reason": "record already checked",
    "next_action": "return_to_planner"
}

這比使用「無結果」之類的通用字串更有用，因為模型可以識別出重複呼叫並不會取得進展。對於會產生副作用的工具，還需要在應用層中添加冪等性，以防止重複呼叫導致相同的工單、付款、訊息或資料庫變更。

另請檢查並行工具調用

穩定版AssistantAgent參考文件指出，多個工具呼叫可以並發執行，並且在支援的模型用戶端中可以停用並行工具呼叫。文件還警告說，如果偵測到多個交接，則只會執行第一個交接，並建議停用並行工具呼叫以避免這種情況。如果您的工作流程假定狀態轉換嚴格地一次只執行一個操作，則並行呼叫可能會使最終狀態更難理解。

5. 打破蜂群式團隊中頻繁的傳球失誤

交接循環通常是這樣的：代理 A 認為代理 B 更合適，代理 B 發現上下文不完整，於是將任務發回代理 A，而這兩個選擇在局部範圍內始終都是合理的。問題不在於哪個模型“錯誤”，而在於交接策略缺乏所有權和終止狀態。

解決方法是為每次交接設定一個明確的條件，並制定一條規則來處理目標無法繼續前進的情況。對於使用者互動式工作流程，HandoffTermination(target="user")該機制旨在當控制權應該返回給應用程式或使用者時，停止團隊的運作。 AutoGen 的人機互動文件也解釋了 Swarm 工作流程在使用者交接後需要明確的復原行為。請參閱官方的人機互動文件。

一份完善的交接合約應包含以下內容：

• 目標所擁有的確切能力；
• 證明移交合理性的證據；
• 目標成功時應返回什麼；
• 如果缺少必要訊息，目標物件應該怎麼做；
• 禁止將任務原封不動地退回。

6. 將 GraphFlow 循環視為需要明確退出的真正循環

GraphFlow支援有意設計的循環、條件分支和循環退出。穩定的 API 僅當存在最終退出循環的條件時才認為循環有效，並且建構器會驗證圖結構。該 API 也被標記為實驗性功能。即使結構上有效的循環，如果退出條件在邏輯上不可達，也可能運行過久，因此需要為其設定獨立的終止條件或循環次數限制。請參閱AutoGen 團隊的官方 API 參考文件。

這點在「作者→審閱者→作者」的流程設計中尤其重要。如果要求審閱者“不斷改進直至完美”，那麼最終的退出條件可能永遠無法實現。因此，應以明確的評估標準來取代主觀的完美標準，例如：包含所有必需章節、通過驗證檢查、無重大缺陷以及達到最大修改次數。

7. 當下一個任務與目前任務無關時，重置狀態

AgentChat 的代理商和團隊是有狀態的。 AutoGen 的穩定版文件指出，團隊會在運行過程中保留對話上下文，以便相關任務能夠繼續進行，並且它提供了reset()清除團隊和參與者狀態的功能。這種行為有利於任務的延續，但如果一個不相關的任務繼承了舊的上下文、未完成的委託或先前的假設，則可能會陷入循環。

await team.reset()
result = await team.run(task=new_unrelated_task)

穩定的代理 API 也提醒呼叫者，每次呼叫時只傳遞新訊息，而不是手動重播整個對話歷史記錄。代理在維護狀態的同時重新註入完整的歷史記錄，會導致上下文重複，並強化重複行為。

8. 記錄轉換過程，而不僅僅是最終文字。

當循環難以重現時，請記錄足夠的信息，以便回答每一回合的四個問題：誰執行了操作、為什麼選擇他們、他們嘗試了什麼操作以及之後發生了什麼變化。 AutoGen 提供追蹤和可觀測性支持，穩定的追蹤指南示範如何追蹤 AgentChat 團隊。請參閱AutoGen 官方追蹤文件。

至少記錄：

• 運行 ID 和轉彎號；
• 消息來源和消息類型；
• 選定的演講者和候選人；
• 工具名稱加上參數的雜湊值或規範化形式；
• 工具狀態以及狀態是否有變化；
• 交接源和目標；
• 終止條件結果；
• TaskResult.stop_reason當運行結束時。

一種非常有效的診斷方法是檢測「相同操作，相同狀態」。如果同一代理程式使用相同的參數呼叫相同的工具，且共享狀態雜湊值在多次迭代中都沒有改變，則停止運行並將其標記為無進展循環。此檢查位於應用程式邏輯中，而非 AutoGen 的內建功能，但它可以捕獲一類事後透過令牌或訊息限制才能發現的故障。

一個切實可行的安全基線

對於現有的 AutoGen AgentChat 應用程序，保守的基準是：

• 務必配置硬性訊息、回合、逾時或令牌上限。
• 將該上限與有意義的完成條件（使用 OR 表示）結合起來，當兩者之一應該停止運行時，就應該停止運行。
• max_tool_iterations除非代理人確實需要多步驟工具序列，否則盡量保持簡潔。
• 傳回結構化的工具結果，區分成功、無進展、可重試錯誤和永久性錯誤。
• 除非工作流程需要，否則不要允許重複發言。
• 對於確定性工作流程，請使用確定性選擇器。
• 明確交接責任和最終路徑。
• 在執行不相關任務之間重新調整團隊。
• 追蹤轉向並偵測狀態不變的重複動作。

不該做什麼

不要簡單地將循環閾值max_messages從 25 提高到 100 來解決所有問題。這樣做只會改變失敗的成本，而不會改變邏輯本身。在檢查終止條件是否已實際整合到團隊之前，不要添加過長的系統提示。不要讓兩個代理同時擁有「最終審核」權限。如果下一次模型呼叫必須決定是否重試，則不要傳回意義模糊的工具字串。不要假設最終停止的運作是正常的：始終達到安全上限的工作流程仍然有故障。

何時應該遷移而不是繼續打補丁

如果您正在維護現有的 AutoGen 應用程序，這些修復程序仍然適用，並且現有文件仍然可用。但是，對於新系統或重大流程編排重寫，維護模式狀態會影響決策。微軟現在建議新用戶使用 Microsoft Agent Framework，其遷移文件描述了從 AutoGen 的事件驅動核心和高級團隊向類型化、基於圖的工作流程的轉變。這並不意味著必須立即遷移 AutoGen 循環，但確實意味著您應該權衡深入的 AutoGen 特定流程編排工作與遷移到受支援的後續方案的成本。

因此，最短且可靠的偵錯路徑是：限制運行時間，識別重複出現的轉換，使進度可觀察，然後使退出過程確定。一旦這四點到位，大多數「無限」的 AutoGen 循環就會變成您可以重現和修復的普通工作流程錯誤。

官方參考資料

• Microsoft AutoGen 儲存庫— 目前維護模式通知。
• AutoGen 發布— 穩定的 Python 版本資訊。
• AutoGen AgentChat終止指南。
• 自動產生選擇器群組聊天指南。
• AutoGen AssistantAgent API 參考。
• 自動產生團隊指南。
• Microsoft AutoGen 到 Agent 框架遷移指南— 2026 年 8 月 25 日更新。