長時間実行エージェントの設計 — 状態・評価・再開
長時間のエージェント作業を安定させるために、状態の永続化、完了条件、評価、チェックポイント、再開手順を設計します。
長時間実行は「長い会話」ではない
数時間から複数セッションにまたがる作業では、会話の継続だけに依存できません。コンテキストの圧縮、プロセス停止、認証切れ、テスト失敗、人間の承認待ちが起きても、現在地を復元できる必要があります。
長時間実行の基本単位は、次の状態遷移です。
目標を読む
→ 次の小さな作業を選ぶ
→ 実行する
→ 外部の証拠で評価する
→ 状態を保存する
→ 続行・再試行・人間確認・終了を決めるこの反復制御はループエンジニアリング、実行環境と検証経路はハーネスエンジニアリング、各反復へ渡す情報の選択はコンテキストエンジニアリングの対象です。
失敗しやすい箇所
| 失敗 | 症状 | 設計上の対策 |
|---|---|---|
| 状態の喪失 | 再開後に同じ調査や変更を繰り返す | 進捗と判断をファイルや状態ストアへ保存 |
| 早すぎる完了 | 一部だけ動き、要件全体は未完了 | 受け入れ条件と完了判定を分離 |
| 無限再試行 | 同じエラーを繰り返す | 上限、エラー分類、エスカレーション条件 |
| 方向の逸脱 | 本来の目的より周辺改善を優先する | スコープ、非対象、次の一手をチェックポイントに記録 |
| 副作用の重複 | 再開時に投稿や決済を二重実行する | 冪等キー、実行済み記録、人間承認 |
永続化する状態
最低限、次の情報をセッション外へ残します。
objective: 認証機能を新方式へ移行する
status: in_progress
completed:
- 既存認証フローの調査
current_step: API境界のテスト追加
decisions:
- 既存セッション形式は移行期間中も受理する
evidence:
- npm test -- auth が成功
next_action: 失敗系テストを追加する
blocked_by: null
retry_count: 0保存先は、リポジトリ内の進捗ファイル、データベース、ワークフローエンジンなど、作業の性質に合わせます。秘密情報や短期トークンは進捗文書へ書きません。
完了条件を先に定義する
長時間作業では「かなり進んだ」と「完了した」を分けます。完了条件には、成果物と検証方法を対で書きます。
## Done criteria
- 正常系と主要な異常系のテストが成功する
- 型検査とビルドが成功する
- 既存セッションからの移行経路を確認できる
- 変更差分に対象外のファイルが含まれない
- 本番反映前に人間が承認する固定のカバレッジ率だけで品質を代理させず、重要なリスクに対応するテストがあるかを確認します。
Planner・Generator・Evaluator
Anthropicは長時間アプリ開発の実験で、Planner、Generator、Evaluatorの役割を分けました。
- Planner: 短い要求を仕様と作業単位へ変換する
- Generator: 作業単位を実装し、証拠を収集する
- Evaluator: 仕様と成果物を独立に照合する
役割分離は、複雑なUIや長い実装で自己評価の偏りを抑える手段です。すべてのタスクで3つのエージェントを動かす必要はなく、CIや人間レビューで十分な場合もあります。
チェックポイントと再開
チェックポイントには、完了したことだけでなく、未完了、検証結果、次の一手を書きます。再開時は次の順で復元します。
- 目標と対象外を読む
- 現在の成果物と差分を確認する
- 前回の検証結果を、必要なら再実行する
- 外部状態が変化していないか確認する
- 記録済みの次の一手から再開する
コミットは有効なチェックポイントですが、未検証の変更を完了扱いにしません。外部APIへの副作用がある場合は、コードの状態と実行済み状態を別々に記録します。
再試行と停止条件
再試行は、原因に応じて制御します。
| 原因 | 対応 |
|---|---|
| 一時的なネットワーク障害 | 待機時間を増やして限定回数再試行 |
| 入力や型の不備 | 入力を修正して再実行 |
| 権限・承認不足 | 自動回避せず人間へ確認 |
| 同一失敗の反復 | ループを止め、ログと試行内容を提示 |
| 評価基準の矛盾 | 仕様決定者へエスカレーション |
回数上限だけでなく、同じ失敗が続いたか、進捗があるか、費用や時間が上限に近いかも停止判断へ使います。
モデル更新でハーネスを見直す
Anthropicの公開実験では、使用モデルを変えることで、コンテキストの扱い、スプリントの区切り、評価役との連携方法を簡素化できる場面がありました。これは「新しいモデルなら長時間実行に制御が不要」という意味ではありません。
モデル、ツール、タスクが変わったら、同じ評価セットで次を再測定します。
- 完了率と要件漏れ
- 再試行回数
- 人間の介入回数
- 実行時間と費用
- 復旧に必要な時間
有効性が確認できない分割やリセットは外し、失敗を防いでいるガードレールは残します。
実装チェックリスト
- 目標、対象外、完了条件が保存されている
- 現在地と次の一手をセッション外から復元できる
- ツール実行と評価結果が追跡できる
- 再試行上限と停止条件がある
- 副作用の重複を防止できる
- 高リスク操作に人間の承認点がある
- 中断後の再開手順を実際に試している