エージェントループエンジン

概要

**エージェントループエンジン（Agent Loop）**は、ワークスペース Work モジュールの中核的な実行メカニズムです。AI Agent による自律的な推論・実行ループを駆動します。すなわち、タスクの分析 → ツールの選択 → 操作の実行 → 結果の評価 → 推論の継続、というサイクルを、タスクが完了するか終了条件が発動するまで繰り返します。

エンジンは provider-agnostic アーキテクチャを採用しており、統一された LLM Adapter インターフェースを通じて複数のモデルプロバイダーをサポートします。

アーキテクチャ

LLM アダプター

AgentEngine │ ├── OpenAIAdapter │ ├── Responses API（増分状態管理） │ └── Chat Completions API（全量コンテキスト） │ └── AnthropicAdapter └── Messages API（ネイティブ streaming + thinking）

                      
                      AgentEngine
    │
    ├── OpenAIAdapter
    │   ├── Responses API（増分状態管理）
    │   └── Chat Completions API（全量コンテキスト）
    │
    └── AnthropicAdapter
        └── Messages API（ネイティブ streaming + thinking）

このコードブロックをポップアップで表示

アダプターは以下を自動的に処理します:

メッセージフォーマット変換（OpenAI ↔ Anthropic）
ツール定義の変換
Think Tag 処理（DeepSeek などのモデルの <think> タグを自動的に除去）

ループフロー

┌─ 事前検証 ──────────────────────────────────────────────┐ │ 入力予算の 60% を超えるプロンプトを拒否し、暗黙的な切り詰めを防止 │ └──────────────────────────┬──────────────────────────────┘ ▼ ┌─ メインループ（Round 0 → maxTurns-1）─────────────────────────┐ │ │ │ ① コンテキスト管理 │ │ - 予防的なツール結果の切り詰め（Layer 1） │ │ - 圧縮が必要かどうかをチェック（shouldPreemptiveCompact） │ │ │ │ ② LLM 呼び出し │ │ - ストリーミング推論（text_delta + thinking + tool_use） │ │ - イベントをリアルタイムで UI にプッシュ │ │ │ │ ③ ツール実行 │ │ - validateToolCalls → 妥当性を検証 │ │ - 並行パーティション → concurrency メタデータでグループ化 │ │ - 並列実行 → 結果を正規化 │ │ │ │ ④ 終了判定 │ │ - ツール呼び出しなし → 終了（end_turn） │ │ - 上限到達 → 終了（max_rounds/max_budget/deadline） │ │ - 異常 → 終了（circuit_breaker/fatal_error） │ │ - ツール呼び出しあり → 次のラウンドへ継続 │ │ │ └──────────────────────────────────────────────────────────┘

                      
                      ┌─ 事前検証 ──────────────────────────────────────────────┐
│ 入力予算の 60% を超えるプロンプトを拒否し、暗黙的な切り詰めを防止 │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─ メインループ（Round 0 → maxTurns-1）─────────────────────────┐
│                                                          │
│  ① コンテキスト管理                                       │
│     - 予防的なツール結果の切り詰め（Layer 1）              │
│     - 圧縮が必要かどうかをチェック（shouldPreemptiveCompact） │
│                                                          │
│  ② LLM 呼び出し                                          │
│     - ストリーミング推論（text_delta + thinking + tool_use） │
│     - イベントをリアルタイムで UI にプッシュ               │
│                                                          │
│  ③ ツール実行                                            │
│     - validateToolCalls → 妥当性を検証                    │
│     - 並行パーティション → concurrency メタデータでグループ化 │
│     - 並列実行 → 結果を正規化                             │
│                                                          │
│  ④ 終了判定                                              │
│     - ツール呼び出しなし → 終了（end_turn）               │
│     - 上限到達 → 終了（max_rounds/max_budget/deadline）   │
│     - 異常 → 終了（circuit_breaker/fatal_error）          │
│     - ツール呼び出しあり → 次のラウンドへ継続             │
│                                                          │
└──────────────────────────────────────────────────────────┘

このコードブロックをポップアップで表示

ループパラメータ

パラメータ	デフォルト値	説明
`maxTurns`	25	最大ループラウンド数
`maxErrors`	—	連続ツールエラーの閾値
`maxBudgetInputTokens`	—	入力 token 予算の上限
`maxExecutionMs`	—	実行時間の上限（ミリ秒）
`snapshotStrategy`	`every_tool_round`	スナップショット保存戦略
`resumeSessionId`	—	中断したセッションを復元する ID

8 種類の終了条件

終了理由	トリガー条件
end_turn	Agent がタスクを完了し、これ以上ツール呼び出しがない
max_rounds	maxTurns の上限に到達（デフォルト 25 ラウンド）
circuit_breaker	LLM 呼び出しが連続 5 回失敗
no_tool_calls	LLM レスポンスにツール呼び出し要求がない
user_cancel	ユーザーが手動で中止
context_overflow	コンテキスト圧縮後もオーバーフローが発生
fatal_error	回復不能なエラー（認証失敗、課金問題など）
compaction_exhausted	圧縮リトライ回数を使い切った（最大 5 回）

サーキットブレーカーメカニズム

LLM の連続失敗による無限リトライを防止します:

パラメータ	値	説明
`CIRCUIT_OPEN_THRESHOLD`	5	連続 5 回の失敗でサーキットブレーカーを発動
`CIRCUIT_OPEN_WAIT_MS`	60,000	サーキットブレーカーが開いた後に 60 秒間クールダウン

エラー分類とリトライ戦略:

エラータイプ	戦略
`rate_limit`	指数バックオフ + ランダムジッターでリトライ
`timeout` / `overloaded`	即時リトライ
`context_overflow`	コンテキスト圧縮を発動
`auth` / `billing` / `model_not_found`	直接スロー（リトライしない）

ストリーミングイベント

Agent の実行プロセスは、ストリーミングイベントを通じて UI にリアルタイムで通知されます:

イベントタイプ	データ	説明
`text_delta`	テキスト断片	Agent のテキスト出力の増分プッシュ
`thinking`	思考断片	ネイティブな思考連鎖の内容（Anthropic thinking モデル）
`tool_use_start`	ツール名 + パラメータ	ツール呼び出しの開始
`tool_result`	実行結果	ツール実行の完了
`error`	エラー情報	実行プロセス中のエラー
`done`	終了理由	当該ラウンドのループ終了

サブエージェントのイベントは、親 Agent の UI 画面に透過的に伝達されます。

EMA Token キャリブレーション

エンジンは**指数移動平均（EMA）**を用いて token 推定の精度を動的にキャリブレーションします:

パラメータ	値	説明
初期値	3.0 chars/token	保守的な推定（中国語 + コードの混合シーンに適合）
最初の 3 回	平均値で収束	実際の値に素早く近づく
以降	EMA α=0.15	実際の消費を滑らかに追跡
フィルタ	0.5 < observed < 8	異常値を除外

LLM 呼び出しのたびに、実際の token 消費でキャリブレーション係数を更新し、コンテキスト予算の推定がますます正確になるようにします。

セッションスナップショット

セッション状態の永続化をサポートし、予期しない中断による進捗の喪失を防ぎます:

戦略	トリガータイミング
`every_tool_round`（デフォルト）	ツール呼び出しが完了するたび
`every_round`	LLM とのやり取りのラウンドごと
`manual`	手動トリガーのみ

スナップショットは JSON ファイルとして保存され、アトミックな書き込み（.tmp + rename）を用いてファイルの破損を防止します。resumeSessionId を通じて、中断したセッションを復元できます。

ユーザーにとっての意味

Agent Loop は、あなたが実感できる「Agent が連続して作業している」能力です。 「このプロジェクトのコード構造をリファクタリングして」と言えば、Agent は提案を一言返して止まるのではなく、自動的にファイルを閲覧し、構造を分析し、一つずつ修正し、テストを実行して、完了するまで作業を続けます。

あなたが観察できる現象:

Agent が複数のツールを連続して呼び出し（ファイルの一覧 → ファイルの読み取り → ファイルの修正 → テストの実行）、画面上にツール呼び出しが次々に表示されます
Agent が連続 5 回失敗した場合（API タイムアウトなど）、無限にリトライするのではなく 60 秒間一時停止します。しばらくの待機の後、Agent が問題に遭遇したことを伝えるのが見られます
デフォルトでは最大 25 ラウンドまで実行され、極めて複雑なタスクは 25 ラウンド後に停止し、「最大ラウンド数に到達しました」と伝えることがあります

あなたができること:

いつでも停止ボタンをクリックして Agent の実行を中止できます
Agent の実行方向がずれた場合は、中止してからより明確な指示を出します
特に複雑なタスクでは、Agent にまず計画を立ててから実行させることができます（「まず計画を立てて、私が確認してから実行して」）