ある朝、Antigravity の Background Agent が前日の AdMob レビュー結果を完全に忘れていて、同じ警告を3回続けて私のメールボックスに投げてきました。Agent run のログを追いかけると、メモリは持っているはずなのに、復元先のキーが微妙にずれて読み出せていなかった、というのが原因でした。個人でアプリを開発しながら、Antigravity を含むエディタ統合の AI エージェントで日々の運用を回しております。「Agent が情報を覚えていない／逆に覚えすぎている」現象に何度かやられてから、私自身の中で「Agent が抱える情報は、寿命の長さで3階層に分けないと必ず壊れる」という結論にたどり着きました。いま思えば、壊れていたのはメモリではなく、寿命の違う情報を同じ棚に並べていた私の設計だったのかもしれません。
本稿はその3階層 — ephemeral / journal / canonical — の責任分界と、Cloudflare Workers の物理ストア（KV / Durable Objects / R2 / D1）への落とし込み方、write-back 境界に承認ゲートを噛ませる実装をまとめたものです。Background Agent / Sub-agent / Browser Sub-agent を複数本並走させている方にとって、設計判断を1段落ずつ詰める材料になればと思います。
同じ Antigravity Agent でも、覚えていてほしい情報には3つの寿命がある
Antigravity の Agent が触る情報を雑に「メモリ」と呼んでしまうと、必ずどこかで破綻します。私が実運用で痛い目を見てから採用したのは、以下の3階層に責任を分ける考え方です。
ポイントは「失われたときに何が起きるか」で寿命を決めることです。情報量や物理的なサイズではありません。たとえば LLM の長い思考ログは数十万トークンあっても ephemeral で十分ですし、たった 1 件のスラッグ重複検知ログは canonical に置かないと事故ります。
この3階層に分けると、Agent コード側は次の3つだけを意識すればよくなります。
その情報は、次の run で再計算できるか？ → できるなら ephemeral
再計算できないが、最悪「やり直し」が許されるか？ → 許されるなら journal
失えばユーザー体験そのものが壊れるか？ → 壊れるなら canonical
これだけです。後述の通り、3層は別々の物理ストアにマッピングしますが、Agent 側コードからは統一的なインターフェースで扱えるようにアダプタを噛ませます。
ephemeral — 1回の Agent run 内だけで生きる作業メモリ
ephemeral は、Agent run の入口で生まれて出口で捨てられる情報です。中間プロンプト、LLM 応答の生テキスト、ファイル一覧の snapshot、検索結果、再計算の途中値、こういったものが該当します。失われても次の run で再生できるので、Cloudflare KV のような共有ストアに置く価値はほぼゼロです。
Antigravity の Background Agent では、私はこの層を Worker のローカルメモリ（つまり JavaScript の Map / Object）で完結させています。コードはこんな雛形です。
// state/ephemeral.ts export class EphemeralStore { private bucket = new Map < string , unknown >();
get < T = unknown >( key : string ) : T | undefined { return this .bucket. get (key) as T | undefined ; }
put < T = unknown >( key : string , value : T ) : void { this .bucket. set (key, value); }
// run 終了時に必ず呼ぶ。意図的に明示する。 dispose () : void { this .bucket. clear (); } } 意図的に dispose を明示しているのは、ephemeral を「黙って捨ててもいい」ではなく「能動的に捨てる」ものとして扱いたいからです。Sub-agent から戻ってきた中間 LLM 応答をうっかり journal や canonical に書き込んでしまうと、ストレージコストが青天井になります。私の場合、Background Agent 1本あたり ephemeral だけで 200〜800KB / run を扱うので、月単位だと GB スケールになります。これを真面目に KV に書いていたら月の運用予算 ¥800 では絶対に収まりません。
実装上の落とし穴も一つ書き残しておきます。Cloudflare Workers では同じ Isolate が次のリクエストにも再利用されることがあり、ephemeral として作った Map が次の run まで残ってしまう挙動を踏みました。これは Worker のグローバル変数として保持していた私のミスで、対処として EphemeralStore は必ず run のエントリ関数内で new するように変更しました。
この再利用は手元の wrangler dev では起きたり起きなかったりするので、テストで意図的に再現しておくのが確実だと思っております。私が置いているのは、同じ Worker に 2 回リクエストを投げ、モジュールスコープに漏れた Map が持ち越されていないかを見るだけの小さなものです。
// test/ephemeral-leak.test.ts — @cloudflare/vitest-pool-workers import { SELF } from "cloudflare:test" ; import { expect, it } from "vitest" ;
it ( "ephemeral は run をまたいで残らない" , async () => { // Worker 側の /run?probe=1 は、その run で 1 件書いたあとの Map の件数を返す const first = await SELF . fetch ( "https://example.com/run?probe=1" ); const second = await SELF . fetch ( "https://example.com/run?probe=1" ); const a = await first. json <{ size : number }>(); const b = await second. json <{ size : number }>(); // どちらの run も、自分が書いた 1 件しか見えていないはず expect (a.size). toBe ( 1 ); expect (b.size). toBe ( 1 ); }); テスト内の 2 回の呼び出しは同じ実行環境に載るので、Map がグローバルに漏れていれば 2 回目の size が 2 になります。このテストが赤くなった朝に初めて、自分がどこで new していたかを疑えるようになりました——落ちてくれるテストが 1 本あるだけで、Isolate の話は「たまに起きる怪現象」から「再現できる仕様」に変わるのです。
journal — 数日〜数週間の意思決定ログ。再現可能だが必須ではない
journal は、再現はできるけれど再現に時間や費用がかかる情報を置く層です。Agent が下した意思決定の根拠ログ、A/B テストの中間スコア、Browser Sub-agent が観測した AdMob ダッシュボードの差分、過去の自動修復ログ、こういったものが該当します。
journal の判定基準は1つだけで、「失っても完全には困らないが、再現には半日以上かかる」かどうかです。私の場合、journal が無いまま再現すべき失敗が複数回あり、そのたびに半日〜2日溶けました。特に厄介だったのが「Agent はなぜこの分岐を選んだのか」を後から追えないケースで、出力だけ残っていても、判断の根拠が消えていると同じ誤りを再び踏みます。今はこの層を真面目に持つようにしています。
物理マッピングとしては、Cloudflare KV のように「読み取りが安く・書き込みは従量・結果整合」という特性が journal にちょうど噛み合います。書き込み頻度が低く、読み取り頻度はそこそこあり、最新性は緩くてよいからです。
// state/journal.ts export class JournalStore { constructor ( private kv : KVNamespace , private agentId : string ) {}
private k ( scope : string , id : string ) : string { // agent ごとに名前空間を切る。誤読み防止。 return `journal:${ this . agentId }:${ scope }:${ id }` ; }
async append ( scope : string , entry : Record < string , unknown >) : Promise < void > { const id = crypto. randomUUID (); const value = JSON . stringify ({ at: Date. now (), ... entry }); // 30日の TTL を必ずつける。journal は永続ではない。 await this .kv. put ( this . k (scope, id), value, { expirationTtl: 60 * 60 * 24 * 30 }); }
async list ( scope : string , limit = 50 ) : Promise < Array < Record < string , unknown >>> { const { keys } = await this .kv. list ({ prefix: this . k (scope, "" ), limit }); const items = await Promise . all (keys. map (( k ) => this .kv. get (k.name, "json" ))); return items. filter (Boolean) as Array < Record < string , unknown >>; } } ここで2つ実運用の落とし穴を共有します。1つ目、journal のキーに必ず journal: の prefix を入れること。canonical と物理 KV を共有してしまっても、prefix で誤読み・誤上書きを防げます。2つ目、TTL を必ずつけること。journal は性質的に再現可能なので、30 日経って捨てても困りません。逆に TTL なしで運用すると、半年経った頃に Agent が「過去の意思決定が膨大すぎて文脈が壊れる」状態になります。私はこれを 2 度やっています。
journal の月額コストは、書き込み十万件・読み取り百万件程度の小規模な Agent 運用なら、Workers の有料プランに含まれる KV の枠でほぼ吸収できます。私の環境では 1 サイトあたり ¥800 という運用予算の中で、journal が目立った項目になったことはありません。
canonical — 削れば致命傷になる、サービス本体のソース・オブ・トゥルース
canonical は失えば終わる情報です。記事のスラッグ、Stripe の購入レコード、premium 会員のメール、AdMob の収益サマリーの月次集計（再取得可能だが API 制限で時間がかかる）、こういったものが該当します。
私の運用ルールはシンプルで、canonical はAgent 自身ではなく、必ず外側のシステム側にソース・オブ・トゥルースを置くというものです。Agent はあくまでも canonical を「読む」か「書き戻す」かのどちらかしかしません。Agent 内部で canonical を「持っている」つもりになると、Agent 側のバグでサービス本体がぶっ壊れます。
物理マッピングは、データの構造によって2つを使い分けています。
具体例で言うと、Antigravity Lab の記事公開済みスラッグ一覧は GitHub repo（つまり Git そのもの）が canonical で、Agent はそれを clone して読むだけ。書き込みは GitHub API 経由でしか発生させません。Agent 側の KV や DO は journal 扱いで、Git 側に書き戻したらすぐ捨てる、という分離を徹底しています。
Durable Object を使った canonical アダプタの最小例も載せておきます。premium 購入記録のような並行更新が起きうるものに向いています。
// state/canonical-do.ts export class PurchaseRegistry { state : DurableObjectState ; constructor ( state : DurableObjectState ) { this .state = state; }
async fetch ( req : Request ) : Promise < Response > { const url = new URL (req.url); if (req.method === "POST" && url.pathname === "/grant" ) { const { email , slug } = await req. json <{ email : string ; slug : string }>(); // 同時に同じユーザーが2回叩いても安全（DO の単一インスタンス性）。 const key = `grant:${ email }:${ slug }` ; const existing = await this .state.storage. get (key); if (existing) return new Response ( JSON . stringify ({ already: true })); await this .state.storage. put (key, { grantedAt: Date. now () }); return new Response ( JSON . stringify ({ granted: true })); } return new Response ( "not found" , { status: 404 }); } } 長時間タスクの途中再開そのものは Antigravity × Durable Execution: 障害に強い長時間AIタスクの設計パターン に譲り、ここでは「何を Agent の外に置くか」だけに絞ります。
canonical を Agent 内に「持たせない」ことのご利益は、Agent をいつでも捨てて作り直せるという気軽さです。Agent 側のバグで journal が壊れても、最悪 30 日の TTL で勝手に消えてくれます。一方で canonical を Agent 内に持たせていると、Agent を作り直すたびにユーザー体験が壊れる恐怖と戦うことになります。個人開発では Agent の作り直しが日常茶飯事ですので、この気軽さは設計上の資産です。
3階層を物理ストアにマッピングする — KV / Durable Object / R2 / D1 の判断軸
マッピング判断は、私の場合は次の3軸で機械的に決めるようにしています。
寿命：1 run / 数十日 / 永続 のどれか
並行更新：同じキーに複数 Agent が同時に書く可能性があるか
クエリ性：1キー読み出しで十分か、範囲スキャンや JOIN が要るか
これに当てはめると、Cloudflare のストア選択はかなりすっきり決まります。
寿命1run・並行更新なし・キー読み → ephemeral（in-memory Map）
寿命数十日・並行更新ほぼなし・prefix scan で足りる → journal（KV）
永続・並行更新あり・キー読み中心 → canonical（Durable Object）
永続・並行更新なし・SQL を回したい → canonical（D1）
永続・大容量・読み取り中心 → canonical（R2 にスナップショット）
私自身、最初の頃は journal も canonical も全部 KV に入れていて、prefix の付け忘れで Agent 同士が意図せず読み合うバグを 5 回くらい踏みました。原因が設計の側にあると気づいたのは、同じ修正を 3 度目に書いているときでした。3軸で機械的に判断するルールにしてからは、設計時点でほぼ事故が消えました。お勧めの判断則です。
引き継ぎ境界の設計 — どこで write back し、どこで snapshot するか
3階層を分けるだけでは不十分で、層と層の間でどう情報を渡すかも設計対象です。Antigravity の Background Agent では、私は次の3つの「境界」を意識しています。
ステップ 1. ephemeral → journal の境界（write-down）
ephemeral から「再現に時間がかかる中間決定」だけを journal に書き残します。run の終わり、あるいは Sub-agent が完了したタイミングが書き込みポイントです。すべてを書くと journal が肥大化するので、私の場合は「Agent が分岐判断を下した瞬間」だけに絞っています。
ステップ 2. journal → canonical の境界（write-back）
これが最も慎重に設計すべきポイントです。journal はあくまで Agent 内の運用ログですが、ここから canonical に書き戻すときに人間（私）の承認を挟むことを強く推奨します。Antigravity の HITL（Human-in-the-Loop）パイプラインを使うか、最低でもメールか Slack の通知を1段挟みます。実際、私は過去に承認なしで journal → canonical を直結させてしまい、Agent が誤判断で premium 記事を 12 本一斉に free に降格させたことがあります。リカバリに半日かかりました。
ステップ 3. canonical → journal への snapshot（read-back）
逆方向の引き継ぎも忘れがちですが重要です。canonical の最新状態を journal に snapshot しておくと、Agent が「今の状態」を毎回 canonical に問い合わせなくて済みます。読み取りコストが減るだけでなく、canonical 側の API 制限（GitHub API の 5,000 req/h 等）にも引っかかりにくくなります。snapshot は1時間に1回程度の粒度で十分です。
なお、境界を越えたはずの書き込みが実は一件も起きていなかった、という取りこぼしは別の観測系で拾っています。そちらは Antigravity サブエージェントの「動いているのに何もしていない」を捕まえる Observability 3層設計 に書き分けました。
この3つの境界を明示的にコードに書き分けると、Agent コード全体が驚くほど読みやすくなります。逆に境界が暗黙になっていると、コードを読んでも「今これは ephemeral なのか canonical なのか」がわからなくなり、変更時に必ず事故ります。
承認ゲートを実装する — write-back を止める最小コード
「人間の承認を挟む」と口で言うのは簡単ですが、実装で曖昧にすると必ず素通りします。私が使っている最小の形は、書き込み先の層を型で持ち、canonical だけ承認待ちキューに落とす、というものです。
// state-gate.ts — 層ごとに write の扱いを変える最小ゲート type Tier = "ephemeral" | "journal" | "canonical" ;
interface PendingWrite { id : string ; key : string ; value : unknown ; reason : string ; // Agent がなぜ書こうとしたか createdAt : number ; }
interface GateDeps { journal : KVNamespace ; // journal 層 canonical : DurableObjectStub ; // canonical 層 notify : ( w : PendingWrite ) => Promise < void >; }
const JOURNAL_TTL = 60 * 60 * 24 * 30 ; // 30日
export async function write ( tier : Tier , key : string , value : unknown , reason : string , deps : GateDeps , ) : Promise <{ applied : boolean ; pendingId ?: string }> { if (tier === "ephemeral" ) { // 呼び出し側の Map に置くだけ。永続化しない return { applied: true }; }
if (tier === "journal" ) { await deps.journal. put (key, JSON . stringify ({ value, reason }), { expirationTtl: JOURNAL_TTL , }); return { applied: true }; }
// canonical は即時反映しない。必ず承認待ちに落とす const pending : PendingWrite = { id: crypto. randomUUID (), key, value, reason, createdAt: Date. now (), }; await deps.journal. put ( `pending:${ pending . id }` , JSON . stringify (pending), { expirationTtl: 60 * 60 * 24 * 3 , // 承認されなければ3日で失効 }); await deps. notify (pending); return { applied: false , pendingId: pending.id }; }
export async function approve ( id : string , deps : GateDeps ) : Promise < boolean > { const raw = await deps.journal. get ( `pending:${ id }` ); if ( ! raw) return false ; // 失効済み。取りこぼしではなく設計どおりの拒否 const p = JSON . parse (raw) as PendingWrite ; await deps.canonical. fetch ( "https://do/put" , { method: "POST" , body: JSON . stringify ({ key: p.key, value: p.value }), }); await deps.journal. delete ( `pending:${ id }` ); return true ; } このコードで肝心なのは write() の戻り値です。applied: false を返す経路を必ず作っておくと、呼び出し側の Agent は「書けたつもり」で先に進めません。逆に戻り値を void にしてしまうと、承認待ちなのか反映済みなのかが Agent 側から区別できず、後続処理が壊れた状態を canonical だと信じ込みます。
pending: に 3 日の失効を付けているのも意図があります。承認待ちが無期限に溜まると、1ヶ月後に「これは何の変更だったか」がわからないまま承認ボタンを押す羽目になるためです。忘れられた変更は、承認されないほうが安全と考えております。
ヘッドレス実行では承認が素通りしていた — 前提が変わった修正
承認ゲートを設計しても、実行系の側で自動承認されてしまえば意味がありません。ここは実際に前提が変わった箇所ですので、記録として残しておきます。
Antigravity CLI 1.1.3（2026-07-16）で、ヘッドレス実行（-p）に関する2つの修正が入りました。ひとつは、確認の必要なツールでプロセスが固まる、あるいは黙って自動承認してしまう問題です。修正後はソフト拒否となり、許可に必要な allow ルール名が stderr に出るようになりました。もうひとつは、always-proceed モードでワークスペース外へのファイル書き込みが誤って自動承認されていた問題です。
夜間に自動でタスクを回している場合、この2件は前提そのものが変わる修正です。つまり 1.1.3 より前の環境では、承認を挟んでいるつもりのフローが、実際には通過していた可能性があります。
確認の手順は次のとおりです。
antigravity --version で CLI が 1.1.3 以降かを確認します1.1.3 未満なら更新します。更新できない事情があるなら、ヘッドレスでの canonical 書き込みを一旦止めます
更新後、承認が必要なはずの処理を -p で1本流し、stderr に allow ルール名が出ることを目視します
出ない場合、そのツールは allow ルールで既に許可されています。ルール一覧を洗い直します
3 番目が要点です。ソフト拒否されること自体を確認しないと、「修正が入ったから大丈夫だろう」という思い込みで運用を続けることになります。私はここで、自分の allow ルールが想定より広く書かれていたことに気づきました。
もうひとつ、あわせて確認しておきたいのがトークン計上の挙動です。2026-07-21 のアップデートで、会話が想定より早く上限に達するトークン計上のバグが修正されました。長時間のエージェント実行を組んでいる場合、消費の実測を取り直しておくと、承認ゲートで止まった処理が「上限で落ちた」のか「設計どおり保留された」のかを取り違えずに済みます。
その後の CLI で、この取り違えはさらに起きにくくなりました。CLI 1.2.6 でヘッドレス -p の既定タイムアウトが 5 分から無制限になり、失敗時には stderr に AGY_ERROR: {...} という構造化された 1 行と終了コード 3 が出るようになりました。1.2.9 では -p の終了後に残っていたデーモンが止まり、バックグラウンド作業は --print-timeout（上限 30 分）まで待つようになっています。
私はこれを受けて、夜間ジョブの合否を「終了コード 0、かつ stderr に AGY_ERROR が無い」に組み替えました。承認ゲートが applied: false を返した run は、Agent から見れば正常終了で、pending の通知だけが残ります。ここを「失敗」と混ぜないことが、朝の確認を 5 分で済ませるための線引きなのだと思います。
承認は run の外で待たせ、run の中には待ち時間を残しません。 ゲートが保留を返したら run はそのまま終わり、承認は翌朝の私が別のプロセスで行います。--print-timeout の上限が 30 分に伸びても、承認待ちをその中に押し込まないのは、タイムアウトと保留を同じログに混ぜたくないからです。入口側で壊れた入力を弾く話は 非対話実行でターン境界を守る — コマンド分類テーブルと fail-closed ゲートの実装メモ に分けて書いています。
実運用で固まった、私自身の3つの判断則
ここまで設計則を整理してきましたが、最後に、Agent を実際に走らせ続ける中で固まった判断則を3つだけ共有させてください。
canonical に書く前に、必ず 1 秒以上のディレイか承認を挟みます。Agent の暴走で canonical を一気に書き換えられると、戻すコストは平均で半日、最悪で 2 日です。一方ディレイ 1 秒のコストは無視できます。私の場合、AdMob の eCPM サマリーを書き換える Agent では 5 秒の確認バッファを入れています。
journal は迷ったら 30 日 TTL をつけておきます。後から TTL を伸ばすのは簡単ですが、TTL なしで運用したものを後から有限化するのは記憶喪失級の事故になります。Antigravity の Background Agent では journal はすべて 30 日固定で運用しています。
ephemeral を黙って捨てません。dispose() のような明示的な破棄メソッドを必ず持たせます。これだけで Cloudflare Workers の Isolate 再利用バグ・メモリリーク系トラブルが事実上ゼロになります。私自身、Browser Sub-agent で 3 日間メモリが膨らみ続けて 1 度クラッシュさせた経験があり、それ以来このルールを守っています。
3つとも、Antigravity の Agent が「将来やらかすかもしれない誤動作」を、設計段階で前もって防ぐためのものです。Agent は失敗するものとして扱ったうえで、被害範囲を 3 階層のうち最小の層に閉じ込める、というのが本稿全体の主張でもあります。
次に Background Agent を 1 本作るときは、まず「これは ephemeral / journal / canonical のどれを触る Agent か」を 1 行コメントで書いてみていただければと思います。それだけで設計レビューの半分は終わります。被害を最小の層に閉じ込めるという原則だけは、急いでいる夜でも崩さないようにしています。