AIエージェントの仕組み：ループの動作と停止条件を理解する

次に何をするかはモデルが提案します。その操作を実行してよいか判断し、結果を記録し、モデルをもう一度呼び出してよいか決めるのは、アプリケーション側の仕事です。この役割分担を押さえることが、初めてエージェントを作る場合にも、動き続けるエージェントの原因を調べる場合にも出発点になります。

以下で紹介するフレームワークの挙動は、2026年10月24日に各開発元の公開ドキュメントで確認したものです。比較では、何をカウントするのか、どの時点で制御が働くのかをそろえて整理しています。サポートチケットの例と推奨ポリシーは説明用であり、本番環境での測定結果ではありません。

AIエージェントの仕組み：エージェントループはどう動くのか

基本となる流れは、モデル呼び出し → ツール呼び出し → 結果の観測 → 繰り返しです。続行する必要がなくなった時点、または続行が認められない時点で、ループを抜けます。

作業を割り振る担当者と、現場の技術者を思い浮かべてください。担当者が次の仕事を選び、技術者が実行し、その作業報告をもとに次の判断を下します。「機械を点検してほしい」という依頼は点検そのものではありませんし、「大丈夫です」という言葉だけでは修理の成功を確認できません。

ソフトウェアでは、この担当者に当たるのが大規模言語モデル、つまりLLMです。技術者に当たるのがツールで、データベースの読み取り、ドキュメントの検索、コマンドの実行、レコードの変更などを行う関数です。両者をつなぐコードが、周囲のランタイムを構成します。

チケットへの返信案を作る架空のタスクなら、実行履歴はこうなります。最初のモデル呼び出しでチケットを取得し、次の呼び出しで関連ポリシーを取得し、その次に両方を根拠とする返信案を返します。アプリケーションへの依頼は1回でも、その内部ではモデル呼び出しが3回、ツール実行が2回発生しています。送信に承認が必要なら、返信案の作成は完了していても、送信は保留にできます。

タスクの状態は会話履歴と分けて管理してください。どのチケットを扱っているか、どのポリシーを採用したか、返信案が存在するか、送信が許可されているかを、状態として記録します。会話履歴が説明するのは、そこに至った経緯です。膨らみ続ける会話から毎回モデルにこれらを推測させると、処理を監督しにくくなります。

固定ワークフローとエージェントループは何が違うのか

ループ型のエージェントは、直近の結果を見て次の操作を選べます。一方、固定ワークフローでは「チケットを取得する、ポリシーを取得する、返信案を作る」という順序があらかじめ決まっています。直前の操作で分かったことによって次の有効な操作が変わるなら、適応的なループが向いています。その不確実性がなければ、固定の手順を使います。

ReActはエージェントループのどこに位置づけられるのか

ReActのエージェントループは、推論と行動を結びつけます。モデルは観測結果を次の行動の判断材料にします。ReActの元プロジェクトでは、環境に対する行動と推論を交互に進める考え方が説明されています。アプリケーションを監視する際は、要求された操作、観測データ、結果を記録してください。進捗を説明する文章は、実行を確認する記録の代わりにはなりません。

本番運用のループに必要な3つの停止条件

出口は完了、上限到達、人の判断待ちの3つを明確に設計します。これは設計上の分類であり、すべてのSDKに同じ3つの設定項目があるという意味ではありません。クラッシュ、キャンセル、回復不能なエラーについても、失敗時の処理を明示する必要があります。

タスクの完了を確認して停止する

最初にモデルを呼び出す前に、何をもって完了とするか定義します。下書きを作るアシスタントなら、必要な参照元を含む有効な下書きができたことが条件になるでしょう。実際に操作を行うアシスタントなら、書き込みの完了を確認する記録まで必要になる場合があります。

「モデルがツールを要求しなくなった」と「依頼された仕事が成功した」は分けて扱います。前者はランタイムからのシグナルです。後者には、そのタスクに応じた証拠が必要です。モデルは、先に進めなくなったために停止することもあります。その場合は成功として見せず、アプリケーション側で続行不能または未完了と記録します。

回答が検証に通らなかったからといって、無条件でループを再開してはいけません。修正の試行も、同じジョブの上限に計上します。そうしなければ、検証処理そのものが際限のない再試行を生みかねません。

上限に達したら停止する

ステップ数、リソース使用量、経過時間には、それぞれ独立した上限を設けます。ステップ数の上限は繰り返しを制限します。トークン数や費用の予算は消費量を制限します。期限を設ければ、遅いモデルやツールのためにジョブがいつまでも終わらない事態を防げます。これらは互いに代用できません。

新しい処理を開始してよいか判断する前に上限を確認し、処理の終了後に使用量を更新します。完了した呼び出しだけを数えても、すでに動いているリクエストの消費は防げません。厳密な上限を保証するなら、次の操作に必要な枠を予約し、並行して進む処理も計算に入れてから開始します。

上限はSDKの呼び出し単位だけでなく、業務ジョブ全体にかけます。再試行、承認後の再開、子エージェントの起動によって、いつの間にか新しい実行枠が付与されてはいけません。追加の処理が必要なら、アプリケーション側で明示的に判断して枠を拡張します。

Human in the loop：人の承認が必要な操作の前で止める

人が判断に関わるAIエージェントは、承認が必要な操作の実行前に一時停止するべきです。提案する操作、その対象、判断に必要な引数を提示します。保留中の呼び出しと現在のジョブの状態を保存し、明示的な判断を待ちます。

チケット対応アシスタントなら、特定の宛先に送る特定の返信内容について承認を得ます。下書きの承認が、その後のメッセージ送信すべてへの包括的な許可になってはいけません。承認後にモデルが宛先や内容を変えたら、その操作を改めて確認します。

一時停止はcompletedではなくawaiting_approvalとして記録します。却下されたら、定義済みの別の処理に進むか停止します。同じ操作を別のツール経由で通そうと繰り返してはいけません。承認キューやエスカレーションについては、human in the loopの解説で扱っています。

疑似コードで見る最小限のエージェントループ

各操作の前後にポリシーの確認を置けば、ループ本体は小さく保てます。以下は疑似コードであり、そのまま実行できるSDKのコードではありません。例にあるモデル呼び出し8回という上限は、説明用のアプリケーション設定です。実際の上限は、タスクと観測した実行履歴をもとに決めてください。

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)

補助関数の名前には、実装上の重要な責務が含まれています。枠の予約では、すでに実行中の処理も計上します。ツールの再試行には上限が必要です。書き込み結果が不明のままタイムアウトした場合は、再試行する前に停止するか、実際の状態を照合します。モデルやツールに致命的なエラーが発生したら、次の反復へ進まず、失敗を記録して終了します。

一時停止の保存データには、残りのツール呼び出し、完了済みの結果、消費済みの実行枠を含めます。再開時には保存した処理を引き継ぎ、権限と上限を再確認します。タスク全体を最初からやり直すと、すでに行った操作の影響が重複するおそれがあります。

確認処理を置く場所に注目してください。承認はツール実行前、使用量の計上は処理の完了後です。そして、モデルが要求したというだけでは次の反復を開始できません。

フレームワークごとにループの制御はどう違うのか

OpenAI Agents SDK、Claude Agent SDK、Vercel AI SDK、LangGraphでは、ループの提供方法が異なります。オプション名を見比べる前に、何を単位として数え、どの時点で停止を判断するのかを比較してください。

これらの名称は、各開発元のOpenAIのループドキュメント、Claudeのループドキュメント、Vercelのループドキュメント、LangGraph Graph APIに基づきます。承認時の挙動に関する資料は、以下の各節で紹介します。

OpenAI Agents SDK：続行を管理するのはRunner

OpenAI Agents SDKでは、Runnerがモデルを呼び出し、要求されたツールを実行し、結果を追加して処理を続けます。ハンドオフが発生すると、担当エージェントを切り替えて実行を続行します。ドキュメント上の正常終了条件は、ツール呼び出しを伴わずに期待する型の出力が得られることです。max_turnsを超えると、処理しない限りMaxTurnsExceededが送出されます。OpenAIのエージェント実行ドキュメント。

チケット対応アシスタントでは、モデルのターン数に上限を設けやすい構成です。ただし、実行が完了したことと、業務上の操作が完了したことの間には境界があります。期待する出力の仕様を定め、タスクに必要な証拠を確認してください。

承認については、Pythonのツールでneeds_approvalを宣言でき、保留中の呼び出しはinterruptionsに現れます。RunStateを保存し、承認または却下を反映してから再開します。一時停止した実行の再開は、新しいユーザーリクエストではありません。OpenAIのhuman in the loopドキュメント。

Claudeのエージェントループ：ターン数と費用の両方に上限を設ける

Claude Agent SDKには、ファイル操作やコマンド実行のツールを含め、Claude Codeを支えるループが組み込まれています。maxTurnsはツールを使用するターンを数え、maxBudgetUsdは推定費用のしきい値を設定します。どちらも未設定なら無制限です。Pythonではmax_turnsとmax_budget_usdを使います。Claudeのエージェントループドキュメント。

結果のサブタイプを確認してください。success、error_max_turns、error_max_budget_usdは、それぞれ異なる結果です。単発実行モードでは、エラー結果の後に例外が送出されるため、結果と例外の両方を処理します。Claudeの結果の処理。

権限の境界にも同じだけ注意が必要です。allowedToolsは、一覧にあるツールを自動承認します。一覧に含めなかったツールを利用不可にする設定ではありません。既定の権限モードでは、承認が必要で、どの許可ルールにも一致しない呼び出しがcanUseToolに渡されます。人が監督しない書き込み処理にこのSDKを使う前に、権限ポリシー全体を確認してください。Claudeの権限。

子エージェントを含む使用量の集計では、Claudeはメインループのusageと、ツリー全体のmodelUsage、またはPythonのmodel_usageを区別します。ジョブの消費量を調べる際は、対象に合う合計値を使ってください。Claudeの費用・使用量ドキュメント。

実装手順を知りたい場合は、当サイトのClaude Agent SDKガイドから始めてください。

Vercel AI SDK：stopWhenが制御するのは次のステップ

Vercel AI SDKでは、stopWhenで続行を制御します。現在のドキュメントでは、ステップ数の上限にisStepCountを使います。条件を複数指定することもでき、いずれかに一致すると停止します。既定値は、ToolLoopAgentが20ステップ、generateTextとstreamTextが生成1回です。どのAPIを入り口に使うかで挙動が変わります。Vercelのループ制御、ツール呼び出しドキュメント。

1ステップには、生成と、それに伴うローカルのツール実行が含まれます。押さえておきたいのは、直前のステップにツールの結果が含まれるときにstopWhenが評価される点です。その結果を生んだツールの処理を、後から取り消すことはできません。 つまり、これは続行の制御であり、操作前の承認ではありません。Vercelの複数ステップの呼び出し。

明示的にユーザーの承認を得るには、ドキュメントにあるtoolApprovalを使います。現在のドキュメントでは、以前のツールプロパティneedsApprovalは非推奨とされています。Vercelのツール承認。

コンテキスト管理には、各ステップの前に実行されるprepareStepが使えます。メッセージや設定を変更できるため、毎回すべての生データを引き継ぐ代わりに、この時点で関連する状態を渡します。VercelのprepareStep。

LangGraphとLangChainのエージェントループ

LangGraphはグラフのランタイムです。処理を担うノードを、次に何を実行するか決めるエッジでつなぎます。グラフ上にLangChainのエージェントループを構築するなら、モデルへ戻る経路とENDへ進む経路を明示してください。Pythonのrecursion_limitが制限するのは、グラフのスーパーステップです。並列に動くノードは同じスーパーステップに属します。ツール呼び出しの回数を数えるものではありません。LangGraph Graph API。

recursion_limitは、呼び出し設定のトップレベルに指定します。configurableの内側ではありません。上限に達するとGraphRecursionErrorが送出されます。通常は、この緊急用の出口に達する前に、設計した完了経路で処理を終えるべきです。LangGraphの再帰上限。

人のレビューが必要な場合は、interrupt()でグラフを一時停止します。チェックポインターと固定したthread_idを使い、Command(resume=...)で再開します。ここで注意すべき境界は、再開すると中断したノードの先頭から処理が始まることです。中断より前のコードは再実行される可能性があります。外部に影響する操作は承認後に配置するか、繰り返し実行しても追加の影響が生じない冪等な処理にしてください。LangGraphの中断。

分岐や再開可能な状態管理が業務の中心になるなら、この明示的なグラフ構造が適しています。単純なツールの反復で動く、初めての読み取り専用アシスタントなら、要件を満たす最小限のランタイムから始めましょう。

なぜ実行が40ステップに達するのか

上限を引き上げる前に、ステップ間で何が変わったかを調べてください。長い実行は、有用な作業の積み重ねかもしれませんし、同じ失敗の繰り返しかもしれません。再開時に完了済みの処理を見失った可能性もあります。回数だけでは見分けられません。

無限ループ：新しい情報がないまま同じ操作を繰り返す

チケット対応エージェントがポリシーを検索し、結果が空だったために同じ検索を繰り返すことがあります。次の観測データに何も加わらなければ、次の判断も同じ操作になりえます。

正規化したツール名と引数、結果のフィンガープリント、タスクの進捗を示す指標を記録します。状態が変わらないまま同じ操作が繰り返されたら、停滞していないか確認します。正当なポーリングでも同じ操作は繰り返されるため、重複をすべてエラーとみなすのではなく、ポーリングには専用の上限付きポリシーを設けます。

再試行の前に、検索語、不足していた識別子、利用するデータソース、タスクの範囲など、何かを変えてください。有効な変更ができないなら、満たせなかった要件を返すか、助けを求めます。「もう一度試す」だけでは復旧策になりません。

ツールエラー：回復可能な失敗と結果不明を区別する

不正な引数、権限の拒否、一時的なサービス障害では、必要な対処が違います。モデルが次の操作に生かせる、簡潔なエラーを返します。回復可能なエラーにも再試行の上限を設け、ジョブに与えられた権限では解決できないエラーなら直ちに停止します。

書き込み中のタイムアウトは、さらに厄介です。応答が届かなかっただけで、書き込み自体は成功しているかもしれません。顧客へのメッセージを再送したり、レコードをもう一度作成したりする前に、処理状況を照会するか、冪等性キーを使います。冪等性キーは、同じ意図の操作であることをサービス側が識別できる、固定した識別子です。

復旧時も、成功済みの処理を保持してください。チケットの読み取りには成功し、ポリシーの取得に失敗した場合、ジョブ全体をやり直すと余計な処理が増え、すでに生じた操作の影響を重複させるおそれがあります。

コンテキストの肥大化：生データをすべて抱えず、判断を引き継ぐ

観測データを追加するたびに、次のモデル呼び出しでタスクの指示や過去の証拠に向けられる注意が分散します。大きなツール応答は、技術的には有効でも、次の判断の焦点をぼやけさせることがあります。

ツール出力のサイズを制限し、大きな成果物はプロンプトの外に保存して、取得可能な参照先を添えた簡潔な結果を返します。確定した制約、承認、確認済みの操作は、アプリケーションの永続的な状態として保持します。要約でそれらを説明することはできますが、要約だけを唯一の記録にしてはいけません。

ClaudeのSDKは、コンテキスト上限に近づくと自動圧縮を行うことをドキュメントで説明し、初期の指示が要約から抜け落ちる可能性にも言及しています。だからこそ、重要な状態を意識的に保持する必要があります。Claudeのコンテキスト圧縮。コンテキストウィンドウに収まっていても必要な情報を適切に取り出せるとは限らない理由は、コンテキスト劣化の解説で扱っています。

運用担当者の疑問に答えられる実行履歴を残す

ジョブごとに、識別子、モデル呼び出し回数、ツールの実行試行、使用量、経過時間、保留中の承認、停止理由を記録します。操作ごとには、何が要求され、何が完了し、タスクの状態が変わったかを残します。

モデルへのリクエスト、ツール実行、ランタイムのステップは、別々のカウンターで管理します。ダッシュボードに「40ステップ」とだけ表示されても、単位が分からなければ実行内容を説明できません。子エージェントの作業と再試行も、親ジョブの使用量に含めます。複数のエージェントにまたがる作業の責任分担は、AIエージェントのオーケストレーション解説で説明しています。

エージェントループはどこまで期待できるのか

反復回数が多いからといって、進捗が多いとは限りません。ループは、フィードバックを利用する機会を繰り返し提供します。その繰り返しが役に立つかどうかは、フィードバックの質と成功の定義で決まります。

モデルが「完了しました」と返したのは、そのやり取りで自分の役割を終えたということです。ステップ上限が示すのは、実行回数が制限されていたことです。どちらも、サポートの返信が正しいことや、依頼された変更が実際に行われたことの証明にはなりません。

フレームワークを使っても、権限、永続化、復旧を定義する必要は残ります。フレームワークが提供するのは実行の仕組みです。何を成功とするか、何を実行してよいかは、アプリケーションが決めます。

エージェントのテストループは実行ループと分けて考える

エージェントのテストループは、テストケースと受け入れ基準に照らして挙動を評価します。実行ループの外側に検証処理を置き、結果を受け入れるか、再試行のためのフィードバックを返す構成もあります。LangChainのループエンジニアリングの解説では、実行、検証、イベントをきっかけとする処理を区別しています。

検証する側にも上限を設けます。別のモデルに回答の良し悪しを繰り返し尋ねても、決め手となる証拠が得られず、実行枠だけを消費しかねません。可能なら、必須フィールドがあるか、引用したレコードが一致するか、書き込みの完了記録があるか、期待するテストに通るか、といった具体的な確認を優先します。

AIエージェント開発・運用で次に取り組むこと

初めてエージェントを開発する人： 範囲を絞った読み取り専用のタスクから始め、完了条件を明示し、各操作に上限を設けます。提案する操作を示し、権限を確実に確認し、結果が曖昧な場合にも復旧できるようになってから書き込みを追加します。手順がすでに決まっているなら、固定ワークフローで十分かもしれません。

費用のかかった実行を調べる運用担当者： モデルの変更や上限の引き上げに進む前に、繰り返された呼び出し、連鎖する再試行、増え続ける観測データを確認します。どのステップが有用な証拠を増やしたのか、実際にジョブを止めたのはどのカウンターだったのかを調べてください。

信頼できる固定ワークフローを持つチーム： 結果に応じたツール選択で解決できる具体的な問題が見つかるまでは、今の仕組みを維持します。ループが価値を持つのは、中間結果によって次の操作が変わる場合です。反復できるという理由だけで作り直す必要はありません。

まず着手するなら、代表的なタスクを1つ選び、正常完了、上限到達、承認待ちの一時停止、操作の拒否、ツールの失敗という各経路を試してください。どの経路でも状態が明確に残り、再開時には完了済みの作業と残りの実行枠の両方が維持されることを確認します。

エージェントループのよくある質問

AIシステムの開発と運用に役立つ実践ガイドは、ニュースレターに登録してお受け取りください。