AIエージェントの上限付きループ: チェック、再試行、停止ルール

Table of Contents
目標ループは、定義した結果がチェックに合格するか、停止ルールが発動するまで作業を繰り返します。 有用なループは現在の状態を読み取り、範囲を限定した操作を1つ実行し、結果を確認して、起きたことを記録します。「成功するまで試し続ける」といった曖昧な指示には、信頼できる完了条件がありません。
学習目標: 失敗すると分かっているチェックを含む上限付きのラボループを実行し、停止の判断を記録します。
主なポイント
- 目標: 観察できる形で表した結果。
- 状態: 現在のファイル、出力、エラー、ソースのリビジョン。
- チェック: 目標に関連付けたテストまたはレビュー。
- 再試行予算: 1つの失敗に対して許可する試行の最大数。
- 停止ルール: 終了するか、人の判断を求める必要がある条件。
始める前に
前提資料: タスクパケット 、 検証記録 、 委任のレッスン 。45分を確保してください。難易度は中級です。最初に失敗するチェックを事前に把握できるよう、合成ラボの新しいコピーを使います。
ループの契約を書く
ステータスで絞り込む依頼では、 再試行の前に契約を定めます。
目標: デフォルト出力を変えずに --status open|done をサポートする。
参照元: docs/requirements.md、リビジョン 1。
許可ファイル: task_report.py と対象を絞ったテスト。
確認項目: 単体テスト、件数 4/2/2、不正な値でゼロ以外の終了コード。
再試行の上限: 最初の試行後、編集は最大 2 回。
直ちに停止: 参照元との矛盾、予期しないファイル変更、秘密情報の露出、
またはこの依頼と無関係なベースラインの失敗。
引き継ぎ: 最終差分、コマンド、出力、試行回数、未解決の問題を報告する。
予算はタスクの方針であり、 製品の既定値ではありません。小さなラボ課題を診断し、失敗の繰り返しを隠さないためには、再試行を2回に制限すれば十分です。本番タスクではリスクとレビューについて別途判断が必要です。
状態表を使う
| 手順 | 記録する状態 | 判断 |
|---|---|---|
| 読む | ソースのリビジョンと初回の結果 | 初期状態が異なる場合は停止 |
| 実行する | 変更したファイルと実行した操作 | 範囲外の変更を拒否 |
| 確認する | 正確なテストと手動の出力 | 受け入れるか原因を調べる |
| 再試行する | 失敗の原因と新しい仮説 | 予算内でのみ続行 |
| 引き継ぐ | 最終状態と次の担当者 | 合格またはブロック後に停止 |
最後のメッセージだけでなく、試行を記録してください。 3回の未記録の編集後にテストが通っても、何が変わったか分かりません。失敗、見直した仮説、新たな証拠を短く記録します。
失敗を確認する
最初の試行の例: エージェントがフィルターとテストを追加します。open は2を出力しますが、--status invalid は0を出力して正常終了します。要件では無効な値に対してゼロ以外の終了コードを求めています。このチェックを失敗として記録します。
診断: 引数の検証を確認します。エージェントは未知の値をエラーではなく空の一致として扱っています。カウント前に許可された値を検証する、範囲を限定した修正を依頼します。無効なケースとそれまでのチェックをすべて再実行します。
試行 1: 不正なステータスが成功を返したため、受け入れ条件に失敗した。
判明した原因: 許可された値の検証がない。
試行 2 の依頼: 未対応の値を拒否し、件数 4/2/2 を維持する。
必要な証拠: 全テストの実行結果と不正なコマンドの終了ステータス。
2回目の試行で期待する結果: invalid に対して明確なエラーとゼロ以外の終了コードが返り、有効なカウントは変わりません。2回目も失敗した場合は、新しい原因を特定してから最後の再試行を使います。同じ依頼を繰り返しても診断にはなりません。
曖昧な結果に対処する
結果を出さずにプロセスが止まっても成功ではありません。 書き込みの可能性がある後にツールがタイムアウトしたら、再実行の前にファイルとGitの状態を確認します。接続サービスが結果不明と報告した場合は、外部操作を繰り返す前に現在の状態を読み取ります。ラボ外で送信、投稿、書き込みが重複すると実際のリスクになります。
人のレビューのために停止してください。 要件が別の承認済みソースと矛盾する場合、権限不足で操作できない場合、再試行予算を使い切った場合、または依頼された操作が公開の境界を越える場合が該当します。引き継ぎには正確な状態と未解決の判断事項を記載します。
ループとモニターを分ける
編集ループは範囲を限定したタスクの中で動き、操作ごとに結果を確認します。スケジュールされたモニターは後で起動し、条件を調べます。モニターには独自の頻度、変更しきい値、通知ルール、停止条件が必要です。ラボの編集ループを定期タスクに変えないでください。次のレッスンでは、常時稼働システムを有効にする前に評価します。
制御されたループを実行する
変更前のラボから始めます。 2つのベースラインテストは合格します。新しい展開先で、下記のチェックを含む tests/test_loop_contract.py を作成します。このファイルはスターターに存在しない機能を要求するものです。保守対象のスターターZIPには含めません。
"""One controlled failing check for the status-filter exercise."""
import subprocess
import sys
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
class LoopContractTests(unittest.TestCase):
def test_open_status_count(self):
result = subprocess.run(
[sys.executable, str(ROOT / "task_report.py"),
str(ROOT / "tasks.json"), "--status", "open"],
capture_output=True, text=True, check=False,
)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout.strip(), "Total tasks: 2")
if __name__ == "__main__":
unittest.main()
python3 -m unittest discover -s tests -v を実行します。 2つの既存テストは合格し、新しい契約テストはスターターが --status に対応していないため失敗するはずです。実際の失敗内容を記録します。レッスン0に従ってGitを初期化した場合は、git status --short の結果も記録してください。そうでなければ、変更したファイルを未変更の展開内容と比較します。Windowsでは、セットアップがランチャーを使う場合に py -3 を使います。
試行回数を3回に設定します: 最初の編集と、最大2回の修正です。上記のループ契約をエージェントに渡し、範囲を限定した編集を1つ依頼します。各試行後に変更ファイルを確認し、すべてのテストを再実行して、既定の動作、open、done、無効な値を試します。次の試行前に失敗原因を記録します。テスト合格、無関係なベースラインの失敗、範囲外の変更、または3回目の失敗で停止します。
学習ルート: 赤いテストを記録した後、この新しいコピーに レッスン5の完全な解答 を適用します。同じチェックを再実行し、エージェントの編集を実行しなかったことを記録します。制御された契約テストは残してください。合格させるために弱めたり削除したりしないでください。
| 試行 | 状態と観察結果 | 判断 |
|---|---|---|
| 編集前 | 2つのベースラインテストは合格、新しい open チェックは失敗 | 範囲を限定した編集を1つ行う |
| 各編集後 | 正確なテスト、カウント、無効値での終了コード、変更ファイルを記録 | 受け入れ、診断、または停止 |
| 予算終了時 | 残った失敗と現在の差分を記録 | 追加試行せず引き継ぐ |
練習して確認する
成果物: 制御された失敗テスト、前後で観察した出力、試行ログ、最終的な受け入れまたは停止の判断。最初の編集で合格した場合は、試行を1回だけ記録します。ログを埋めるために2回目の失敗を作らないでください。
完了チェック: 契約にソース、ファイル範囲、観察可能なチェック、再試行の上限、即時停止条件を少なくとも1つ、引き継ぎが含まれています。記録には実際の赤いテスト、その後のチェック結果、合格または予算による停止が含まれています。2回目の試行では新しい原因を特定し、1回目と異なる対応をします。
理解度を確認する
- 質問: 最初の赤い契約テストは何を示しますか。回答: 編集前に書いたテストが示すように、スターターには依頼されたステータスフィルターがありません。
- 質問: 試行が残っていても、いつループを止める必要がありますか。回答: 範囲外の変更、権限の不明確さ、または要件の矛盾がある場合です。
トラブルシューティング
- 同じ失敗を繰り返す: 停止して、原因について新しい仮説を立てます。
- チェックが弱くなっている: 元の合格基準に戻します。
- 外部結果が不明: 次の試行前に現在の状態を確認します。
- 予算を使い切った: 失敗を隠さず、記録を引き継ぎます。
次のステップ
任意の 専門エージェント評価 に進むか、 AIワークフローコースの最終プロジェクト に進みます。実行環境については エージェントハーネスガイド を参照してください。
コースナビゲーション: 前へ: エージェントへの委任 、 コース概要 。



