並行エージェントのトークンコストを予算で抑える — 暴走を止めるバジェットガードの設計

タスク単位で予算を割り当てる

まず配分です。私は「実行（run）」を最上位の単位に置き、その中に複数の「タスク（task）」がぶら下がる構造にしました。実行全体の上限と、タスク個別の上限を別々に持たせるのがポイントです。実行全体だけだと1本の暴走を止められず、タスク個別だけだと並行数が増えたときの合計が青天井になるからです。

// budget.ts — 予算の割り当て定義
export type Money = number; // USD 換算。内部はすべて USD で統一する
 
export interface BudgetPolicy {
  runCeiling: Money;        // この実行全体で使ってよい上限
  taskCeiling: Money;       // 1タスクが使ってよい上限
  softRatio: number;        // この割合を超えたら縮退を始める（例: 0.8）
}
 
// モデルごとの単価（per 1M tokens, USD）。実際の請求値に合わせて更新する
export const PRICE_TABLE: Record<string, { input: Money; output: Money }> = {
  "fast":     { input: 0.30, output: 1.50 },
  "balanced": { input: 3.00, output: 15.0 },
  "deep":     { input: 8.00, output: 40.0 },
};
 
export function costOf(model: string, inTok: number, outTok: number): Money {
  const p = PRICE_TABLE[model] ?? PRICE_TABLE["balanced"];
  return (inTok / 1_000_000) * p.input + (outTok / 1_000_000) * p.output;
}

USD で内部を統一しているのにも理由があります。私はサイトによって日本円で考えがちなのですが、モデルの単価はドル建てで提示されることが多く、為替で換算式が散らばると、どこかで桁を間違えます。実際、最初の実装では一部を円、一部をドルで持ってしまい、上限の比較がまるで意味をなさない状態になっていました。比較する値の単位は、一箇所に固定するのが安全です。

単価テーブルは必ず外出しにしておきます。モデルの価格は改定されますし、サイトごと・用途ごとに使うモデルも違うからです。私の場合、記事生成は balanced、リンク監査のような単純作業は fast、設計レビューだけ deep というふうに、タスクの性質で割り当てを変えています。

実消費をリアルタイムに積算する

次が計測です。ここが今回の肝でした。事故の本質は「消費を後からしか知れなかった」ことなので、走行中に累計を持つ台帳（ledger）を用意します。

// ledger.ts — 走行中のトークン消費をリアルタイムに積算する台帳
import { costOf, Money } from "./budget";
 
interface Entry {
  taskId: string;
  model: string;
  inTok: number;
  outTok: number;
  cost: Money;
  at: number;
}
 
export class TokenLedger {
  private entries: Entry[] = [];
  private byTask = new Map<string, Money>();
  private runTotal: Money = 0;
 
  record(taskId: string, model: string, inTok: number, outTok: number): Money {
    const cost = costOf(model, inTok, outTok);
    this.entries.push({ taskId, model, inTok, outTok, cost, at: Date.now() });
    this.byTask.set(taskId, (this.byTask.get(taskId) ?? 0) + cost);
    this.runTotal += cost;
    return cost;
  }
 
  taskSpend(taskId: string): Money {
    return this.byTask.get(taskId) ?? 0;
  }
 
  total(): Money {
    return this.runTotal;
  }
 
  // あとで突き合わせ（reconciliation）するための明細を吐く
  dump(): Entry[] {
    return [...this.entries];
  }
}

ここで大事なのは、record をLLM 呼び出しの直後に必ず通すことです。並列で走っていても、台帳のインスタンスを一つ共有していれば、runTotal には全エージェントの消費が合算されます。私は最初、エージェントごとに台帳を分けてしまい、実行全体の上限を見られないという間抜けな実装をしていました。合算したい値は一箇所に集める、という当たり前のことが、並行になると意外と崩れます。

リアルタイムである必要性は、最初は過剰に思えるかもしれません。けれど、並行で10本走っているとき、合計がいつ上限に届くかは誰にも予測できません。あるタスクが急に重くなれば、ほかが軽くても全体は跳ねます。事後の集計では、跳ねたあとの数字しか手に入りません。走りながら積算しているからこそ、「いま全体で上限の8割まで来た」という判断が成り立ち、まだ止められる余地のあるうちに手を打てます。私はこの「走行中に累計が見える」という一点が、ガバナンス層のいちばんの価値だと感じています。

そして dump() の明細は、走行後に必ず保存します。冒頭の事故で一番つらかったのは「どのタスクが犯人か分からない」ことでした。明細さえ残っていれば、翌朝5分で原因が特定できます。これは保険として効きます。

ハードキャップと段階的に縮退する遮断層

三層目の遮断です。配分（budget）と計測（ledger）がそろったので、両者を突き合わせて判断を下す BudgetGuard を実装します。判断は三段階にしました。

第一段階は通常。ソフト閾値（例: 上限の80%）に達するまでは何もしません。第二段階は降格。ソフト閾値を超えたら、以降の呼び出しを安いモデルに自動で切り替えます。仕上げの品質は少し落ちますが、止めるよりはマシな状況が多いからです。第三段階は停止。ハードキャップに達したら、そのタスク（あるいは実行全体）に対してこれ以上の呼び出しを許可しません。

この段階分けは、一見すると過剰に思えるかもしれません。けれど「即停止」だけの設計を一度試して、痛い目を見ました。記事生成のように、序盤で大量に下調べをして終盤で仕上げるタスクは、消費の8割が前半に寄ります。前半で閾値に触れて即停止すると、仕上げ前の中途半端な状態で打ち切られ、その晩のトークンがまるごと無駄になります。降格という中間段階を挟むと、「仕上げは安いモデルでもいいから最後まで走らせる」という選択ができます。完璧な成果物は得られませんが、ゼロよりはずっとマシです。コストを守ることと、成果をゼロにしないことは、別々に考える価値がある二つの目的だと感じています。

// guard.ts — 予算と台帳を突き合わせ、縮退判断を下す
import { BudgetPolicy } from "./budget";
import { TokenLedger } from "./ledger";
 
export type Decision =
  | { action: "proceed"; model: string }
  | { action: "downgrade"; model: string }
  | { action: "halt"; reason: string };
 
export class BudgetGuard {
  constructor(
    private policy: BudgetPolicy,
    private ledger: TokenLedger,
  ) {}
 
  // 呼び出し前に必ず通す。返ってきた action に従う
  check(taskId: string, requestedModel: string): Decision {
    const run = this.ledger.total();
    const task = this.ledger.taskSpend(taskId);
 
    // ハードキャップ: 実行全体 or タスク個別のどちらか超過で停止
    if (run >= this.policy.runCeiling) {
      return { action: "halt", reason: `run ceiling $${this.policy.runCeiling} reached` };
    }
    if (task >= this.policy.taskCeiling) {
      return { action: "halt", reason: `task ${taskId} ceiling reached` };
    }
 
    // ソフト閾値: 実行全体・タスク個別のどちらかが softRatio を超えたら降格
    if (
      run >= this.policy.runCeiling * this.policy.softRatio ||
      task >= this.policy.taskCeiling * this.policy.softRatio
    ) {
      return { action: "downgrade", model: "fast" };
    }
 
    return { action: "proceed", model: requestedModel };
  }
}

ソフト閾値を実行全体だけでなくタスク個別にも当てているのは、あとから直した点です。当初は実行全体の消費でしか降格しない実装でした。すると、全体にはまだ余裕があるのに1本のタスクだけが重い、といういちばんありがちな状況で、そのタスクは通常モデルのまま taskCeiling に突き当たり、いきなり停止します。段階的に縮退させるために作ったはずの降格が、単独の暴走に対してだけ働かないのです。前の節で「即停止だけの設計で痛い目を見た」と書いておきながら、コードは単独タスクに対して実質そうなっていました。

task >= taskCeiling * softRatio を足すと何が変わるのか、上の check をそのまま切り出して手元で回してみました。runCeiling: 4.0 / taskCeiling: 0.8 / softRatio: 0.8、1呼び出しあたり入力 40,000・出力 4,000 トークン（上位モデルで約 $0.18）という重いタスクを1本だけ流した結果です。

払う金額はほぼ同じで、進んだ距離が倍になりました。修正前は上位モデルのまま4回走って5回目の手前で taskCeiling に触れ、降格を一度も経ずに停止しています。修正後は4回目を終えた時点で自分の上限の8割に届き、そこから安いモデルに落ちて残りを稼いでいます。停止そのものは避けられませんが、「同じ予算でどこまで進めるか」が変わるのが要点です。降格は節約の仕組みではなく、打ち切られる前に成果を確定させるための時間稼ぎだと考えると腑に落ちます。

check は呼び出しの前に通します。record は呼び出しの後です。この前後の対称性を守るのがコツで、どちらかを忘れると予算が漏れます。私は「ガードしてから呼び、呼んだら記録する」を一つの関数にまとめて、エージェント側から個別に触れないようにしました。

// guarded-call.ts — check と record を必ずセットで通す唯一の入口
import { BudgetGuard } from "./guard";
import { TokenLedger } from "./ledger";
 
export async function guardedCall(
  guard: BudgetGuard,
  ledger: TokenLedger,
  taskId: string,
  model: string,
  invoke: (model: string) => Promise<{ inTok: number; outTok: number; text: string }>,
): Promise<{ text: string; halted: boolean }> {
  const decision = guard.check(taskId, model);
  if (decision.action === "halt") {
    console.warn(`[budget] halt ${taskId}: ${decision.reason}`);
    return { text: "", halted: true };
  }
  const useModel = decision.action === "downgrade" ? decision.model : decision.model ?? model;
  const res = await invoke(useModel);
  ledger.record(taskId, useModel, res.inTok, res.outTok);
  return { text: res.text, halted: false };
}

これで、エージェントがどう実装されていても、LLM を叩く経路がこの guardedCall を通る限り、予算は必ず効きます。

逆に言えば、抜け道を一つでも残すと、そこから予算が漏れます。私はエージェントのコードをレビューするとき、invoke に相当する生の呼び出しが guardedCall の外に書かれていないかだけは必ず確認します。入口を一つに絞るのは地味ですが、ガバナンスを「気をつける運用」から「構造で守られる運用」に変える、いちばん効くルールだと思っています。

Antigravity の並列エージェントに差し込む

ここまでの三層を、Antigravity の並列エージェントに組み込みます。Antigravity では複数のサブエージェントを同時に走らせられますが、それぞれが独立して LLM を叩くため、放っておくと合算消費が見えません。そこで、台帳とガードを実行スコープで一つだけ生成し、全サブエージェントに同じインスタンスを渡します。

// orchestrate.ts — 並列エージェントに共有ガードを配る
import { TokenLedger } from "./ledger";
import { BudgetGuard } from "./guard";
import { guardedCall } from "./guarded-call";
 
async function runDailyJobs(tasks: { id: string; model: string; run: Function }[]) {
  const ledger = new TokenLedger();
  const guard = new BudgetGuard(
    { runCeiling: 4.0, taskCeiling: 0.8, softRatio: 0.8 },
    ledger,
  );
 
  // 全タスクが同じ ledger / guard を共有するのが要点
  const results = await Promise.allSettled(
    tasks.map((t) =>
      t.run((model: string, invoke: any) =>
        guardedCall(guard, ledger, t.id, model, invoke),
      ),
    ),
  );
 
  // 走行後に明細を保存しておく（事故時の原因特定が5分で済む）
  await persistLedger(ledger.dump(), new Date());
  console.log(`[budget] run total: $${ledger.total().toFixed(3)}`);
  return results;
}

Antigravity の並列エージェントは、サブエージェントごとに作業ログとアーティファクトを残してくれます。私はそこに、台帳の run total と、降格や停止が発動したかどうかを書き出すようにしました。こうしておくと、翌朝アーティファクトを開いた時点で、その晩のコストと、ガードが何回働いたかが一目で分かります。エージェントの成果物とコストの記録が同じ場所に並ぶので、品質とコストを切り離さずに振り返れるのが気に入っています。

ここで Promise.allSettled を使っているのは意図的です。ただし理由は正確に書いておきます。guardedCall は halt のとき例外を投げず halted: true を返すので、予算による停止それ自体は reject になりません。allSettled が効くのは、停止を受け取ったタスク側が「この途中結果では続けられない」と判断して自前で throw する場合や、ネットワーク・パース由来の例外が混ざる場合です。そこで Promise.all を使っていると、1本の失敗が他の完走結果まで巻き込んで捨ててしまいます。

停止を明示的に失敗として扱いたいなら、guardedCall から専用のエラー型を投げる設計に寄せる手もあります。私は返り値で受け取る側を選びました。停止したタスクの部分成果も翌朝の判断材料になるからです。

実行スコープの runCeiling を $4.0、タスク個別を $0.8 に置いているのは、私の手元の1晩分のジョブ規模に合わせた値です。最初に事故ったときの請求差分から逆算して決めました。みなさんの規模に合わせて調整してください。

runCeiling は、並行数のぶんだけ踏み越えられます

orchestrate.ts を数晩まわしたあと、明細の合計が $4.0 の上限をはっきり超えている晩があるのに気づきました。ログを見ると、ガードは正しく halt を返しています。それでも超えるのです。

原因は check と record のあいだにありました。check が読んでいるのは ledger.total() で、そこにはまだ返ってきていない呼び出しの消費が入っていません。並行10本が同じ瞬間に check を通れば、10本とも同じ「まだ余裕のある合計」を見て proceed を受け取ります。天井は、飛び立ったあとの呼び出しの数だけ、後から踏み越えられます。

これは後述する「共有台帳への並行書き込み」とは別の問題です。競合しているのは Map の更新ではなく、await をまたいだ判断のほうなので、Node の単一スレッドでも起こります。

check と record の順序だけを取り出した小さなスクリプトを手元で回し、1呼び出しの重さを変えて比べました。runCeiling: 4.0 / softRatio: 0.8 は本文と同じ値です。

軽い呼び出しのうちは、数パーセントの誤差にしか見えません。重くなるほど、超過はそのまま並行数と単価の掛け算になります。いちばん下の行では、どの1本も halt を受け取らないまま6本が同時に飛び、天井の2.4倍を使い切っています。冒頭の事故と同じかたちが、ガードを入れたあとの実装にも残っていたわけです。

上限は、確定した消費ではなく、飛び立った呼び出しに対して引きます。 直し方は素朴で、check を通ったところで見積り額を「予約」として台帳に積み、record のときに予約を外して実額に置き換えます。

// ledger.ts に追記 — 飛行中の呼び出しを予約として保持する
export class TokenLedger {
  // ...既存のフィールドはそのまま
  private reserved: Money = 0;
  private holds = new Map<string, Money>();
 
  // check を通ったあとに呼ぶ。見積り額を予約し、控えの ID を返す
  reserve(model: string, estIn: number, estOut: number): string {
    const est = costOf(model, estIn, estOut);
    const holdId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
    this.holds.set(holdId, est);
    this.reserved += est;
    return holdId;
  }
 
  // record と対で呼ぶ。予約を外し、実額だけを残す
  release(holdId: string): void {
    const est = this.holds.get(holdId);
    if (est === undefined) return;
    this.holds.delete(holdId);
    this.reserved -= est;
  }
 
  // ガードが見るべきはこちら。確定分 + 飛行中の見積り
  committed(): Money {
    return this.runTotal + this.reserved;
  }
}

BudgetGuard.check で this.ledger.total() を読んでいた箇所を this.ledger.committed() に替え、guardedCall を予約つきの形に直します。

// guarded-call.ts — 予約してから呼び、返ってきたら予約を外して実額を記録する
const decision = guard.check(taskId, model);
if (decision.action === "halt") {
  console.warn(`[budget] halt ${taskId}: ${decision.reason}`);
  return { text: "", halted: true };
}
const useModel = decision.action === "downgrade" ? decision.model : model;
const holdId = ledger.reserve(useModel, ESTIMATED_IN, ESTIMATED_OUT);
try {
  const res = await invoke(useModel);
  ledger.record(taskId, useModel, res.inTok, res.outTok);
  return { text: res.text, halted: false };
} finally {
  ledger.release(holdId);   // 例外で抜けても予約を残さない
}

release を finally に置いているのには理由があります。呼び出しがネットワーク例外で落ちたときに予約が台帳へ残り続けると、committed() が下がらないまま高止まりし、以降のタスクが理由もなく halt を受け取ります。予算で止めたつもりが、例外の後始末の漏れでサービスを止めていた——という筋書きは、避けたいところです。

同じスクリプトを予約つきに直して回すと、上の3条件はいずれも最終合計 $4.01〜$4.04（超過 1% 以内）に収まりました。超過が完全にゼロにならないのは、予約が積まれる直前の1本だけは通るからです。超過の上限が「並行数 × 1呼び出し」から「1呼び出しぶん」に縮む、と考えていただくのがいちばん近いと思います。

見積りに使う ESTIMATED_IN / ESTIMATED_OUT は、私は直近20回の最大値を採っています。中央値を使うと予約が実際より薄くなり、元の踏み越えが小さな規模で戻ってきます。見積りを多めに置いたぶんは record のときに実額へ置き換わるので、払いすぎにはなりません。多めに見積もって早めに降格し、あとから実額で辻褄を合わせる——この順番のほうが、私の運用では安心できました。

本番で踏んだ落とし穴

設計どおりに動かすまでに、いくつか痛い目を見ました。記録しておきます。

第一に、ストリーミング応答の計測漏れです。トークンの確定値は応答完了後にしか出ないので、ストリーミング中に巨大な出力が走っていても、record が呼ばれるのは最後です。つまりガードが効くのは「次の呼び出しから」になります。1回の呼び出しで暴走されると素通りします。対処として、タスク個別の上限を、平均1呼び出しの想定消費よりも十分大きく、しかし事故レベルよりは小さく置く必要があります。私は「想定の3〜5倍」を目安にしています。

第二に、リトライによる二重消費です。ネットワークエラーでリトライすると、失敗した呼び出し分のトークンも実際には課金されることがあります。リトライ前の消費を record し忘れると、台帳が実請求と食い違います。私はリトライのたびに記録するよう直しました。走行後に請求ダッシュボードと dump() の合計を突き合わせて、誤差が5%以内に収まっているかを毎週確認しています。最初は20%以上ずれていて、その差のほとんどがリトライの記録漏れでした。

第三に、降格の品質劣化を見逃す問題です。fast モデルへ降格したタスクの成果物は、当然ながら品質が落ちます。記事生成で降格が発動すると、薄い記事が出てきます。なので私は、降格が一度でも発動した実行については、成果物に「降格フラグ」を立てて、人間のレビュー対象に回すようにしました。コストを守った代わりに品質を黙って落とすのは、別の事故の入口になります。

第四に、共有台帳への並行書き込みです。同じ TokenLedger インスタンスを全サブエージェントが触るので、record が同時に呼ばれます。Node の単一スレッドなら同期的な Map 更新は競合しませんが、ワーカーを分けたり別プロセスにすると話が変わります。私は当面シングルプロセスで運用すると決めて、その前提を台帳のコメントに明記しました。前提を破る変更を入れるなら、原子的な加算に置き換える必要があります。前提を言葉で残しておくと、半年後の自分が事故を起こしにくくなります。

これらはどれも、設計図だけ見ていると気づけない類の問題でした。実際に本番で1晩回してみて初めて表に出てきます。だからこそ、最初は上限をかなり低めに設定して、わざと halt を踏ませながら挙動を確かめるのをお勧めします。

素朴な並列実装と、ガードを通した実装の違い

導入前後の差を、コードで並べてみます。事故を起こしていた頃の素朴な実装は、おおよそこうでした。

// Before — ガードなし。消費は走行後の請求でしか分からない
async function runDailyJobs(tasks: { id: string; run: Function }[]) {
  // 各タスクが好き勝手に LLM を叩く。合算も上限もない
  return Promise.all(tasks.map((t) => t.run()));
}

一見すると何の問題もなく、実際ふだんは何事もなく動きます。けれど、上限がどこにもないので、1本でも暴走すると誰も止められません。請求が確定して初めて異常に気づく構造です。

これを、これまでに作った三層に通すとこうなります。

// After — 共有台帳とガードを全タスクに配り、走行後に明細を残す
async function runDailyJobs(tasks: { id: string; model: string; run: Function }[]) {
  const ledger = new TokenLedger();
  const guard = new BudgetGuard(
    { runCeiling: 4.0, taskCeiling: 0.8, softRatio: 0.8 },
    ledger,
  );
  const results = await Promise.allSettled(
    tasks.map((t) =>
      t.run((model: string, invoke: any) =>
        guardedCall(guard, ledger, t.id, model, invoke),
      ),
    ),
  );
  await persistLedger(ledger.dump(), new Date());   // ← 明細を残すのが効く
  return results;
}

差分は行数にすれば数行です。けれど、この数行が「請求書を見て青ざめる」運用から「毎朝ログで把握できる」運用への分かれ目になりました。大掛かりな監視基盤を組む必要はなく、既存の並列実行をこの薄いラッパーで包むだけで足ります。

予算の数字を実績から逆算する

runCeiling や taskCeiling に入れる金額は、勘で決めるとだいたい外します。高すぎればガードが効かず、低すぎれば正常なタスクまで止まります。私は、台帳の明細を1〜2週間ためてから、実績の分布を見て決めました。

具体的には、こういう順序で詰めていきました。

1. まず遮断を一切かけず、TokenLedger の dump() だけを2週間ぶん集めます。
2. タスクごとに1回の実行コストを並べ、中央値と最大値を見ます。私のリンク監査タスクは中央値 $0.12、たまに $0.30 まで伸びる程度でした。
3. タスク個別の上限は、その最大値の3〜5倍に置きます。私は $0.8 にしました。正常範囲には十分余裕があり、事故レベル（過去に $6 超え）はしっかり止まる値です。
4. 実行全体の上限は、1晩に走る全タスクの合計の中央値に、安全率1.5倍ほどを掛けます。私の1晩は合計 $2.5 前後だったので、$4.0 に置きました。

この決め方の良いところは、根拠が自分の実績データにあることです。一般論の数字ではなく、自分のエージェントが現に消費している分布から逆算するので、止めるべきものは止まり、通すべきものは通る確率が高くなります。3ヶ月運用した範囲では、正常タスクを誤って止めてしまった例はゼロでした。

数字は一度決めて終わりにせず、月に一度は明細を見直して調整するのが良いと感じています。扱う記事の本数やモデルの単価は変わっていくので、上限もそれに合わせて動かし続ける必要があります。

導入して変わったこと

このガバナンス層を入れてから、月のトークン費は事故前の水準に戻り、何より「いくらかかるか読めない」という不安が消えました。毎晩の実行ログに run total: $X が必ず残るので、異常があればその日のうちに気づけます。冒頭のような「翌月の請求書で初めて知る」事故は、それ以来一度も起きていません。

数字をひとつ挙げると、事故月に約3.2倍まで膨らんだトークン費は、ガード導入後の3ヶ月はいずれも基準値の±10%以内に収まっています。最適化で単価を下げたこと以上に、天井を持ったことの安心感が大きいと感じています。

次の一歩としておすすめしたいのは、まず TokenLedger だけを既存のエージェントに差し込んで、1週間ぶんの明細を取ってみることです。遮断はその次で構いません。自分のエージェントが実際に何にいくら使っているかを数字で見るだけで、どこに上限を置くべきかが自然と見えてきます。私自身、台帳を取り始めて初めて、犯人だと思っていたタスクが実は無実で、地味な定型作業のほうが累計で効いていたと気づきました。

同じようにコストの不透明さと向き合っている方の、設計の足がかりになれば嬉しいです。