
AIエージェントの障害を後から「再生」する~Trace Engineeringの考え方~
最近、marfin(@marfinxx)さんの「Trace Engineering: The Observability Architecture for Autonomous AI Agents」を読みました。
自律型のAIエージェントを本番で動かすとき、障害の原因をどう追うか。この記事はそこに「ログではなくトレースで設計する」という答えを出しています。
エージェントの問題をプロンプトの工夫ではなく、分散システムの可観測性の問題として扱っている点が面白いです。
この記事では、原文を読んでいなくても分かるように、トレースとは何か、ログと何が違うのか、失敗をどう再生し、どう検証するのかを順に説明します。
【発端】 14ターン目の失敗が、ログから読めない

つまり、エージェントは長く動かすほど、失敗した場所と原因の場所が離れていきます。
原文は、次のような場面から始まります。5ステップの作業は順調なのに、100ステップ級の作業を任せると、14ターン目あたりで止まります。
開いたログは、標準出力、構造のないJSON、プロンプト履歴が混ざった数万行のテキストです。
どのサブエージェントが誤った前提を置いたのか、2ステップ目の幻覚が14ステップ目のAPI呼び出しをどうおかしくしたのかが、そこからは分かりません。
しかも再現するたびにAPI料金がかかり、確率的な呼び出しは毎回別の道を通ります。
原文はここから、実行を因果のグラフとして記録するという設計を、Trace Engineeringと呼んで整理します。
【基礎】 トレースは親子関係を持つ実行記録
つまり、トレースは「何が出力されたか」ではなく「何が何を呼んだか」を残す記録です。
分散システムの世界では、ひとつの処理をスパン(開始と終了、状態、属性を持つ作業の単位)で表します。OpenTelemetry(OTel、観測データの標準仕様とツール群)でも、スパンは一つの論理的な作業を指します。hidekazu-konishi
スパン同士は親子でつながり、まとまりがトレースです。サービスをまたいでも同じトレースとして追えるよう、W3Cが traceparent などのヘッダーの形式を定めています。[10][23]
エージェントに当てはめると、エージェントの呼び出し、モデルの呼び出し、ツールの実行がそれぞれスパンになります。OTelの生成AI向け規約には、invoke_agent や execute_tool といった名前が用意されています。veraexmachina
原文の設計では、ここに委譲(サブエージェントへの引き継ぎ)や、並列作業の合流点もスパンとして加わります。
【違い】 ログ・軌跡・トレースは別の記録

つまり、因果を持つ記録はトレースだけで、再現できる範囲もそこで決まります。
原文は、ログ、軌跡(会話ターンの並び)、トレースを混同するとうまくいかなくなりやすい設計になると指摘します。軸ごとに並べると違いが見えます。
形
テキストのログ:時系列の文字列
軌跡(ターンの列):直線の配列
トレース:親子付きのグラフ
因果
テキストのログ:時刻から推測
軌跡(ターンの列):直線なので暗黙
トレース:親子と依存で明示
並列処理
テキストのログ:出力が混ざる
軌跡(ターンの列):想定しない
トレース:分岐と合流を表せる
主な読み手
テキストのログ:人間の目視
軌跡(ターンの列):学習パイプライン
トレース:デバッガー、検証器、遮断器
状態コードが正しさを保証しない点は、大事です。存在しないDBスキーマを、文法的に正しいJSONで返したモデルは OK を返します。
だから原文は、実行時エラーは状態コードで、意味の誤りは実行記録による検証で捉える、と分けて考えます。
なお、OTelの基本は親子の木構造で、原文は並列サブエージェントを見据えて、グラフとして扱うことを勧めています。hidekazu-konishi
【仕組み】 台帳で再生し、スパンで検証する

つまり、記録を「あとから動かせる素材」にすると、デバッグと検証が同じ記録に載ります。
仕組みの中心はイベント台帳です。状態を上書きせず、起きた変化を追記だけで残す方式で、イベントソーシングと呼ばれる考え方です。
過去の状態を、イベントから再構成できます。martinfowler
原文は、ツールの応答、環境の観測、モデルの出力を、乱数シードやサンプリング設定と一緒に台帳へ記録するよう勧めています。
再生は二つの形に分かれます。
モック再生:N-1ターン目までを台帳の記録で返し、Nターン目だけ実際に動かす。上流のAPIを呼ばないので、推論コストはかかりません。
状態の再開:N-1ターン目の状態を復元し、実際のモデルで続ける。同じ履歴にプロンプトの修正を当てて試せます。
原因の特定は、後ろ向きにたどります。失敗したスパンが入力として使った依存の線だけを逆にたどり、起点を探します。
時刻順に遡るより、ノイズが減ります。
副作用の扱いも設計に入ります。ツールを登録する時点で、読み取り専用か、状態を変えるかを付けておきます。
状態を変えるツールは、実行前に先行書き込みログ(WAL)へ記録します。再生時はそれを受け止めて、実際の書き込みを防ぎます。
原文は、異常検知の例として、ステップ数の外れ値や、同じ引数で続く再試行の出力の偏りを数式で検出し、遮断する案も示しています。閾値は原文の提示値なので、自分の環境で調整する前提で読むのがよさそうです。
なお、原文には外部の研究事例と効果の数値も出てきますが、この記事では一次資料を確認できていないため、紹介しません。
【具体例】 「テストは通った」を、スパンの有無で確かめる

つまり、エージェントの自己申告ではなく、実行の痕跡を採点します。
原文の例では、エージェントが「全テストを実行し、回帰はゼロだった」と報告します。文章を読むだけのモデル採点は、もっともらしい説明に高い点を付けてしまいます。
トレースを使う検証器は、別のことを聞きます。「pytest を実行したツールスパンは、グラフにあるか」です。
無ければ、報告は不採用です。
この考え方は、手元の開発エージェントにそのまま移せます。たとえば、修正完了の報告に対して、「テスト実行のスパンがあり、終了コードが0か」を条件にします。
文章の出来ではなく、実行の記録で判定するので、報告の書き方をいくら工夫しても通りません。
【関連概念】 台帳、記憶、キャッシュへ広がる

つまり、同じトレースから、再現、学習、コスト管理の三つが派生します。
イベントソーシングの背景を知りたい場合は、Martin Fowlerの解説が基本になります。
トレースを学習に使う例がReasoningBankです。成功と失敗の経験から、再利用できる推論の方針を取り出して記憶にします。
失敗からも学ぶ点が特徴です。research
原文は、生のトレースを文脈に入れず、蒸留してから記憶に回すことを勧めています。
コストの面では、原文は入力、キャッシュ、出力、推論の各トークンを分けて記録するよう提案しています。プロンプトの先頭に変動する値を置くとキャッシュが効かなくなるため、固定部分を前、変動部分を後ろに置く、という順序の指摘もあります。
参考情報・参考書籍(PR)
本記事をより深く理解するために、概念マップスライドを作成しました。こちらをみることで理解の補助になるはずです。
Charity Majors、Liz Fong-Jones、George Mirandaの原書 Observability Engineeringは、英語で読める読者向けの一冊です。オブザーバビリティの考え方を、エージェントの観測の前提として置けます。
Mike Julian『入門 監視』は、何を、なぜ監視するかの基本を押さえる本です。エージェントの観測設計の前提になります。
『SRE サイトリライアビリティエンジニアリング』は、分散システムの監視と信頼性を、運用の側から補う本です。参考情報の Google SRE Bookに対応する書籍版です。
関連記事
【まとめ】 まず三点を、手元のエージェントで確かめる
つまり、仕組み全体を作る前に、記録の粒度だけ先に整えられます。以下は私が考えた確認項目で、効果は検証していません。
□ ツール呼び出しとモデル呼び出しが、一つずつ別のスパンになっているか。
□ 各ツールに、読み取り専用か状態変更かの区別があるか。
□ 失敗した実行を、モデルを呼ばずに途中まで再生できる記録が残っているか。
三つ目が難しければ、モデルのパラメータとツールの応答を保存するところから始められます。
「エージェントがそう言った」を信じる前に、「そのスパンはあるか」と問う。これが最初の一歩です。