Cloudflare Artifactsでエージェントの成果を版管理する

エージェントの成果を、検証した版へ結びつける

教材アプリを二つのエージェントが同時に改善する。一方は見出しを直し、もう一方は入力検証を修正する。どちらもファイルと「チェック成功」を返した。比較するには、作業の起点、差分、チェックが調べた版を知る必要がある。最後に残ったディレクトリと緑の表示だけでは、その関係を説明しきれない。

Artifacts は、この作業単位を扱うための、プログラムから操作できる Git ストレージを提供する。所有者の台帳と変更を採用する判断は、アプリが持つ。タスク、基準 commit、候補 commit、検証結果を一緒に記録しよう。以下は設計例であり、Kumyu に稼働中のパイプラインがあるという説明ではない。

確認範囲は 2026 年 10 月 4 日時点。10 月 1 日の公式発表では、Artifacts は Workers Paid 向けのオープンベータ。個別アカウントでの利用可否、実際の隔離、処理性能、費用は今回試していない。演習もすべて未実施である。ドキュメントの初回公開日は不明とし、確認日とは別に、表示された改訂日を調査記録へ残している。

保存先の役割を分ける

残したいもの	保存・管理を担うものの例	その場所を使う理由
ソース、差分、commit の履歴	Artifacts の repo	作業の版を比較し、取り出せるようにする。
タスク所有者、権限判断、検証状態	Durable Object などに置くアプリの台帳	誰が作成、閲覧、採用、削除できるかを決める。
複数段階の検証	必要なら Workflow	個別のチェックと失敗を追う。
大きな動画、ログ、ビルド成果物	R2 など、選んだオブジェクトストレージ	大容量の出力に独自の保持期間を持たせる。
commit と外部成果物の対応	アプリ独自の小さな manifest	参照先とハッシュを、検証した commit へ結びつける。

この分担は著者の設計案である。Git ストレージだけでレビューの規則や生成コードの実行が成立するわけではなく、成果の安全性も証明されない。実行途中の状態を復元する問題は、Sandbox の状態を扱う記事で別に考える。

図を横にスクロールして読む。

公式の repo、イベント、CI の契約を基に作成した Kumyu の図。1 基準版を記録する。2 タスク別 repo と限定した資格情報を渡す。3 push された版を受け取る。4 その版を検証する。5 大きな成果物を別に残す。6 commit に結びついた証拠で候補を比較する。採用の判断はアプリの責務であり、破線はその範囲を表す。Artifacts の内部構成を描いたものではない。

repo を分けるか、branch を分けるか

repo は namespace 内で、それぞれの履歴、ref、remote、トークン、ライフサイクルを持つ。資格情報や削除時期を分けたい作業には、タスクごとの repo が適している。同じアクセス範囲を共有する共同作業なら、一つの repo の branch を使う選択もある。ただし、repo 単位のトークンを「この branch だけの権限」と説明してはいけない。

エージェントへ渡す前に、タスク用 repo の実際の起点 commit を記録する。binding の fork() が受け取るのは作成先の名前やオプションであり、指定したい commit hash ではない。動き続ける元 branch と、別途記録した基準版が、同時に固定されたと仮定しない。fork 先の起点を読み返して予定の基準と比較し、食い違うなら、作業を始める前に拒否するか、意図的に解決する。この照合はアプリの設計であり、製品の整合性保証を述べたものではない。

台帳には、たとえば taskId、ownerId、namespace、repo の識別子、基準 SHA、候補 SHA、検証記録の参照を置く。これは独自に提案した項目であり、Artifacts API のフィールドではない。対応を明示すると、「A を検証したのに B へ成功表示を付けた」という障害を調べやすくなる。

資格情報が通る経路を追う

認証の資料は、三つのインターフェースを分けている。

呼び出す側とインターフェース	認証に使うもの	この設計への影響
信頼する Worker の binding	設定済みの artifacts binding	実行時の API token を渡さず、結び付けた namespace を操作する。アプリへのタスク要求の認証・認可は先に行う。
外部の管理クライアントの REST	Artifacts Read / Edit 権限を持つ Cloudflare API token	管理用の資格情報を生成コードへ渡さない。
Git クライアント	repo 単位の Artifacts token、read または write	エージェントには作業先だけの書き込み権限、検証側には読み取り権限を渡せる。

Git protocol の資料では、通常のローカル作業に、返された remote と Bearer header を使う方法を勧めている。資格情報を remote URL、永続化する manifest、ブラウザーへの応答、コマンドの記録へ混ぜない。短命な token にも、信頼できる受け渡し経路が必要だ。有効期限は所有者の確認に代わらない。

binding の資料から、影響のある設定を拾う。

設定・メソッド	正確な意味	値の例と影響
artifacts[].binding、namespace	環境の binding 名と namespace の対応	ARTIFACTS と選んだ検証用 namespace で、操作対象を明示する。
get(name)	解放が必要な repo capability を返す	using で寿命を管理する。メタデータは想像したプロパティではなく info() で読む。
createToken(scope?, ttl?)	scope の省略時は write。TTL の単位は秒	"read", 3600 と明示すれば、1 時間の検証用読み取り資格情報を要求する。結果の plaintext、expiresAt を、権限のないクライアントへ返さない。

現行の資料は、binding の型生成と、ローカル開発で remote binding の Blob を返すメソッドを使う場合に、Wrangler 4.145.0 以降を求める。ここでは資格情報を発行しておらず、API 要求も実行していない。契約を読むための例であって、そのまま公開できる handler ではない。

イベントが指す版を固定する

push イベントの schemaには、種類 cf.artifacts.repo.pushed、source の namespace と repoName、payload の ref、before、after がある。A を push し、その検証中に B を push したとする。検証時に最新 branch を読み直すだけだと、B を調べた結果を A の結果として記録しかねない。イベントの after が指す版を解決して検証し、実際に調べた SHA をすべての結果へ残す。

設定した platform event の経路、所有する repo の許可リスト、厳密な payload 検証を使う。一般的な event subscriptions は、構造化した記録を Queues へ届ける仕組みである。汎用 HTTP webhook の署名方式を想像で補ったり、任意の呼び出し元が「push」を送れる公開 endpoint を作ったりしない。独自の HTTP 連携で転送するなら、その認証はアプリが別に担う。

queue consumer を使う場合、Queues の配送保証は at least onceであり、同じメッセージが届くことがある。namespace、repo、after、pipeline の版から検証キーを作り、処理を再び始める前に状態遷移を永続化する。実行中、成功、失敗を分けて残そう。キーを作るだけでは外部への操作を exactly once にできず、操作ごとに再試行の契約が要る。別の event → Workflow 経路へ Queues の保証をそのまま移してはいけない。

必要な範囲の CI を選ぶ

build の資料には、通常の Worker の build・deploy と、他 branch の preview に使う Workers Builds がある。独自 CI では Workflow を使い、検査、cache、再試行、必要なら配布までを組む。資料の例では、チェックの失敗が deploy 前に処理を止める。

独自 trigger では triggers.events の type を cf.artifacts.repo.pushed とし、namespace と repoName を filter へ指定する。repo の filter を省略すると、namespace 全体の push が対象になる。binding は資源へのアクセス、trigger は対象イベントの選択であり、どちらもアプリの所有者検証に代わらない。

branch とコマンドの方針が合うなら標準の build を使う。承認待ち、利用者別の配布、検証手順の分岐が必要なら独自処理を選ぶ。この演習はレビュー可能な候補版までで止める。自動の本番配布には、検証した同じ commit に結びつく別のリリース判断が必要になる。

作業領域の大きさと寿命を決める

現行の上限は、repo ごとに 1 GB、file / blob 一つで 32 MB、account 合計で 1 TB。account の上限は引き上げを申請できる。repo の数が無制限でも、保持するデータまで無制限になるわけではない。大きな外部成果物には、検証 commit、出力参照、digest、チェック結果を持つ小さな manifest を Git に置く。形式はアプリの契約であり、その対応の正しさを Artifacts が検証するわけではない。

ArtifactFSは、ファイル内容を必要に応じて取得しながら、作業ツリーを mount する選択肢である。対応する FUSE host と repo token が要る。大きなツリーへ早くアクセスできる代わりに、全内容が初めからローカルにあるとは限らず、初回の読み取りが待たされる。今回の小さな fixture には、普通の clone が扱いやすい。起動時間の改善は測定していない。

namespace の jurisdiction は、作成時に eu、us、または省略して制限なしを選ぶ。namespace 内のすべての repo に保存・処理の地域制限が適用され、後から変更できない。CI runner、モデル要求、ログ、R2 bucket の所在地まで決まる設定ではない。アプリ全体のデータ所在地を説明する前に、それぞれの経路を追う必要がある。

操作量と保持量を分けて見積もる

発表された価格表では、月 10,000 操作と 1 GB の保存を含み、超過は 1,000 操作あたり 0.15 米ドル、GB-month あたり 0.50 米ドル。保存量は全 repo を対象に、30 日の請求期間で日ごとのピークを平均して求める。repo は明示的に削除するまで残る。

**10 月 4 日時点で、課金開始日は未解決。**価格ページには 2026 年 10 月 14 日、10 月 1 日のブログには 10 月 15 日とある。どちらも未来の日付なので、課金が始まったとは扱わない。実際の利用予算を決める前に再確認する。

課金開始後に、月 30,000 操作と 5 GB-month を使い、この含まれる枠が適用されると仮定する。Artifacts の超過分は (30,000 − 10,000) / 1,000 × $0.15 + (5 − 1) × $0.50 = $5.00。発表済み単価での計算例であり、実測の請求額ではない。Workers Paid の基本料金、Worker / Workflow / runner の実行、モデル、ログ、他の保存先は含めていない。

たとえば、採用した変更と必要な証拠は残し、却下した使い捨て作業は合意したレビュー期間の後に期限を迎える、といった保持方針を定める。削除にはアプリ側の説明と権限判断が必要だ。予算のために利用者の repo を無断で消してはいけない。不要になった作業 token の失効と、残す履歴の判断も別々に行う。

演習：三つの失敗を見えるようにする

この未実施の演習は offline から始める。機密を含まない fixture に二つの変更案を作り、変更しないローカル commit A / B として扱う。token、account ID、公開 deploy を使わず、模擬イベントと review manifest を作る。まず、台帳が各チェックを実際の commit に結びつけることを示す。後で live 検証するなら、利用許可のある test account、Workers Paid、予算が必要になる。今回、環境は作成していない。

起こす条件	必要な観察	残す証拠
A の同じイベントを二度渡す	再試行状態が明示され、論理上の検証記録が一つになる	検証キーと結果の参照。
A の検証中に B を渡す	branch の先頭が B でも、A の結果は A のまま	イベントの after、検証 SHA、候補 SHA。
B のチェックを失敗させる	失敗が表示され、B を採用候補にできない	失敗したチェックと、変わっていない採用記録。
後日の許可済み live test で、read token から push する	token をログへ残さずに拒否を確認する	秘密値を除いた権限結果。

成果物は、第三者が「候補 → commit → check → 出力 digest」を追える小さなレビュー記録である。実行時間、再試行結果、費用は、実際に動かしてから測る。live 演習で予期しない公開、他 repo へのアクセス、資格情報の露出が起きたら停止し、秘密値を除いた失敗記録を残す。成功したことにして先へ進めない。