{"meta":{"title":"エージェント ループ","intro":"Copilot CLI がユーザー メッセージをエンド ツー エンドで処理する方法: プロンプトから session.idle。","product":"GitHub Copilot","breadcrumbs":[{"href":"/ja/copilot","title":"GitHub Copilot"},{"href":"/ja/copilot/how-tos","title":"方法"},{"href":"/ja/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/ja/copilot/how-tos/copilot-sdk/features","title":"機能"},{"href":"/ja/copilot/how-tos/copilot-sdk/features/agent-loop","title":"エージェント ループ"}],"documentType":"article"},"body":"# エージェント ループ\n\nCopilot CLI がユーザー メッセージをエンド ツー エンドで処理する方法: プロンプトから session.idle。\n\n\n\n\n\n## Architecture\n\n![図: 説明されたプロセスを示すグラフ図。](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-0.png)\n\n**SDK** はトランスポート層であり、JSON-RPC 経由でプロンプトを **Copilot CLI** に送信し、イベントをアプリに表示します。\n**CLI** は、エージェント ツール使用ループを実行するオーケストレーターであり、タスクが完了するまで 1 つ以上の LLM API 呼び出しを行います。\n\n## ツール使用ループ\n\n`session.send({ prompt })`を呼び出すと、CLI はループに入ります。\n\n![図: 説明されたプロセスを示すフローチャート。](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png)\n\nこのモデルでは、各呼び出しの **会話履歴 (** システム プロンプト、ユーザー メッセージ、および以前のすべてのツール呼び出しと結果) が表示されます。\n\n**主要な分析情報:** このループの各イテレーションは、イベント ログ内の 1 つの `assistant.turn_start` / `assistant.turn_end` ペアとして表示される、1 つの LLM API 呼び出しです。 非表示の呼び出しはありません。\n\n## ターン — その定義\n\n**ターン**は、単一の LLM API 呼び出しとその結果です。\n\n1. CLI は会話履歴を LLM に送信します。\n2. LLM が応答する (場合によってはツール要求あり)\n3. ツールが要求された場合、CLI によって実行されます\n4. `assistant.turn_end` が送出される\n\n通常、1 つのユーザー メッセージは **複数のターン**になります。 たとえば、\"X はこのコードベースでどのように機能しますか?\" のような質問です。 生成される可能性があります:\n\n| 回転 | モデルの動作 | toolRequests? |\n| ------------------------------ | ------------------------------ | ------------- |\n| 1 | | |\n| `grep`と`glob`を呼び出してコードベースを検索する | | |\n| ✅ はい | | |\n| 2 | 検索結果に基づいて特定のファイルを読み取ります | |\n| ✅ はい | | |\n| 3 | より深いコンテキストのためにより多くのファイルを読み取ります | |\n| ✅ はい | | |\n| 4 | 最終的なテキスト回答を生成します | |\n| ❌ いいえ → ループが終了する | | |\n\nモデルは、各ターンで、より多くのツールを要求するか、最終的な回答を生成するかを決定します。 各呼び出しでは **、蓄積されたコンテキスト全体** (以前のすべてのツール呼び出しと結果) が表示されるため、十分な情報が得られたかどうかに関する情報に基づいて判断できます。\n\n## 複数ターンにわたる対話のイベントフロー\n\n![図: 説明されたプロセスを示すフローチャート。](/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png)\n\n## 各ターンをトリガーするのは誰ですか？\n\n| 俳優 | 責任 |\n| --------------- | ----------------------------------------------- |\n| **お客様のアプリ** | を使用して最初のプロンプトを送信します。 `session.send()` |\n| **Copilot CLI** | ツール使用ループを実行します。ツールを実行し、結果を次のターンの LLM にフィードします |\n| **Llm** | ツールを要求するか (ループを続ける)、または最終的な応答を生成するか (停止) を決定します |\n| **SDK** | イベントをそのまま通します。ループは制御しません |\n\nCLI は単に機械的です。つまり、「モデルがツールを要求する → 実行する → もう一度モデルを呼び出す」です。\n**モデル**は、停止するタイミングの意思決定者です。\n\n## `session.idle` と `session.task_complete`\n\nこれらは、非常に異なる保証を持つ 2 つの異なる完了信号です。\n\n### `session.idle`\n\n* ツール使用ループが終了したときに**常に出力されます**\n* **エフェメラル**: ディスクに永続化されず、セッションの再開時に再生されない\n* 意味: \"エージェントは処理を停止し、次のメッセージの準備ができています\"\n* **これを** 信頼できる \"完了\" 信号として使用する\n\nSDK の `sendAndWait()` メソッドは、このイベントを待機します。\n\n```typescript\n// Blocks until session.idle fires\nconst response = await session.sendAndWait({ prompt: \"Fix the bug\" });\n```\n\n### `session.task_complete`\n\n* **必要に応じて出力:** モデルに明示的に通知する必要があります\n* **永続化**: ディスク上のセッション イベント ログに保存\n* 意味: \"エージェントは、タスク全体が満たされたと見なします\"\n* 省略可能な `summary` フィールドを含む\n\n```typescript\nsession.on(\"session.task_complete\", (event) => {\n console.log(\"Task done:\", event.data.summary);\n});\n```\n\n### 自動操縦モード: CLI が `task_complete` を促す\n\n**オートパイロット モード** (ヘッドレス/自律操作) では、CLI はモデルが `task_complete` を呼び出したかどうかをアクティブに追跡します。 ツール使用ループがそれなしで終了した場合、CLI はモデルを微調整する合成ユーザー メッセージを挿入します。\n\n> *\"task\\_complete ツールを使用して、タスクを完了としてまだマークしていません。計画していた場合は、計画を中止し、実装を開始します。タスクが完全に完了するまでは完了しません。*\n\nこれにより、ツール使用ループが効果的に再開されます。モデルはナッジを新しいユーザー メッセージとして認識し、動作を続けます。 また、ナッジは、\\*\\*\\*\\* を途中で呼び出`task_complete`モデルに指示します。\n\n* オープンな質問がある場合は呼び出さないでください。意思決定を行い、作業を続ける\n* エラーが発生した場合は呼び出さないでください。解決してみてください\n* 残りの手順がある場合は呼び出さないでください。最初に完了してください\n\nこれにより、オートパイロットに **2 レベルの完了メカニズム** が作成されます。\n\n1. モデルが概要付きで`task_complete`を呼び出す → CLI が`session.task_complete`を出力する → 完了\n2. モデルがそれを呼び出さずに停止する → CLI が促す → モデルが継続するか、`task_complete` を呼び出す\n\n### `task_complete`が表示されない理由\n\n**対話型モード**（通常のチャット）では、CLI は`task_complete`の入力を促しません。 モデルはそれを完全にスキップする可能性があります。 一般的な理由:\n\n* **会話型 Q\\&A**: モデルは質問に回答し、単に停止します。完了する個別の \"タスク\" はありません\n* **モデルの裁量**: モデルは、タスク完了シグナルを呼び出さずに最終的なテキスト応答を生成します\n* **中断されたセッション**: モデルが完了ポイントに達する前にセッションが終了する\n\nCLI は、セマンティック信号ではなく、機械的なシグナル (ループが終了) であるため、 `session.idle` を出力します (モデルでは完了と見なされます)。\n\n### どちらを使用すべきか\n\n| 利用シーン | 信号 |\n| ---------------------------------- | -- |\n| \"エージェントの処理が完了するまで待ちます\" | |\n| `session.idle` | |\n| ✅ | |\n| | |\n| \"コーディング タスクがいつ完了したかを把握する\" | |\n| `session.task_complete` (ベストエフォート) | |\n| \"タイムアウト/エラー処理\" | |\n| `session.idle` | |\n\n*\n\n`session.error`\n✅\n|\n\n## LLM 呼び出しの数え方\n\nイベント ログ内の `assistant.turn_start` / `assistant.turn_end` ペアの数は、LLM API 呼び出しの合計数と同じです。 計画、評価、または完了チェックの非表示の呼び出しはありません。\n\nセッションのターン数を調べるには:\n\n```bash\n# Count turns in a session's event log\ngrep -c \"assistant.turn_start\" ~/.copilot/session-state//events.jsonl\n```\n\n## 詳細については、次を参照してください。\n\n* [ストリーミング セッション イベント](/ja/copilot/how-tos/copilot-sdk/features/streaming-events): すべてのイベントの種類に対するフィールド レベルの完全な参照\n* [セッションの再開と永続化](/ja/copilot/how-tos/copilot-sdk/features/session-persistence): セッションの保存と再開方法\n* [フックを使った作業](/ja/copilot/how-tos/copilot-sdk/features/hooks): ループ内のイベントをインターセプトする (アクセス許可、ツール)"}