AgentGPTでループ制限を設定しタスク出力をエクスポートしてトークン浪費を防ぐ方法

自律型AIエージェントは、高レベルな目標を自律的にサブタスクへ分解し、再帰的に実行を進める強力な仕組みを備えています。しかし、適切な制限を設けない再帰的ループは、APIトークンを一気に消費してしまう最大の原因にもなります。エージェントが論理的なデッドロックに陥ったり、アクセスできないWebページの解析を繰り返したり、無限にサブタスクを増殖させたりすると、わずか数分でAPI予算が枯渇する危険があります。Reworkdが開発したオープンソースプラットフォーム「AgentGPT」では、開発者がこのリスクを回避するために2つの主要な制御手段を提供しています。それが厳格な実行ループ制限（Loop limits）の設定と、**マルチフォーマットでのタスク出力エクスポート（Task outputs export）**です。

エージェントを起動する前にループ回数とトークン枠を設定し、完了時や中断時に成果物を確実に抽出することで、安全かつ予測可能な自律ワークフローを実現できます。

1. AgentGPTの再帰的ループとトークン消費の仕組み

なぜループ制限が不可欠なのかを理解するために、AgentGPTの実行サイクルを確認しておきましょう。

1. 目標の取り込み（Goal Ingestion）：ユーザーが入力した主目標を受け取り、LLM（GPT-3.5-TurboやGPT-4など）を呼び出して初期のサブタスク一覧を生成します。
2. タスクの実行と分析（Task Execution）：キューの先頭にあるサブタスクを取り出し、モデルや外部ツールを用いて実行し、中間結果を記録します。
3. 新規タスクの生成（Task Creation）：得られた結果に基づき、さらに必要なサブタスクが存在するかを判定してキューに追加・再構成します。
4. 再帰的サイクル（Recursive Loop）：ステップ2と3がタスク完了または制限到達まで繰り返し実行されます。

このサイクルの1巡を「実行ループ（Loop）」と呼びます。1ループごとに複数回のAPIリクエストが発生し、蓄積されるコンテキスト履歴も増大していきます。目標が曖昧であったりツール実行が失敗し続けたりすると、無限ループが発生し、急激なトークン消費につながります。

2. ユーザーインターフェースでのループ制限設定

AgentGPTのWebブラウザ画面およびローカルUIでは、設定画面から直感的に実行上限をコントロールできます。

詳細設定へのアクセス

1. AgentGPTの画面を開き、左側メニューバーの Settings（⚙️ 設定） をクリックするか、直接 /settings にアクセスします。
2. 認証ログイン（GitHub、Google、Discord）を完了しているか、またはセルフホスト環境であることを確認します。公式ホスティング版では、公開リソース保護のため、未ログインのゲスト状態では Advanced Settings（高度な設定） が無効化されています。

ループスライダーの調整（customMaxLoops）

Advanced Settings 内にある Loop パラメータを設定します：

• 調整範囲：1 〜 25ループの間で1刻みで指定可能。
• デフォルト値：無料デモ利用時は 25、カスタムAPIキー設定時は安全基準として 10 が初期設定されます。
• 停止動作：実行ループのカウントが設定上限に達すると、それ以上のサブタスク生成を即座に停止し、コンソールに以下の保護メッセージが表示されます。

  The maximum number of loops have been reached, this agent is shutting down.
  

  (過去の初期バージョンでは "To save your wallet, and our infrastructure costs, this agent is shutting down." と通知されていました)

タスク種別ごとの推奨ループ目安

• 要約、単一トピックの質問、簡易調査：3 〜 7ループ。
• 複数段階の文書作成、比較調査、構成案検討：8 〜 12ループ。
• 複数情報源の深層リサーチ、複合的タスク：15 〜 25ループ。

コスト管理を強化する周辺パラメータ

ループ制限とあわせて、同画面内の以下の項目も調整することが推奨されます：

• トークン上限（Tokens / maxTokens）：スライダーで200からモデル上限値（4000トークンなど）まで指定可能。1回のAPI呼び出しにおける最大出力長を抑え、単一タスクの肥大化を防ぎます。
• モデル選択（Model）：プロトタイプ段階では経済的な gpt-3.5-turbo を利用し、複雑な推論を要する局面でのみ gpt-4 に切り替えます。
• 温度（Temperature）：0.0 〜 0.2 付近に下げることで、出力の決定論性を高め、幻覚（ハルシネーション）による迷走ループを抑止します。
• カスタムAPIキー（API Key）：自身のOpenAI APIキーを入力し、Test ボタンで接続検証を行うことで、自身の利用枠内でコストを直接監視できます。

3. 実行時のリアルタイムライフサイクル制御

事前設定だけでなく、実行中もコンソール上部のコントロールボタン（AgentControls）で柔軟に介入できます：

• 一時停止（Pause / FaPause）：現在のサブタスク完了後にエージェントを一時停止させます。生成されたタスク一覧や中間ログが目的に沿っているかを目視で確認できます。
• 再開（Play / FaPlay）：方向性に問題がなければ、再開ボタンを押して次のタスク実行を継続させます。
• 強制停止（Stop / FaStop）：エージェントが同じ推論を繰り返していたり、的外れなタスクを量産し始めた場合、赤色の停止ボタンを押すことでセッションを即時終了（stopped）させ、ストリーミング通信を切断してトークン消費を食い止めます。

4. セルフホスト環境とバックエンドでの環境変数設定

Dockerやソースコードを用いてローカル環境や自社インフラで運用する場合、バックエンドおよびコードレベルで全体の上限を縛ることができます。

バックエンド環境変数での制限

AgentGPTのPythonバックエンド（reworkd_platform）はPydanticを用いて設定を管理しており、環境変数による全体ループ制限に対応しています：

# .env ファイルに記述
REWORKD_PLATFORM_MAX_LOOPS=20

これは platform/reworkd_platform/settings.py の settings.max_loops に反映され、クライアント側が上限を超えようとしてもサーバー側でシャットダウンされます。

フロントエンドのスライダー上限変更

独自に上限を拡張または縮小したい開発者は、Next.jsフロントエンドのコードを直接書き換えることが可能です：

• next/src/pages/settings.tsx 内のスライダー設定：

  <Input
    label={`${t("LOOP")}`}
    value={settings.customMaxLoops}
    name="loop"
    type="range"
    onChange={(e) => updateSettings("customMaxLoops", parseFloat(e.target.value))}
    attributes={{
      min: 1,
      max: 50, // 必要に応じて上限を変更
      step: 1,
    }}
    helpText={t("CONTROL_THE_MAXIMUM_NUM_OF_LOOPS")}
    icon={<FaSyncAlt />}
    disabled={disableAdvancedSettings}
  />
  

• next/src/utils/constants.ts 内の定数変更：

  export const DEFAULT_MAX_LOOPS_FREE = 25 as const;
  export const DEFAULT_MAX_LOOPS_CUSTOM_API_KEY = 10 as const;
  

5. タスク出力と成果物のエクスポート

エージェントが目標を完了した際、あるいはループ上限や手動停止で終了した際、得られたデータを素早くエクスポートすることで、セッション再読み込みによる消失や再実行によるコスト重複を防止できます。

コンソール画面のエクスポートメニュー

チャットウィンドウの右上ヘッダー（MacWindowHeader）にある Export アイコン（CgExport）から、3通りの方法で出力できます：

1. クリップボードへコピー（Copy）：
   • 画面上に描画されたメッセージ全体のテキスト（innerText）を抽出します。
   • 目標、追加されたサブタスク、実行ログ全体をプレーンテキストとしてクリップボードへ即座にコピーします。
2. 画像保存（Image / PNG）：
   • html-to-image ライブラリを使用して、スクロール可能なメッセージ一覧（element.scrollHeight）全体をDOMレンダリングします。
   • agent-gpt-output.png として高解像度画像をダウンロードし、視覚的な記録や共有資料として活用できます。
3. 構造化PDF（PDF）：
   • @react-pdf/renderer を利用した PDFButton により、メッセージ履歴をセクション別に構造化してPDF生成します：
     • Agent Goal（全体目標）
     • Adding Task（派生したサブタスク）
     • Executing（実行したタスクと取得された調査結果）
   • 整形された my-document.pdf をダウンロードでき、報告書や提出資料としてそのまま利用可能です。

プラットフォームの一括エクスポートとデータベース連携

• 一括エクスポート（Bulk Exports）：Reworkdのクラウドプラットフォーム機能では、app.reworkd.ai/exports から特定のグループや実行ジョブの全データをCSVやJSON形式でまとめてダウンロードできます。
• DB直接取得：セルフホスト運用時、実行履歴はMySQL / SQLiteデータベースの agent_run および agent_task テーブルに蓄積されます。FastAPIのRESTエンドポイント（/api/agent/execute など）やSQLクエリから直接データを取得し、後続のデータ基盤へパイプライン連携できます。

6. コスト管理の実践ベストプラクティス

1. 実行前のループ数チェックを習慣化：タスク投入前に必ず Settings を確認し、検証フェーズではループ数を 5 〜 10 程度に抑えて実行します。
2. ループ数とトークン制限の併用：Loop 数に加え、maxTokens（1250 〜 2000など）も同時に制限することで、呼び出し回数と1回あたりの生成長の両面から予算を保護します。
3. 序盤のサブタスクを監視：最初の2〜3タスクが意図通りに分解されているかを観察し、脱線が確認されたら迷わず Pause や Stop で中断します。
4. 完了・停止直後のエクスポート：エージェントの停止直後に Copy または PDF で即座にログを保存し、リロードによるデータ消失を防ぎます。

(※ オープンソース版 reworkd/AgentGPT は2026年1月にアーカイブされ読み取り専用となっています。自社フォークや派生基盤を運用する開発者は、本アーキテクチャパターンを踏まえて安全策とエクスポート機能を保守してください。)

参考文献

• AgentGPT
• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser.
• AgentGPT Settings Page Component
• AgentGPT Console Window Header Component
• AgentGPT PDF Export Implementation
• AgentGPT Backend Platform Settings
• AgentGPT Bulk Exports Documentation