エージェントを本番運用に乗せると必ずぶつかる壁が「状態管理」です。エージェントが生成したドラフト、編集中のコード、過去の判断ログ——これらをどこに、どう保存するか。S3 に投げるだけでは差分も履歴もなく、別途 PostgreSQL に持つと運用が爆発します。
ここに新しい選択肢として登場したのが、Cloudflare が発表した「Cloudflare Artifacts」です。Git 互換のバージョン管理と RESTful API を持ったファイルシステムで、AI エージェントの成果物管理を一気に楽にします。本記事では、受託開発で Artifacts を採用するときの設計パターンと、既存ストレージから移行するときの実装ステップを整理します。
なぜ Git 互換FSが必要なのか
エージェントの状態管理で発生する典型的な要件を並べると、Git の機能とほぼ同じであることに気付きます。
| エージェント側の要件 | Git 相当の機能 |
|---|---|
| 過去の出力に巻き戻したい | git checkout <commit> |
| 並列に複数案を試したい | git branch |
| 修正前後の差分を人がレビュー | git diff |
| 採用案だけ本流に取り込む | git merge |
| 誰が何を変えたかを追跡 | git blame / git log |
Cloudflare Artifacts はこれらをそのまま REST API 化しているため、「エージェントが Git ライクに状態を扱う」というユースケースに最短で対応できます。
私たちが pgvector の本番運用ガイド で書いたように、エージェント基盤は「状態を持つ」前提で設計しないと、本番で必ず破綻します。Artifacts はその状態管理を、自前で作らずに済ませる現実的な選択肢です。
アーキテクチャの位置付け
エージェント基盤における Artifacts の役割を、4 つの状態レイヤに分けて整理します。
- Conversation State：直近の対話・思考プロセス → KV / Durable Objects
- Artifact State（本記事の対象）：エージェントが生成した成果物 → Cloudflare Artifacts
- Domain Data：本来の業務データ → 既存 DB（Postgres / 業務システム）
- Knowledge Base：RAG 用の参照データ → ベクトル DB（pgvector / Vectorize）
「会話履歴」と「成果物」を分離するのが設計の第一歩です。会話は揮発性で短命、成果物は人がレビューし長期保存される——性質が違うので、ストレージも分けます。
受託案件で頻出するユースケース
A. ドキュメント生成エージェント
提案書・議事録・要件定義書をエージェントに書かせる案件。Artifacts に commit させることで、
- 「3 つ前のバージョンに戻して」が一瞬
- 担当者ごとに branch を切って並行レビュー
- 確定版だけ main に merge
という運用が可能になります。Word/Google Docs のリビジョン履歴の比ではない柔軟性です。
B. コード生成 / 内製ツールビルダ
社内ツールをエージェントに作らせるユースケース。生成コードを Artifacts に置けば、人間がレビューして commit するか revert するかを決められます。誤生成コードが本番に紛れ込むリスクを大幅に下げられます。
C. 画像・動画ワークフロー
マルチモーダルエージェントが生成する画像のバージョン管理。同じ素材を A/B/C 案で並列生成し、採用案だけ main にマージ——というクリエイティブワークフローに最適です。
既存ストレージからの移行ステップ
S3 / GCS にエージェント成果物を保存している案件を、Artifacts に移行するときの段取りを示します。
Step 1. 「成果物」と「単発ファイル」を仕分ける
すべてを Artifacts に置くと、コストとレイテンシが跳ねます。「履歴・差分を見る価値があるもの」だけを Artifacts に寄せます。
// 仕分けの判断ロジック例
function shouldUseArtifacts(file: GeneratedFile): boolean {
if (file.size > 100 * 1024 * 1024) return false; // 100MB 超は S3
if (file.type === "log") return false; // 単発ログは S3
if (file.lifecycle === "ephemeral") return false; // 一時生成物は KV
return true; // それ以外は Artifacts
}Step 2. リポジトリ粒度の設計
Artifacts は Git と同じく「リポジトリ」単位でブランチや履歴を持ちます。「顧客 × プロジェクト × エージェント」 のような 3 軸で粒度を切るのが定石です。粒度が細かすぎると統計が取りづらく、粗すぎると権限分離ができません。
Step 3. コミットメッセージの設計
Git と同じく、commit には説明文を付けます。エージェント側が自動生成するため、テンプレを決めておくと検索性が上がります。
[agent:billing-summary] 顧客 #1234 の 2026-04 請求サマリ生成
- 元データ: invoices_2026_04.csv
- 判断: 期日超過 3 件を強調
- 信頼度: 0.92「エージェント名」「対象データ」「判断ポイント」「信頼度」を構造化しておくと、後で監査するときに価値が爆発的に上がります。
Step 4. 人間レビューフローの組み込み
Artifacts を使う最大の価値は「人間が差分レビューしてマージできる」点。Slack / 社内ポータルから
view diff <artifact_id>で差分を確認approve <artifact_id>で main にマージrevert <artifact_id>で巻き戻し
を呼べる UI を組みます。既存 SaaS API を MCP サーバー化する設計パターン で示した HITL の発想を、成果物管理にも適用します。
落とし穴：エージェントが暴走 commit するパターン
実装初期に必ず起きる事故が「エージェントが意味のない commit を毎秒打ち続ける」ことです。トークン消費・ストレージ・レビュー負荷のすべてが破綻します。対策は次の 2 つ。
- commit のレート制限：エージェント側に「直前 commit から N 秒以内なら追記、N 秒超えたら新 commit」のロジックを入れる
- 意味の閾値：差分行数 / トークン数が閾値を下回る変更は commit しない
まとめ — エージェントの「履歴」は財産になる
エージェントが生成した成果物・判断ログは、そのまま社内のナレッジ資産です。Artifacts のような Git 互換 FS に積み上げておくと、後から検索・再学習・監査・改善のすべてに使えます。
ただし、ここまで書いてきたとおり、Artifacts に何を寄せるかは案件ごとに答えが変わります。Step 1 の仕分けの線引き、Step 2 のリポジトリ粒度、レビュー UI をどこまで作り込むか——この 3 つの前提が変われば、必要な設計も期間もまるごと変わります。すでに S3 / GCS に成果物が積み上がっている状況と、これから基盤を組む状況でも出発点が違います。金融・医療・法務のように「過去のエージェント判断を遡って説明できること」を求められる領域なら、監査ログの設計はさらに前段から考える必要があります。
いま成果物をどこに置いていて、どこまで遡って説明を求められるのか——その 2 点を伺えれば、そこから逆算して構成を一緒に考えられます。お問い合わせフォーム からお声がけください。
