AutoGenエージェントが無限ループに陥る理由とその解決方法

AutoGen ループのデバッグを行う前に知っておくべき重要なプラットフォーム変更があります。2026 年 9 月現在、公式 AutoGen リポジトリはメンテナンス モードになっています。新機能ではなくメンテナンス作業が行われる予定であり、Microsoft は新規プロジェクトには Microsoft Agent Framework の使用を推奨しています。公式 AutoGen リポジトリでは、Python 0.7.5 が現在の安定版として記載されていますが、Microsoft は 2026 年 8 月 25 日に更新された AutoGen から Agent Framework への移行ガイドを公開しました。ただし、既に本番環境で AutoGen を使用している場合は、以下のトラブルシューティング手法が引き続き役立ちます。公式 AutoGen リポジトリ、公式 AutoGen リリース、および Microsoft のAutoGen 移行ガイドを参照してください。

AutoGenエージェントが「無限ループに陥っている」ように見えるのは、通常、次の5つの理由のいずれかが原因です。実行に信頼できる終了条件がない、次のスピーカーポリシーが非生産的な参加者を選択し続ける、ツール呼び出しで目に見える進捗が得られない、エージェント間で作業が繰り返される、またはアプリケーションが古い状態を再開し続ける、のいずれかです。最も迅速な解決策は、すべてのプロンプトを書き直すことではありません。まず、実際に発生しているループを特定し、次にハードストップを追加し、最後に失敗している遷移を修正します。

簡単な診断：どのようなループが発生していますか？

1. 他のデバッグを行う前に、強制停止を追加してください。

AutoGen AgentChat には、チーム間の境界を維持するために、組み込みの終了条件が用意されています。安定版ドキュメントには、、、、、、、、、、、、およびが含まれています。MaxMessageTermination公式のAutoGen終了ドキュメントを参照してください。TextMentionTerminationTokenUsageTerminationTimeoutTerminationHandoffTerminationSourceMatchTerminationExternalTerminationStopMessageTerminationTextMessageTerminationFunctionCallTerminationFunctionalTermination

ほとんどの運用ワークフローでは、意味的な完了条件と独立した安全上限値を使用します。重要な演算子は通常ORです。タスクが正常に完了するか、安全上限値に達したかのいずれかの時点で実行を停止したいからです。

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

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

termination = done | safety_cap

よくある間違いは、「完了したらTERMINATEと表示する」だけに頼ることです。これでは、動作の正確性はモデル化に委ねられてしまいます。もう一つの間違いは、&「どちらかで停止する」という意味で条件をANDとORで組み合わせることです。AutoGenはANDとORの両方の合成をサポートしているので、セマンティクスを慎重に選択してください。

この修正内容

• 期待される完了フレーズを決して生み出さないチーム。
• 有用な作業が停止した後も、別のスピーカーを探し続けるセレクター。
• 自然な終わりがない引き継ぎチェーン。
• 予期せぬモデルまたはツールの動作により、無制限のターンを消費してしまう可能性がある。

ハードキャップは回路遮断器であって、ワークフローが正しいことの証明ではありません。実行が常にキャップに達して停止する場合、修正すべき論理的な問題が依然として存在します。

2. 補完を単なる会話形式ではなく、機械が検出できるようにする

最も強力な終了シグナルは、アプリケーションが文章を解釈することなく認識できるものです。ワークフローに明確な成功イベントがある場合は、最も近い終了条件を使用してください。たとえば、特定のハンドオフは で検出できHandoffTermination、特定のツールの完了は で検出できFunctionCallTermination、カスタムロジックは で表現できますFunctionalTermination。

を使用する場合はTextMentionTermination("TERMINATE")、責任を明確にしてください。どのエージェントが完了を宣言できるのか、また、どのような検証済み条件の下で完了を宣言できるのかを明確にしてください。「満足するまで続ける」といった曖昧な指示をすべての参加者に与えるのは避けてください。「満足」には明確な境界がないため、そのような指示は際限のない批判と書き換えの行動を引き起こす可能性があります。

有用な完了契約は具体的である。「レビュー担当者は、ドラフトに必須の3つのセクションがすべて含まれ、未解決の障害が残っていない場合にのみ、TERMINATEを発行する。」さらに良いのは、可能であれば、レビュー担当者がアプリケーションがチェックできる構造化された状態を生成するようにすることである。

3. すべてのエージェントプロンプトを書き換える前に、SelectorGroupChat のルーティングを修正します。

SelectorGroupChatは、共有された会話コンテキストから次の話者を選択するためにモデルを使用します。安定版のドキュメントでは、参加者の名前と説明は話者選択に使用されるため重要であると述べられています。デフォルトでは、利用可能なエージェントが1つしかない場合を除き、同じ話者が連続して選択されることはありませんが、この動作は変更されます。AutoGenは、より決定論的な制御が必要な場合にも提供します。公式のSelectorGroupChatallow_repeated_speaker=Trueドキュメントを参照してください。selector_funccandidate_func

同じ参加者が繰り返し選ばれる場合は、以下の項目を順番に確認してください。

• エージェントの説明：各説明には、エージェントが何をするのか、そしていつ選択すべきなのかを明記する必要があります。説明が重複すると、ルーティングが不安定になります。
• セレクターのプロンプト：ルーティングルールは、モデルが確実に適用できるよう、短く保つようにしてください。AutoGenのドキュメントでは、プロンプトに多くの条件が蓄積され始めた場合は、カスタムセレクターの使用を検討することを明示的に推奨しています。
• 繰り返しスピーカー設定：連続して発言する必要が本当にある場合を除き、allow_repeated_speakerオフにしてください。
• 候補者の制限：特定の状態の後、有効なエージェントが2人しかいない場合、モデルにすべての参加者から選択させるのではなく、候補者のセットを制限します。
• 決定論的遷移：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リファレンスでは、複数のツール呼び出しが同時に実行される可能性があり、サポートされているモデルクライアントでは並列ツール呼び出しを無効にできることが指摘されています。また、複数のハンドオフが検出された場合、最初のハンドオフのみが実行されるため、そのような状況を避けるために並列ツール呼び出しを無効にすることを推奨しています。ワークフローで厳密に一度に1つのアクションのみの状態遷移を想定している場合、並列呼び出しによって結果として得られる状態の理解が難しくなる可能性があります。

5. スウォーム型チームにおけるハンドオフのピンポン現象を打破する

ハンドオフループは通常、次のような流れになります。エージェントAはエージェントBの方が適任だと判断し、エージェントBは不完全なコンテキストを見てタスクを返送します。そして、どちらの選択も局所的には永遠に妥当なままです。問題は、どちらのモデルも「間違っている」ということではありません。ハンドオフポリシーには所有権と終端状態が欠けているのです。

引き継ぎごとに具体的な条件を設定し、対象が処理を進められない場合にどうするかを定めるルールを設けることで、この問題を解決できます。ユーザー対話型ワークフローの場合、HandoffTermination(target="user")制御がアプリケーションまたは担当者に戻るべきときにチームを停止するように設計されています。AutoGen のヒューマン・イン・ザ・ループに関するドキュメントでは、Swarm ワークフローではユーザー引き継ぎ後に意図的な再開動作が必要であることも説明されています。公式のヒューマン・イン・ザ・ループに関するドキュメントを参照してください。

優れた引き継ぎ契約には以下の内容が含まれます。

• 対象が保有する正確な能力。
• 引き継ぎを正当化する証拠。
• ターゲットが成功した場合に返すべき値。
• 必要な情報が不足している場合、対象者は何をすべきか。
• 作業内容を変更せずに返送することを禁じる。

6. GraphFlowのサイクルを、明示的な終了が必要な実際のループとして扱う

GraphFlow意図的な循環、条件分岐、ループ終了をサポートします。安定版APIでは、ループは最終的にループを終了する条件が存在する場合にのみ有効であり、ビルダーがグラフ構造を検証すると説明されています。また、実験的な機能としてマークされています。構造的に有効なループであっても、終了条件が論理的に到達不可能な場合は、実行時間が長くなりすぎる可能性があるため、ループの周囲に独立した終了条件またはターン制限を設けてください。詳細については、公式のAutoGenチームAPIリファレンスを参照してください。

これは特に「執筆者→レビュー担当者→執筆者」という設計において重要です。レビュー担当者に「完璧になるまで改善を続ける」よう指示した場合、終了条件が満たされない可能性があります。主観的な完璧さを、必須セクションの出現、検証チェックの合格、重大な欠陥の不存在、最大改訂回数の達成といった、より明確な評価基準に置き換えてください。

7. 次のタスクが無関係な場合は状態をリセットする

AgentChatのエージェントとチームはステートフルです。AutoGenの安定版ドキュメントによると、チームは実行間で会話のコンテキストを保持するため、関連するタスクを継続でき、reset()チームと参加者の状態をクリアする機能も備えています。この動作は継続に役立ちますが、無関係なタスクが古いコンテキスト、未完了の委任、または以前の前提条件を引き継ぐと、ループのように見えることがあります。

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

安定版エージェントAPIでは、呼び出し元に対し、会話履歴全体を手動で再生するのではなく、各呼び出しで新しいメッセージのみを渡すよう警告しています。エージェントが状態を保持している状態で履歴全体を再注入すると、コンテキストが重複し、反復的な動作が強化される可能性があります。

8. 最終テキストだけでなく、遷移も記録する

ループの再現が難しい場合は、各ターンについて、誰が行動したか、なぜその人が選ばれたか、どのような行動を試みたか、その後何が変わったか、という4つの質問に答えられるだけの情報を記録してください。AutoGenはトレースと可観測性をサポートしており、安定版トレースガイドではAgentChatチームのトレース方法を示しています。AutoGenの公式トレースドキュメントを参照してください。

最低限、ログに記録してください。

• 実行IDとターン番号。
• メッセージの送信元とメッセージの種類。
• 選ばれた講演者および参加可能な候補者。
• ツール名と、ハッシュ値または正規化された形式の引数。
• ツールの状態と、状態が変化したかどうか。
• 引き渡し元と引き渡し先。
• 終了条件の結果。
• TaskResult.stop_reasonランニングが終了するとき。

非常に効果的な診断方法の一つは、「同じアクション、同じ状態」の検出です。同じエージェントが同じツールを同等の引数で呼び出し、共有状態ハッシュが数ターンにわたって変化していない場合、実行を停止し、進行しないループとしてマークします。このチェックは、AutoGenに組み込まれた機能ではなく、アプリケーションロジック内に実装する必要がありますが、トークンやメッセージの制限では事後的にしか検出できない種類の障害を捕捉できます。

実用的で安全な基準

既存のAutoGen AgentChatアプリケーションの場合、保守的なベースラインは次のとおりです。

• 必ず、ハードメッセージ、ターン、タイムアウト、またはトークン上限を設定してください。
• その上限値を、実行を停止させるべき条件がORである場合に意味のある完了条件と組み合わせます。
• max_tool_iterationsエージェントが本当に複数の手順からなるツールシーケンスを必要とする場合を除き、小規模に保つ。
• 成功、進捗なし、再試行可能なエラー、および永続的なエラーを区別する構造化されたツール結果を返します。
• ワークフロー上必要な場合を除き、同じ発言者を複数回発言させないでください。
• 決定論的なワークフローには、決定論的なセレクタを使用してください。
• ハンドオフには明確な所有権とターミナルルートを指定する。
• 関連性のないタスクの間には、チームをリセットする。
• 回転を追跡し、状態が変化しない繰り返し動作を検出します。

やってはいけないこと

ループを単にmax_messages25から100に増やすことで解決しないでください。それでは失敗時のコストが変わるだけで、ロジックは変わりません。終了条件が実際にチームに組み込まれているかどうかを確認する前に、より長いシステムプロンプトを追加しないでください。2人のエージェントが両方とも「最終レビュー」を担当しないようにしてください。次のモデル呼び出しで再試行するかどうかを決定する必要がある場合は、曖昧なツール文字列を返さないでください。また、最終的に停止する実行が正常であると想定しないでください。常に安全上限に達するワークフローは、依然として機能不全を起こしています。

パッチ適用を続けるのではなく、移行すべきタイミング

既存の AutoGen アプリケーションを保守している場合は、これらの修正は適切であり、最新のドキュメントも引き続き利用可能です。ただし、新規システムまたは大規模なオーケストレーションの書き換えの場合は、保守モードの状態によって判断が変わります。Microsoft は現在、新規ユーザーを Microsoft Agent Framework に誘導しており、その移行ドキュメントでは、AutoGen のイベント駆動型のコアおよび高レベルチームから、型付きグラフベースのワークフローへの移行について説明しています。これは、AutoGen ループを直ちに移行する必要があるという意味ではありませんが、AutoGen 固有のオーケストレーション作業にかかるコストと、サポートされている後継システムへの移行コストを比較検討する必要があることを意味します。

したがって、最も短く確実なデバッグ手順は、実行範囲を限定し、繰り返される遷移を特定し、進行状況を可視化し、最後に終了処理を確定させることです。これら4つの要素が揃えば、ほとんどの「無限」AutoGenループは、再現して修正できる通常のワークフローバグになります。

公式資料

• Microsoft AutoGenリポジトリ— 現在のメンテナンスモードに関するお知らせ。
• AutoGenリリース— 安定版Pythonリリース情報。
• AutoGen AgentChat 終了ガイド。
• AutoGen SelectorGroupChat ガイド。
• AutoGen AssistantAgent API リファレンス。
• AutoGenチームガイド
• Microsoft AutoGen から Agent Framework への移行ガイド— 2026 年 8 月 25 日更新。