AIエージェントの状態だけを安全に残す「agent-flight-recorder-mini」を作りました

AIエージェントを日常的に動かしていると、「さっき何が起きたのか」「どのチェックポイントまで進んだのか」「ヘルスチェックは通っていたのか」を、あとから短く確認したくなる場面があります。

ただし、そこで会話全文やログ全文を雑に保存してしまうと、トークン、Cookie、認証URL、下書き本文、個人情報などを一緒に残してしまう危険があります。そこで作ったのが、agent-flight-recorder-mini です。

何をするプロジェクトか

agent-flight-recorder-mini は、ローカルのエージェントツールから送られる短い状態イベントだけを保存する、小さな Flight Recorder です。

こうした「状態」だけを、検索しやすいメタデータと、redaction 済みの小さな JSON payload として保存します。会話全文、長いログ、Discord 本文、X の下書き本文、記事本文、認証URL、raw session id などは保存対象にしません。

最初の実装ターゲットは Cloudflare Workers です。構成はかなりシンプルです。

初期構成では、DNS route、Tunnel、Zero Trust、Cron、Workers AI、本番サイト設定には触りません。まずは安全な最小構成で、エージェントの状態記録だけを扱う方針です。

API は、イベントの登録と検索に絞っています。

GET  /health
POST /events
GET  /events
GET  /events/:id
GET  /events/:id/raw

GET /health だけは公開で、D1 と R2 の binding があるかを返します。それ以外の endpoint は ADMIN_TOKEN が必要です。

POST /events では、source、event_type、severity、actor、task_id、summary、tags、metadata などを受け取り、検索に必要な情報を D1 に、redaction 済みの raw payload を R2 に保存します。

エージェント連携では、送信がタイムアウトしたあとに再送することがあります。そのとき同じイベントが何度も保存されると、あとから見たときに状態が読みづらくなります。

そのため、このプロジェクトでは任意の dedupe_key を持てるようにしています。同じ agent、source、event_type、task、dedupe_key の組み合わせがすでにあれば、新しい行を作らずに既存イベントを返します。

これにより、retry や spool replay をしても、論理的に同じイベントはひとつの記録として扱えます。

agent-flight-recorder-mini は、ログを何でも集めるための仕組みではありません。むしろ、送ってはいけないものを明確に決めることを重視しています。

イベントを送る前には、短い summary に要約し、必要な redaction を済ませます。contains_secret: true のイベントは送らない、redaction に失敗したら Flight Recorder 送信だけを諦める、という姿勢にしています。

Worker に直接 JSON を送るだけでなく、ローカル運用用の薄い shell wrapper も用意しています。

dry-run で payload を確認し、staging 送信では明示的な確認フラグを要求するようにしています。自動連携では親プロセスを止めないことも重要です。Flight Recorder 送信が失敗しても、エージェント本体の処理を巻き込んで失敗させない設計にしています。

送信失敗時は、retry できるエラーだけを短く再試行します。初期設定では 1 秒、2 秒、4 秒の指数バックオフに jitter を加えます。

それでも送れない場合は、redaction が完了した payload だけをローカル spool に保存できます。ここでも、secret や private URL が残っている可能性がある payload は保存しません。

このプロジェクトは public OSS 候補として整理しており、公開前チェックを通してから public 化する想定です。

publication check では、Worker の構文チェック、dedupe test、shell script の構文確認、公開前に残してはいけない marker の scan を実行します。GitHub Actions でも同じチェックを回せるようにしています。

agent-flight-recorder-mini は、豪華な監視基盤ではありません。目的はもっと小さく、AIエージェントの運用状態をあとから安全に確認できるようにすることです。

「全部保存する」のではなく、「残してよい状態だけを短く残す」。この制約を先に決めることで、エージェント運用の記録を扱いやすくしつつ、秘密情報や本文データを不用意に溜め込まない形にできます。