AIエージェントのリプレイ設計 — 過去のセッションを再現する時間旅行デバッグの作法

設計パターン1: 決定論的リプレイ（Deterministic Replay）

最も基本的なパターンは、イベント層をそのまま再生する決定論的リプレイです。ツール呼び出しの実行を「録画」しておき、再生時はモデル呼び出し以外は録画した結果を返すだけ、というやり方になります。

// agent-replay/recorder.ts
import { writeFileSync, readFileSync } from "node:fs";
 
export type ReplayEvent =
  | { kind: "user_message"; ts: number; content: string }
  | { kind: "model_call"; ts: number; prompt: string; response: string; seed?: number }
  | { kind: "tool_call"; ts: number; name: string; args: unknown; result: unknown }
  | { kind: "agent_state"; ts: number; snapshot: Record<string, unknown> };
 
export class SessionRecorder {
  private events: ReplayEvent[] = [];
 
  constructor(private sessionId: string) {}
 
  record(event: Omit<ReplayEvent, "ts">) {
    this.events.push({ ...event, ts: Date.now() } as ReplayEvent);
  }
 
  flush(path: string) {
    writeFileSync(path, JSON.stringify({ sessionId: this.sessionId, events: this.events }, null, 2));
  }
}
 
export class ReplayPlayer {
  private events: ReplayEvent[];
  private cursor = 0;
 
  constructor(path: string) {
    const data = JSON.parse(readFileSync(path, "utf8"));
    this.events = data.events;
  }
 
  // 録画されたツール結果を順に返す。本物のツールは呼ばない
  async replayTool(name: string, args: unknown): Promise<unknown> {
    while (this.cursor < this.events.length) {
      const ev = this.events[this.cursor++];
      if (ev.kind === "tool_call" && ev.name === name) {
        // 引数が一致しない場合は警告だけ出して結果を返す（モデルの揺らぎを許容）
        if (JSON.stringify(ev.args) !== JSON.stringify(args)) {
          console.warn(`[replay] tool args drift on ${name}`);
        }
        return ev.result;
      }
    }
    throw new Error(`Replay exhausted for tool ${name}`);
  }
}

このコードのポイントは、ツール呼び出しの引数が完全一致しなくても警告だけで通過させているところです。最初は厳密に一致を求めていたのですが、実際に運用してみると、モデルの応答に微妙な揺らぎがあって毎回ストップしてしまい、肝心の不具合を再現する前に止まることが多発しました。「同じツールを同じ順序で呼ぶ」までは厳密に、「引数の細部」は緩く — この緩急の付け方が、現場で動くリプレイ基盤になるかどうかを分けます。

設計パターン2: 因果リプレイ（Causal Replay）

決定論的リプレイは確かな再現性を持ちますが、「なぜその順序になったのか」を説明できません。マルチエージェントや並列ツール呼び出しのある構成では、イベントの順序自体が問題になります。そこで、イベント間の因果関係を明示的に記録するのが因果リプレイです。

Lamportタイムスタンプの考え方を借りて、各イベントに「直前に依存しているイベントID」を付け、グラフ構造で保存します。再生時はそのグラフをトポロジカルソートで再構築するため、実時刻の前後関係に縛られず、依存関係さえ揃えば同じ結末に辿り着けます。

// agent-replay/causal.ts
type CausalEvent = {
  id: string;
  causes: string[];           // 因果上の親イベントID
  agentId: string;
  payload: unknown;
};
 
export class CausalLog {
  private events: Map<string, CausalEvent> = new Map();
 
  append(ev: Omit<CausalEvent, "id">): string {
    const id = crypto.randomUUID();
    this.events.set(id, { ...ev, id });
    return id;
  }
 
  // 因果順にイベントを返す（並列で観測順序がぶれてもグラフ上は一意に再構築できる）
  *replayCausal(): Generator<CausalEvent> {
    const visited = new Set<string>();
    const order: CausalEvent[] = [];
    const visit = (id: string) => {
      if (visited.has(id)) return;
      visited.add(id);
      const ev = this.events.get(id);
      if (!ev) return;
      ev.causes.forEach(visit);
      order.push(ev);
    };
    [...this.events.keys()].forEach(visit);
    yield* order;
  }
}

私が因果リプレイを最初に必要だと感じたのは、Antigravity の Manager Surface でサブエージェントを並列起動したときでした。3つのエージェントが同時にツールを呼ぶ構成で、ある日「結果が毎回ちょっと違う」という、誰もが頭を抱える種類の症状が出たのです。ログを見ても、3エージェントのイベントが時刻順にインターリーブされているだけで、どのイベントがどのエージェントの判断に依存しているのか追えませんでした。

因果グラフを導入してからは、同じ症状を見たときに「エージェントAのこの応答が、エージェントBの次の決定に影響している」という連鎖が、図のように見えるようになりました。一見すると過剰な設計に見えるかもしれませんが、マルチエージェント運用に進んだ瞬間に必要になります。

エージェント間の協調パターンの基礎はマルチエージェント・オーケストレーション実践ガイドで扱っているので、因果リプレイを導入する前にこちらの設計判断を整理しておくと、グラフの設計がスムーズに進みます。

設計パターン3: 監査リプレイ（Audit Replay）

3つ目は、コンプライアンスや事後説明を目的とした監査リプレイです。これは「なぜその判断をしたか」を後から第三者に説明できる粒度で、決定層を保存します。具体的には、モデル呼び出しのプロンプト全文・ツールスキーマ・温度・最終的に選ばれたレスポンス・必要に応じてlogprobsまでを、改ざん不能な形で書き出します。

// agent-replay/audit.ts
import { createHash } from "node:crypto";
 
export type AuditRecord = {
  sessionId: string;
  step: number;
  prompt: string;
  toolSchemas: unknown[];
  modelParams: { temperature: number; seed?: number; topP?: number };
  response: { text: string; toolCalls: unknown[] };
  prevHash: string;
  hash: string;
};
 
export class AuditChain {
  private records: AuditRecord[] = [];
  private prevHash = "GENESIS";
 
  append(record: Omit<AuditRecord, "prevHash" | "hash">) {
    const enriched = { ...record, prevHash: this.prevHash };
    const hash = createHash("sha256")
      .update(JSON.stringify(enriched))
      .digest("hex");
    const full: AuditRecord = { ...enriched, hash };
    this.records.push(full);
    this.prevHash = hash;
    return full;
  }
 
  // 改ざん検証: 各レコードのhashを再計算し、prevHashで連鎖を辿る
  verify(): boolean {
    let prev = "GENESIS";
    for (const r of this.records) {
      if (r.prevHash !== prev) return false;
      const expected = createHash("sha256")
        .update(JSON.stringify({ ...r, hash: undefined }))
        .digest("hex");
      if (expected !== r.hash) return false;
      prev = r.hash;
    }
    return true;
  }
}

ハッシュチェーンを使うのは大袈裟に見えるかもしれません。私自身、最初は単純なJSONログで十分だと思っていました。けれど、ある契約案件で「エージェントの判断ログを後から監査できるか」と聞かれたとき、JSONを後から書き換えていないことを技術的に示せない、という事実に静かに気づかされました。

監査リプレイは、必ずしも全エージェントに必要ではありません。けれど、医療・金融・法務に近い領域でエージェントを動かすつもりなら、最初からこの層を入れておく価値はあります。後から差し替えるのは、ほとんど不可能に近いです。

どの層をどこまで実装すべきか

3層全部を最初から実装する必要はありません。私がいまもプロダクトの規模に応じて使い分けているのは、次のような線引きです。

• 個人開発者・MVP段階: イベント層のみ（決定論的リプレイ）。本番でログをJSONに書き出して、開発機でリプレイできれば十分。これでバグの90%は再現できる
• チーム開発・複数エージェント: イベント層 + 因果層。マルチエージェントの並列実行を始めた瞬間に、因果リプレイがないと議論が成立しなくなる
• 本番運用・エンタープライズ: 3層すべて。特に監査リプレイは契約や規制要件が出てから慌てて入れるものではない

実装コストはイベント層が一番軽く、決定層が一番重い、という順です。決定層は容量も食います。プロンプトをそのまま保存すると、半年で数十GBになるのは珍しくありません。S3やR2のような安価なストレージに、暗号化と保存期間ポリシーをセットで設計しておくと、後で困りません。

エージェントの観測性をそもそもどう設計するかについては、AIエージェントのトレース観測設計で別の角度から書いています。リプレイは「観測した過去を再生する」もので、観測そのものとは別のレイヤーなので、両方を組み合わせると本番運用の見通しが一段良くなります。

Before/After: リプレイ層を入れる前と後で何が変わったか

これは私自身のチームで実際に経験したことです。

Before（リプレイなし）: 不具合報告が来ても「再現しない」で終わることが週に2-3件。エンジニアは推測でコードを直し、自信のない修正をデプロイし、再発を待つしかない状態。誰のせいでもないのですが、心理的な疲労が蓄積していきました。

After（決定論的リプレイ導入後）: 同じ報告が来たら、まずセッションIDで録画ログを引き、開発機で再生します。再現できたものは原因が必ず分かる。再現できないものは「録画範囲の外で起きた」とはっきり言える。判断の確度が一気に上がりました。

数字で言えば、不具合の平均解決時間が3日から4時間に短縮しました。けれど私にとってより大きかったのは、「説明できる修正」がチームの会話の標準になったことのほうです。AIエージェントは触れ込みが派手な領域ですが、結局のところ、現場の安心感を作るのは地道な観測と再現性の積み上げなのだと、もう一度思い知らされました。

個人開発者がまず最初に実装する最小構成

ここまでの話を読むと身構えてしまうかもしれません。でも、最小構成は驚くほど小さくて、土曜の午後ひとつで動き始められます。

具体的には、こうしてみてください。

1. SessionRecorder を1ファイルだけ用意して、ユーザー入力・モデル応答・ツール結果の3種類だけ記録する
2. 録画ファイルは replays/{sessionId}.json に書き出すだけ。S3もKVも要らない
3. 不具合報告が来たら、ReplayPlayer で再生してみる。まずは「再現できるかどうか」だけ確認する

これだけでも、運用の手応えがまるで違ってきます。私自身、最初の頃は本格的な分散トレーシングを入れようとして手が止まり、結局この最小構成に戻ってきました。完璧な観測基盤を最初から作るより、まずは『過去を再生できる状態』を確保するほうが、はるかに実用的です。

エージェントの安全な振る舞いを別の角度から扱ったエージェント安全ガードレール設計と組み合わせると、「事前のガードレール」と「事後のリプレイ」の両側から守りを固められます。

記録の差し込み箇所 — エージェントループのどこをフックするか

3層モデルが頭で分かるのと、実際にエージェントのコードに無理なく組み込むのとでは、距離があります。記録呼び出しをどこに置くかが、半年後にもメンテできる設計か、静かに腐っていく設計かを分けます。

私が辿り着いたのは、エージェント内部の関数すべてに計装するのではなく、I/O境界 — つまりモデル呼び出しとツール呼び出しだけ — をラップする、というやり方です。S/N比が明確に高くなります。エージェント内部の制御フローはほとんどバグの原因にならず、外部世界との境界がほぼ常に原因になるからです。

// agent-replay/wrap.ts
import { SessionRecorder } from "./recorder";
 
type ToolFn = (args: unknown) => Promise<unknown>;
 
export function wrapTool(rec: SessionRecorder, name: string, fn: ToolFn): ToolFn {
  return async (args) => {
    const result = await fn(args);
    rec.record({ kind: "tool_call", name, args, result });
    return result;
  };
}
 
export async function wrapModelCall<T extends { text: string }>(
  rec: SessionRecorder,
  prompt: string,
  callModel: (p: string) => Promise<T>,
  seed?: number,
): Promise<T> {
  const response = await callModel(prompt);
  rec.record({ kind: "model_call", prompt, response: response.text, seed });
  return response;
}

ツールとモデル呼び出しを構築時に一度ラップするだけで、エージェント本体のコードは触りません。エージェント自身は記録されている事実を知らなくていい — このシームを保てば、後からホットパスで記録を切る判断もしやすくなります。

ひとつ細かいけれど大事なポイントは、「録画モード」のフラグはラッパー側ではなくレコーダー側に持たせることです。live / record / replay の3モードが同じ呼び出し形を共有できます。ラッパーをいじって切り替えるようになると、抽象が漏れていて、いずれリプレイドリフトが忍び込んできます。

状態スナップショットを「世界を止めずに」取る

状態層は3層のなかで一番扱いが難しい層です。メモリ・コンテキスト・ツール状態の整合的なスナップショットを欲しいけれど、動いているエージェントを止めるわけにはいきません。私が現場で使っているのは「アイドル時のチェックポイント」と「コピーオンライト・スナップショット」の2つです。

前者はシンプルで、エージェントが1ターンを終えてループに制御を返した直後、次のターンが始まる前に状態をディスクへ書き出します。チャット型のように、自然なアイドル区切りがある構成に合います。

後者は、Manager Surface 配下のサブエージェントのように継続稼働して自然な区切りがない構成で必要になります。状態コンテナを CoW データ構造（TypeScriptなら Immer が選択肢として綺麗です）でラップし、不変参照のスナップショットを任意の時点で取れるようにします。

// agent-replay/state-snapshot.ts
import { produce, type Draft } from "immer";
 
export class AgentState<T> {
  constructor(private state: T) {}
 
  // 不変的更新。スナップショット用に直前の凍結参照を返す
  update(mutator: (draft: Draft<T>) => void): T {
    const previous = this.state;
    this.state = produce(this.state, mutator);
    return previous;
  }
 
  snapshot(): T {
    return this.state;
  }
}

体に染み込ませたい原則はひとつ。スナップショットは「値」であって「イベント」ではないということです。何とも調整せずに取れるべきもの。「世界を止めなければ取れない」となった瞬間、定期的には取られなくなり、不整合な状態層は無いよりも悪いものに変わります。

リプレイの限界 — 何を再現できないかを正直に語る

リプレイの「できない範囲」を最初に明確にしておくことが、チームメイトからの信頼を一番大きく稼ぎます。どんなリプレイ基盤でも再現できないカテゴリーがあります。先に並べておきましょう。

外部の世界状態は分かりやすい一例です。エージェントが深夜2時に検索APIを呼び、その後インデックスが更新されていれば、同じ呼び出しを再生しても結果は変わります。リプレイ層では、ライブAPIを再叩きするのではなく、記録した結果をそのまま返すスタブが必要です。

時間依存の判断も同じ問題を持ちます。エージェントのプロンプトに「今日の日付」が混じっていれば、翌日の生クロックで再生すれば下流の結果が変わります。クロックを抽象化して、エージェントが観測したタイムスタンプを記録しておきます。

モデル外のランダム源も三つ目の落とし穴です。エージェントが生成したUUID、再試行のジッター、ランダムなスケジューリング — それぞれをラップして、ライブ実行中に返した値を記録しておきます。再生時にはその値を返します。

3つに共通する原則は同じです。エージェントが自分の決定論ロジックの外から観測したものは、境界で全部捕まえる — 再生時に再計算しません。これが腑に落ちると、設計が自然に一般化します。

ストレージ戦略 — ホット/コールドの切り分け

録画は意外なほど早く膨らみます。1セッションでツール呼び出しが20回、プロンプトが各数千トークンほどある中規模エージェントだと、1セッションで1MBほどの録画になります。1日1,000セッションなら日次1GB、年間で約3分の1テラバイト。階層化なしでは早晩コストが効いてきます。

私が本番で使っているストレージ階層は3つです。

• ホット層（直近7日）: 高速なオブジェクトストア（Cloudflare R2 や S3 の標準クラス）。新しい不具合報告にすぐ手が届く層
• ウォーム層（7〜90日）: アクセス頻度が低めのストレージクラスへ移す。レイテンシは少し上がるが、コストは半分以下に。多くのリプレイはここで完結
• コールド層（90日以上）: Glacier 系へ保持期間ポリシーつきで送る。コンプライアンス調査や3ヶ月以上前のインシデント分析でしか触らない

階層間の移動はライフサイクルルールで宣言的に組むのが鉄則です。アドホックなスクリプトで運用すると、必ず腐ります。監査チェーンの prevHash 連鎖は、各レコードが自身のハッシュを抱えているので階層をまたいでも生きたままです。

プライバシー — 録画はあらゆる機微情報を抱える

リプレイ層は、定義上「ユーザーが入れたプロンプトのすべて」「エージェントが見たツール結果のすべて」のデータベースです。流れる機微情報は何であれ含まれます。これを一次ユーザーDBと同じ重みで扱うかどうかは、譲ってはいけない判断です。

私が録画ストアに必ずかける最小限のラインは次の通りです。

• 保存時暗号化。プラットフォームが許せばカスタマー管理鍵を使う
• アクセスログを録画ストア自身に。録画を読んだ事実が必ずトレースに残る
• 記録時の伏字化を既知の機微パターン（メール・電話・カード番号）に対して。デバッグの解像度より、責任のリスクを下げるほうが優先
• 削除権の伝播。ユーザーがデータ削除をリクエストしたら、そのセッションIDに紐づく録画もすべて削除します。階層化したあとほど、これが意外と難しい

「ただのデバッグログ」と思って扱った瞬間、何かのスクリーンショット・Slackメッセージ・公開バグレポートに混入します。これは仮想の話ではなく、私自身が3つ全部見たことがあります。プライバシーの境界を先に作って、デバッグ便益はそのあとに乗せる順番にしてください。

モデルバージョンを跨いだリプレイ

モデルは静かに変わります。プロバイダーがマイナーバージョンをロールアウトし、旧バージョンを廃止し、ときには同じエンドポイント裏で重みを差し替えます。バージョンA で取った録画を、バージョンBで再生すると、同じプロンプト・同じパラメータでもまったく別の応答が返ってきうるのです。

私が習慣にしているのは、モデルのバージョン文字列とプロバイダーの応答ヘッダーを決定層の一部として記録すること。そして、別のモデルバージョンで「ライブリプレイ」しようとしたら、明示的な --cross-version フラグをエンジニアに要求するようリプレイヤーに作らせること。ドリフトの可能性を警告してから走らせます。

決定論的リプレイ（イベント層）は、ツール結果がスタブされているので影響は薄めです。けれど、モデル再呼び出しを伴う分析では、バージョン固定は誠実な唯一の手段です。

これは私自身、苦い形で覚えました。モデル更新前に取った録画を、別件の調査で更新後に再生し、ツールが誤動作していると結論しかけたのです。実際には新しいモデルバージョンの応答差でした。返してもらえるなら返してほしい朝のひとつです。

録画群が回帰テストになる瞬間

リプレイ層を作って思いがけなかった副作用が、蓄積した録画群が次第に「回帰テストスイート」として機能し始めることでした。代表的な振る舞いとエッジケースを捉えた録画を少しキュレートし、エージェントのコード・プロンプト・ツールを変えるたびに再生して差分を見る、という運用です。

素朴なやり方は「最終出力を比較する」ですが、それは脆すぎます。モデルの軽い揺らぎでも文面はずれるためです。実用的なのはツール呼び出しのシーケンスをイベント層で比較すること。文面は揺れても、「どのツールをどの順序で・どんな引数で呼ぶか」という構造的な決定は十分安定していて、意味のある差分として読めます。

// agent-replay/regression.ts
import { ReplayEvent } from "./recorder";
 
export function toolCallTrace(events: ReplayEvent[]): string[] {
  return events
    .filter((e): e is Extract<ReplayEvent, { kind: "tool_call" }> => e.kind === "tool_call")
    .map((e) => `${e.name}(${Object.keys(e.args ?? {}).sort().join(",")})`);
}
 
export function compareTraces(a: ReplayEvent[], b: ReplayEvent[]): { ok: boolean; diff: string } {
  const ta = toolCallTrace(a);
  const tb = toolCallTrace(b);
  if (ta.length !== tb.length) return { ok: false, diff: `length ${ta.length} vs ${tb.length}` };
  for (let i = 0; i < ta.length; i++) {
    if (ta[i] !== tb[i]) return { ok: false, diff: `step ${i}: ${ta[i]} vs ${tb[i]}` };
  }
  return { ok: true, diff: "" };
}

ツール呼び出しのシグネチャを比較します。引数の値ではなく、形を比較します。モデルの自然な揺らぎは飲み込みつつ、重要なツール呼び出しが消えたら検知できる粒度です。CIで走らせて、差分があればビルドを止める。

リプレイ層がこの瞬間から「過去の不具合からの回復」だけのツールではなく、「将来の不具合の予防」へと役割を広げます。複利的なリターンが付き始める瞬間です。

失敗履歴の学習ループへ閉じる

最後に触れたいのは、失敗した録画群をどう活かすかです。再現してフィックスした録画が積み上がったら、それは単なる過去の記録ではなく、評価パイプラインの教材になります。

各録画に「何が誤りで、どう振る舞うべきだったか」を短く付記しておきます。プロンプト・ツール・エージェント構造を変えるたびに、それらの録画を新しいエージェントに通して、今度は正しい振る舞いをするか確認します。リプレイ層は、本番に届く前に回帰を捕まえるための学習ループの土台になっていきます。

これがリプレイ設計の自然なゴールだと、私は感じています。過去の再現が、未来の予防につながる場所。多くのチームがここに辿り着けないのは、最初の録画層を作っていないからにすぎません。最初の層さえきちんと組めば、残りはひとりでに閉じていきます。

締めくくり

AIエージェントの開発は、ある意味で「再現できないものを扱う設計」の連続です。確率的に揺らぐ判断、外部APIに依存した状態、ツール間の暗黙の順序 — これらを全部決定論的にしようとすると、エージェントの良さを殺してしまいます。一方で、何も再現できないままでは、不具合に向き合うことすらできません。

リプレイ設計は、その間を歩く方法のひとつです。完全な再現を諦めて、「どこまで再現すれば十分か」を線引きします。線を引いたところまで真摯に記録します。残りは確率としてそのまま受け止める。この姿勢は、技術的な選択というよりも、AIと付き合うときの態度のようなものだと、私は静かに考えています。

次に手を動かすなら、お使いのエージェントに SessionRecorder を1つだけ仕込んでみてください。録画ファイルが手元に残った瞬間から、不具合との向き合い方が変わります。

最後までお読みいただき、ありがとうございました。リプレイ設計を取り入れたあとの肌感や、ハマったポイントなどがあれば、いつかどこかで共有してもらえると、私もまた一歩前に進めます。