◈ Agents & Manager/2026-06-29上級

止まったまま生きているエージェントを見抜く — 進捗ハートビートとウォッチドッグの設計

プロセスは生きているのに6時間まったく進んでいない、という沈黙状態を見抜くために、進捗マーカーの外部化と無進捗タイムアウトによるウォッチドッグを設計しました。安全な止め方や導入の順序、夜間の記事生成エージェントで踏んだ落とし穴も共有します。

バックグラウンドエージェント³ Antigravity³⁷⁶ウォッチドッグタイムアウト設計運用設計²⁷

✦ プレミアム記事

朝、ダッシュボードは緑のままでした。プロセスは動いている、CPUもわずかに食っている、ログの最終行も「モデルに問い合わせ中」で止まっている——なのに、6時間前から1文字も先に進んでいませんでした。

私自身、個人開発で記事生成のエージェントを夜間に走らせています。その夜は外部APIの応答が返らず、リトライにも入らず、ただ待ち続けていました。プロセスは確かに生きていました。だから「生きているか」を見る監視は、ずっと緑を返し続けていたのです。問題は、生存と進捗を同じものとして扱っていたことでした。

「生きている」と「進んでいる」は別の問い

サーバ監視の習慣で、私たちはつい「プロセスが存在するか」「ポートが応答するか」を健全性の指標にします。短時間で終わるリクエストならそれで十分です。けれどバックグラウンドエージェントは、1回のジョブが数分から数十分かかり、その間ずっと「正常に存在しつつ、何も進めていない」状態になり得ます。

停滞の典型は、応答が返らない外部呼び出し、解けない依存関係を前にした無限の思考ループ、そして自分で自分を待つデッドロックです。どれもプロセスは生きています。生存監視（liveness）はこれらを一切捕まえられません。必要なのは**進捗監視（progress）**です。

監視の種類	答える問い	停滞を捕まえられるか
生存監視（プロセス存在・ポート応答）	動いているか	捕まえられない
ログ出力の有無	何か喋っているか	「待機中」を吐き続けると誤魔化される
進捗監視（前進した量）	仕事が進んだか	捕まえられる

ログを吐いているかどうかで判断するのも危険です。「待機中…」を出し続けるコードは、喋ってはいても進んでいません。見るべきは饒舌さではなく、前進した量です。

進捗をマーカーとして外に出す

進捗で見張るには、まずエージェント自身が「ここまで進んだ」を外部から観測できる形で残す必要があります。単調増加するステップ番号と、最後に前進した時刻を、共有できる場所へ書き出します。

# progress.py — 進捗マーカーを共有ファイルに刻む
import json, os, tempfile, time
 
def mark_progress(path: str, step: int, note: str = "") -> None:
    """step は単調増加。前進したときだけ呼ぶ（待機中には呼ばない）。"""
    payload = {"step": step, "note": note, "ts": int(time.time())}
    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path) or ".")
    with os.fdopen(fd, "w") as f:
        json.dump(payload, f)
    os.replace(tmp, path)        # 原子的に差し替え

ここで大事なのは、前進したときだけ mark_progress を呼ぶという規律です。ハートビートを「定期的に必ず打つ」設計にすると、停滞していても鼓動だけは続き、結局は生存監視に逆戻りします。鼓動は「生きている合図」ではなく「進んだ合図」でなければ意味がありません。

エージェント本体では、意味のある区切りごとにステップを進めます。

mark_progress(P, 1, "収集完了")
# ... 外部API呼び出し（ここが固まりやすい） ...
mark_progress(P, 2, "下書き生成")
# ... 整形 ...
mark_progress(P, 3, "検証通過")

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦「生きているか」と「進んでいるか」はまったく別の問いだと理解でき、生存監視だけでは沈黙した停滞を見逃す理由が腑に落ちる

✦進捗ハートビート・無進捗タイムアウト・安全な強制終了までを通した完全な実装（Python のウォッチドッグと bash の組み込み例）。そのまま自分のジョブに差し込める

✦個人開発で夜間に走らせていたエージェントが朝まで無言で固まっていた実体験から、どこに進捗マーカーを刻むべきかの判断基準が得られる

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

無進捗タイムアウトでウォッチドッグを作る

別プロセスのウォッチドッグが、この進捗マーカーを見張ります。判定はシンプルです。「最後に前進してからの経過時間」が閾値を超え、かつステップ番号が動いていなければ、停滞とみなします。

# watchdog.py — 無進捗が続いたら停滞と判定し、対象を止める
import json, os, signal, time
 
def watch(progress_path: str, pidfile: str, stall_sec: int = 600, poll: int = 30):
    last_step, last_change = -1, time.time()
    while True:
        time.sleep(poll)
        try:
            d = json.load(open(progress_path))
        except (FileNotFoundError, json.JSONDecodeError):
            continue                      # まだ書かれていない・書き込み途中
        if d["step"] != last_step:
            last_step, last_change = d["step"], time.time()   # 前進を観測
            continue
        if time.time() - last_change > stall_sec:
            pid = int(open(pidfile).read().strip())
            terminate(pid)                # 無進捗が閾値超え → 停止
            return
 
def terminate(pid: int):
    # まず穏当に（後始末の猶予を与える）、それでも残れば強制終了
    try:
        os.kill(pid, signal.SIGTERM)
    except ProcessLookupError:
        return
    time.sleep(20)
    try:
        os.kill(pid, signal.SIGKILL)
    except ProcessLookupError:
        pass

stall_sec は「この作業なら、ここまで無音なら異常」という肌感覚で決めます。私の記事生成ジョブでは、最長のモデル呼び出しの実測がおおむね90秒だったので、その数倍に余裕を持たせて10分（600秒）にしています。短すぎると正常な長考を殺し、長すぎると朝まで気づけません。

止め方そのものを設計する

検知できても、止め方が雑だと別の事故を生みます。いきなり強制終了すると、書きかけの成果物が中途半端に残ります。だから二段構えにします。

まず SIGTERM を送り、エージェント側のシグナルハンドラに後始末（一時ファイルの削除・ロックの解放・進捗マーカーへの「中断」記録）をさせます。
それでも一定時間内に終わらなければ SIGKILL で確実に落とします。

エージェント本体には、後始末を引き受けるハンドラを仕込んでおきます。

cleanup() {
  rm -f "$TMP_OUT" 2>/dev/null || true     # 書きかけを残さない
  release_lease 2>/dev/null || true        # ロックを手放す
  echo '{"step":-1,"note":"aborted"}' > "$PROGRESS"
  exit 143                                  # 128 + SIGTERM
}
trap cleanup TERM INT

この「中断」を進捗マーカーに残しておくと、次回の起動時に「前回は停滞で落ちた」と分かり、原因調査の起点になります。本番運用では、この一行があるかないかで翌朝の調査時間がまるで変わりました。

よくある落とし穴と回避

ひとつ目の落とし穴は、ハートビートを進捗から切り離してしまうことです。タイマーで定期的に鼓動を打つと、停滞中も鼓動が続き、ウォッチドッグが永遠に発火しません。鼓動は必ず「前進」に紐づけてください。

ふたつ目は、ウォッチドッグをエージェントと同じプロセス内に置くことです。本体がイベントループごと固まると、内蔵のタイマーも一緒に固まります。ウォッチドッグは必ず別プロセスにし、共有ファイル越しに観測する構成を推奨します。

みっつ目は、stall_sec を全ジョブで一律にすることです。30秒で終わる整形ジョブと、5分かかる大規模生成ジョブに同じ閾値を当てると、どちらかが必ず誤判定します。ジョブ種別ごとに閾値を持つのが現実的で、Dolice Labs の運用では、ジョブ定義のメタデータに stall_sec を持たせてジョブごとに切り替えています。

どこから入れるか

最初から完璧な監視網を敷く必要はありません。実体験として効いたのは、まず一番長く固まると困るジョブ一本に進捗マーカーを3つだけ刻み、別プロセスのウォッチドッグを当てる、という最小構成でした。

一晩走らせれば、SIGTERM が一度でも飛んだかどうかで「沈黙した停滞が実際に起きているか」が分かります。起きていなければ閾値はそのまま、頻発するなら原因（多くは外部呼び出し）に手当てを入れる。緑のダッシュボードを信じ切らず、前進した量を見張る——この一点に切り替えるだけで、朝の「なぜか終わっていない」は確実に減らせると考えています。