定期実行エージェントとは｜30日回したら、同じ件を23倍起票していた

定期実行エージェントとはどういう構成なのか

人が話しかけずに、決まった時刻や出来事をきっかけに動かす構成です。対話しないぶん、止め方と再開の仕方を先に決めておきます。

定期実行エージェントは、人が画面を開かなくても、決まった時刻に自動で動く構成です。毎朝の未処理案件の確認、日次の集計、届いたメールの仕分けなどに使われます。

対話しない形で動かす

実行の仕方としては、対話用の画面を使わずコマンドから呼ぶ形になります。Anthropicの案内でも、対話しない形で動かすには実行時に依頼の文と必要な設定を渡すと説明されています。

同じ文書には、この仕組みがClaude Codeと同じツール、同じ実行の繰り返し、同じ文脈の管理を提供するとも書かれています。動きが変わるわけではなく、入口が変わるだけです。

きっかけの種類

1. 時刻で動かす。毎朝9時、毎週月曜など
2. 出来事で動かす。ファイルが置かれた、通知が届いた
3. 前の処理の完了で動かす。集計が終わったら報告を作る
4. 人が押したときだけ動かす。これは定期実行ではない

1番目と2番目が中心になります。どちらの場合も、動いた結果を誰も見ていない時間が生まれる点が対話との違いです。

止め方を先に決める

見ていない時間があるということは、間違ったまま動き続ける時間もあるということです。1回あたりの上限と、異常時に止める条件を先に決めてください。

30日回したら、同じ件を23倍起票していた

30日ぶんを数え上げました。毎回全件を見る構成は17,220件を処理し、本来必要な748件に対して16,472件を重複して起票します。

定期実行エージェントの対象の決め方で何が変わるのかを、30日ぶん数えました。条件は初日400件、1日12件ずつ増える対象です。

断っておくと、これは実運用を計測したものではありません。件数の増え方を置いて積み上げた数え上げです。置いた値はコードに書いてあります。

const DAYS = 30;
const INITIAL = 400;      // 初日時点で存在する件数
const NEW_PER_DAY = 12;   // 1日に増える件数

// 全件方式: 毎日すべてを見る。処理済みかどうかを持たないので毎回起票する
function scanAll() {
  let processed = 0, filed = 0, total = INITIAL;
  for (let d = 1; d <= DAYS; d++) {
    processed += total;
    filed += total;          // 見た件すべてを起票してしまう
    total += NEW_PER_DAY;
  }
  return { processed, filed };
}

初日 400件、1日 12件ずつ増える対象を 30日ぶん処理したとき

方式        処理した件数  起票した件数  本来の件数
毎回全件        17220件       17220件        748件
差分だけ          748件         748件        748件

毎回全件方式の重複起票: 16472件（本来の 23.0倍）
差分方式の重複起票:   0件

10日目の実行が失敗した場合の差分方式（前回の実行時刻を基準にした場合）
  処理した件数: 748件 / 本来 748件
  取りこぼし:   0件

差が桁で開きました。17,220件のうち16,472件は、前日までに処理済みの件をもう一度処理したものです。

毎日ゼロから見てしまう

原因は単純で、処理済みかどうかを記録していないためです。毎朝起動したエージェントには、昨日の自分が何をしたかの情報がありません。

対話であれば履歴が残りますが、定期実行では毎回まっさらな状態から始まります。ですから記録は外に持つしかありません。

実行が飛んでも拾える

差分方式で気になるのが、実行が失敗した日の扱いです。数え上げでは10日目を止めましたが、取りこぼしは0件でした。

前回いつ動いたかを基準にしているためです。11日目に動いたとき、9日目以降に増えた分をまとめて拾います。「昨日の分」と固定してしまうと、この日は抜けます。

定期実行にする前に決めておくこと

前回の実行時刻の保存先、処理済みの記録、費用の見張り方。この3つを決めてから自動化してください。

定期実行エージェントを組む前に、人が見ていない時間に何が起きうるかを先に潰しておきます。前の節の23倍も、その一例です。

外に持つべき記録

1. 前回いつ動いたか。差分の基準になる
2. どの件を処理済みか。二重起票を防ぐ
3. 実行が成功したか。失敗が続いていないかを見る
4. 今日の会話の内容。これは持ち越さなくてよい

4番目は不要です。むしろ持ち越すと、前日の判断に引きずられて同じ誤りを繰り返します。持ち越すのは事実だけにしてください。

費用を見張る

人が見ていないぶん、費用の急増に気づくのが遅れます。ですから実行のたびに費用を記録してください。

Anthropicの説明でも、出力形式を指定すると応答に合計の費用とモデルごとの内訳が含まれ、呼び出しごとの支出を追えるとされています。管理画面を見に行かなくても記録できます。

止まる条件を決める

定期実行は、間違ったまま何日も動き続けることがあります。1回あたりの処理件数に上限を置き、それを超えたら止めて知らせる作りにしてください。

前の節の例でいえば、1日の処理が想定の20倍になった時点で止まっていれば、16,472件の重複は起きませんでした。上限の置き方はエージェントの費用管理の記事で、実行できる操作の絞り方は権限モデルの記事で扱っています。