3行でいうと

  • 場面は5つです。①curlでWorkers AIを呼ぶ、②Workerに載せて wrangler dev と wrangler deploy、③AI Gatewayを通す、④AI Searchに資料を入れて検索する、⑤Agents SDKの雛形を動かす。
  • ①と③はWranglerなしでも進められます（トークンとアカウントIDが要る）。②と⑤は、npm create cloudflare@latest で雛形を作る手順です。
  • wrangler dev で手元で試すときも、モデルはCloudflareのアカウント上で動き、Workers AIの利用料が発生する、と公式のページが明記しています。
  • 返ってくるデータの形は、公式のページに載っている例（result.response、choices[0].message.content など）を写しています。モデルの答えの中身は、そのつど変わります。
  • 手順の最後に、後始末（Workerの削除、トークンの削除、ログアウト）の、公式に書かれている範囲をまとめました。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。コマンドとコードは「公式の例の写し」と書いたものだけが写しで、それ以外は「この記事で組んだ例（動作は確かめていません）」です。画面の表記は変わることがあるので、手元の画面と照らして読んでください。モデル名や、コマンドに出てくる版は、公式ページがその日に載せていたものです。

先に結論

前提：用語をそろえる

最初の1時間の順番（この記事の案）

公式の資料に「1時間の順番」はありません。次の表は、この記事で、各手順の重さを見て並べた案です。

めやす やること 使う節 先に必要なもの
0〜15分 アカウントを作り、Wranglerを入れ、wrangler login 05の段階1〜3 メール
15〜25分 curlで1回呼ぶ（トークンとアカウントIDを取る） 場面1 アカウント
25〜40分 hello-ai を作り、wrangler dev で見て、wrangler deploy 場面2 Node.js、Wrangler
40〜50分 ゲートウェイを作り、同じ呼び出しに足す 場面3 アカウント、トークン
50〜60分 後始末（トークン削除、Worker削除、ログアウト） 後始末 ――

AI SearchとAgents SDKは、上の1時間には入れていません（場面4、場面5）。

場面1：curlでWorkers AIを呼ぶ（公式の「Get started: REST API」）

1-1 トークンとアカウントIDを取る

  1. Cloudflareのダッシュボードで、Workers AI のページへ進みます。
  2. Use REST API を選びます。
  3. Create a Workers AI API Token を選びます。
  4. 画面に入っている内容を確かめて、Create API Token を選びます。
  5. Copy API Token を選んで、値を保管します。公式は、このトークンはプロフィールの画面にも表示される、と書いています（秘密の値の扱いは05の段階4）。
  6. Get Account ID の欄の Account ID の値をコピーして保管します。

自分でトークンを作る場合（テンプレートを使わない場合）は、Workers AI - Read と Workers AI - Edit の両方が要る、と公式に書かれています（権限の考え方は05の段階6）。

1-2 モデルを呼ぶ（公式のコマンドの写し）

{ACCOUNT_ID} と {API_TOKEN} を、保管した値に置き換えます。

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/meta/llama-3.1-8b-instruct \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -d '{ "prompt": "Where did the phrase Hello World come from" }'

期待される結果（公式の記述）：JSONが返り、答えは result.response に入り、success、errors、messages も並びます。公式の例の答えの内容は、「Hello World」という言い回しがBell Labsの1974年ごろの、Brian KernighanのCの例に結びつく、という説明です。答えの文章は毎回同じとは限りません。

別のモデルを使うときは、公式のモデル一覧（Workers AI models）から選び、URLの末尾の @cf/meta/llama-3.1-8b-instruct の部分を、そのモデルのIDに置き換えます。公式のページは「{model} を置き換える」と書いていますが、コマンドではモデル名がURLにそのまま書かれています（ページ内の書き方が少し違います）。

1-3 プロンプトを変えてみる（この記事の例）

次の指示文は、この記事で組んだ例です（動作は確かめていません）。形は公式の例と同じで、prompt の文だけを変えます。

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/meta/llama-3.1-8b-instruct \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -d '{ "prompt": "Explain what an API token is in two sentences." }'

モデルによって、日本語の答えの質や、使える入力の形が違うことがあります。モデルごとの入力の形は、公式のモデルのページで確認します。この記事では読めていません。

場面2：Workerに載せて、手元で見て、公開する（公式の「Get started: Workers and Wrangler」）

2-1 雛形を作る

  1. ターミナルで、次のコマンドを実行します（公式の写し）。
npm create cloudflare@latest -- hello-ai
  1. create-cloudflare（C3）の質問が出ます。公式のページが選ぶ答えは次のとおりです。
質問（公式の表記） 公式が選ぶ答え
What would you like to start with? Hello World example
Which template would you like to use? Worker only
Which language do you want to use? TypeScript
Do you want to use git for version control? Yes
Do you want to add an AGENTS.md file...? Yes
Do you want to deploy your application? No（先に手を入れるため）
  1. hello-ai というフォルダができ、中に src/index.ts（Hello Worldのプログラム）と wrangler.jsonc（設定ファイル）があります。フォルダに入ります。
cd hello-ai

2-2 AIのバインディングを足す

wrangler.jsonc に、次の欄を足します（公式の例の写し。公式は「Wranglerファイルの末尾に」と書いています）。

{
    "ai": {
        "binding": "AI"
    }
}

これは断片です。wrangler.jsonc では、最上位の { ... } の中に入れ、前の項目の後ろにカンマが要ります（公式のページの補足）。TOML形式（wrangler.toml）では、[ai] の下に binding = "AI" と書く、と併記されています。足すと、コードから env.AI で呼べます。

2-3 コードを書き換える

src/index.ts の中身を、公式のページのコードに置き換えます。公式のコードは、env.AI.run("@cf/google/gemma-4-26b-a4b-it", { messages: [...], chat_template_kwargs: { enable_thinking: false } }) を呼び、結果を Response.json(response) で返します。messages には、system の役割で「You are a helpful assistant.」、user の役割で「What is the origin of the phrase Hello, World」が入っています。コードの全文は、公式ページで確認してください。この記事は、写し間違いを避けるため、長いコードは載せていません。

2-4 手元で動かす

  1. 次のコマンドを実行します。
npx wrangler dev
  1. ログインを求められます（05の手順Aと同じです）。
  2. Wranglerが、多くの場合 localhost:8787 のURLを表示します。ブラウザで開くと、WorkerがAIを呼んだ結果が出ます。

期待される結果（公式の記述）：JSONが返り、choices[0].message.content に答えが入る形です（"object": "chat.completion" など、OpenAIのChat Completionsに似た形）。

重要（公式の注記）：Workers AIは常にCloudflareのアカウントを呼んでモデルを動かすため、ローカル開発でもWorkers AIの利用料が発生します。

2-5 公開する

  1. ログインします。
npx wrangler login
  1. ブラウザが開くので、ダッシュボードにログインし、Wranglerがアカウントに変更を加えることを許可するため Allow を選びます。
  2. 公開します。
npx wrangler deploy
  1. 公開先のURLは https://hello-ai.<あなたのサブドメイン>.workers.dev の形です。ブラウザで開くと、AIが答えます。

2-6 公開したあとに使う関連コマンド（公式のWorkersコマンドのページ）

コマンド 公式の説明（要約）
npx wrangler deploy --dry-run コンパイルだけして、実際の公開はしない
npx wrangler tail 各リクエストのconsoleログと例外を、リアルタイムで流す。--format、--status、--search などで絞れる。トラフィックが多いとサンプリングになり、メッセージが落ちることがある
npx wrangler dev --local 手元だけで動かし、リモートのバインディングを使わない（ただしAIのバインディングについては、上の公式の注記のとおり、常にアカウントを呼ぶと書かれている）
npx wrangler dev --remote Cloudflareのプレビュー環境で動かし、バインディングをリモートの資源につなぐ

--local とAIバインディングの関係は、読んだページでは詳しく書かれていません。AIを呼ぶコードの手元での挙動は、場面2の公式の注記（利用料が発生）を前提にしてください。

場面3：AI Gatewayを通して呼ぶ（公式の「Get started」ほか）

先に、05の段階7で、ゲートウェイを作っておきます。

3-1 Workers AIのモデルを、ゲートウェイ経由でcurlする（公式の例の写し）

公式のコメントは、$CLOUDFLARE_API_TOKEN の値は wrangler auth token で、アカウントIDは wrangler whoami で取れると書いています。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "@cf/moonshotai/kimi-k2.6",
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

ポイント（公式の記述）：Workers AIのモデルは、cf-aig-gateway-id のヘッダーが常に必要です。default は、既定のゲートウェイを指す値、と書かれています。公式の「Get started」は、default のゲートウェイが無ければ最初の認証つきリクエストで自動的に作られ、請求は Standard billing になる、とも書いています（05の段階7）。自分で作ったゲートウェイを使うなら、その名前を入れます。このモデル（kimi-k2.6）は、01によると、無料のままでは使えないモデルに入っています。

3-2 他社のモデルを呼ぶ（公式の例の写し）

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [{"role": "user", "content": "What is Cloudflare?"}]
  }'

公式の記述：他社のモデルのときは、ゲートウェイのヘッダーは不要で、default が自動で使われます。この例は提供元のキーをヘッダーに付けていません。提供元への認証は、Unified Billing（前払いクレジット）、BYOK（自分のキーをCloudflareに保存）、リクエストのヘッダー（自分でキーを送る）の3つが書かれています。どれを使うかの設定は、08で書きます。

3-3 Workerのバインディングから、ゲートウェイを指定する

公式の「Workers AIをAI Gatewayから使う」のページは、env.AI.run の3つ目の引数に gateway を足す形を示しています。

例（公式の例のうち、env.AI.run の呼び出し部分の写し。公式は fetch ハンドラーの中に書いています。TypeScript版もあります）：

const response = await env.AI.run(
    "@cf/meta/llama-3.1-8b-instruct",
    {
        prompt: "Why should you use Cloudflare for your AI inference?",
    },
    {
        gateway: {
            id: "{gateway_id}",
            skipCache: false,
            cacheTtl: 3360,
        },
    },
);

3-4 ログを見る・止める（公式の「Logging」）

場面4：AI Searchに資料を入れて検索する（公式の「Get started」のダッシュボード手順）

4-1 インスタンスを作る

  1. ダッシュボードで AI Search を開きます。
  2. Create Instance を選びます。
  3. インスタンスに名前を付けます。
  4. （任意）データソースをつなぎます。公式の例は、自分のウェブサイトか、R2のバケット（Cloudflareの保管場所）です。
  5. 設定を確かめます。
  6. Create を選びます。

4-2 資料を上げる

  1. AI Search で、作ったインスタンスを選びます。
  2. Items のタブを選びます。
  3. ファイルを上げます。公式は、AI Searchが自動で索引（検索用の目次）を作る、と書いています。

4-3 Playgroundで試す

  1. インスタンスの Playground のタブを開きます。
  2. Chat か Search を選びます。
  3. 問いを入れて、答えを見ます。公式は、内容の索引が済んでから行うよう書いています。

「Chat」と「Search」の違い（答えの文章まで作るか、該当箇所を返すか）は、読んだページでは説明されていません。

4-4 アプリから使う

公式は、Workers Binding（Workerのコードから）とREST API（HTTPで）の2つを挙げています。どちらも手順の中身は、この記事では読めていません。AI Searchの外部の道具からのつなぎ口（MCPの公開口）は、07の連携Dで書きます。

読めなかった点：モデルの選択肢、データソースの設定項目の名前、索引にかかる時間や区切り方、料金と制限（制限と料金のページは01と04で触れています）。

場面5：Agents SDKの雛形を動かす（公式の「Quick Start」）

AIの鍵やシークレットは要らない手順です（公式の記述）。

  1. 雛形を作ります（公式の写し）。
npm create cloudflare@latest -- --template cloudflare/agents-starter
  1. 雛形のフォルダに入り、依存を入れ、開発サーバーを起動します（フォルダ名は公式の例）。
cd agents-starter
npm install
npm run dev
  1. ブラウザで http://localhost:5173 を開きます。
  2. 雛形に入っているファイル（公式の記述）：src/server.ts（エージェントのコード）、src/client.tsx（Reactの画面）、wrangler.jsonc（設定）、tsconfig.json、vite.config.ts。
  3. 公式のクイックスタートは、カウンターのエージェントを作ります。src/server.ts に、Agent を継承したクラスを置き、状態（count）と、画面から呼べるメソッド（increment、decrement、reset）を持たせます。wrangler.jsonc には、Durable Objectsのバインディング（name と class_name）、migrations の new_sqlite_classes（状態の保存に使う）、compatibility_flags の nodejs_compat（agentsのパッケージに必要）を書きます。compatibility_date は今日の日付にする、と公式は注記しています。コードと設定の全文は、公式ページで確認してください。（取得の際、最初のコード例の一部が崩れて読めたため、この記事は写していません。）
  4. 画面のボタン（-、Reset、+）を押すと、数字がWebSocketで更新されます（公式の記述）。
  5. 公開は、次のコマンドです。公式のページは、Cloudflareへのログインやアカウントの設定が先に要るかどうかを書いていません。05の手順に従っておくことになります。
npm run deploy

後始末（公式に書かれている範囲）

対象 方法 出どころ・注意
作ったWorker npx wrangler delete。--name で指定、--env で環境、--dry-run で実際には消さずに出力だけ見られる 公式は、Workerと、関連するCloudflare開発者プラットフォームの資源すべてを削除すると書く。先に --dry-run で確かめるのが、この記事の案
APIトークン ダッシュボードのAPI Tokensのページで削除 05の段階4
Wranglerのログイン npx wrangler logout OAuthトークンを取り消し、保存した認証情報を削除（公式）
ゲートウェイ（AI Gateway） ―― 削除の手順は、読んだページに記載が見つからない
AI Searchのインスタンス ―― 削除の手順は、読んだページに記載が見つからない
アカウント ―― 閉鎖の手順は、読んだページに記載が見つからない（04を参照）

つまずきと直し方

症状 公式に書かれている原因・直し方 書かれていないこと
curlで認証エラー トークンの権限不足の可能性。自分で作ったトークンは Workers AI - Read と Workers AI - Edit の両方が要る エラーメッセージごとの対処
wrangler dev でログインを求められる 手順どおり（05の手順A）。続けてよい ――
手元で試したのに利用料がかかった 公式が明記：ローカル開発でもWorkers AIは常にアカウントを呼ぶ 無料枠で足りるかの目安（01・04）
ゲートウェイ経由のWorkers AIが失敗する Workers AIのモデルには cf-aig-gateway-id が常に必要 ゲートウェイ名の綴りの確認方法
認証つきゲートウェイでエラー ヘッダーなしだと「missing authorization」で失敗する。同じアカウントのWorkerのバインディング経由は、あらかじめ認証済み トークンの作り方の細部は08の連携E
有料プランが要るモデルで失敗する 01で書いたとおり、一部のモデルは無料のままでは使えない 具体的なエラーの形
Playgroundで答えが出ない 公式は、内容の索引が済んでから試すよう書いている 索引にかかる時間
deploy のURLが開けない 形は https://hello-ai.<あなたのサブドメイン>.workers.dev サブドメインの決まり方や、変え方

たとえ話：カウンターで頼んで、番号札で受け取る

curlは「カウンターに紙のメモを出して、答えをその場で受け取る」こと、Workerは「自分の店を出して、お客さんの注文をAIに取り次ぐ」こと、AI Gatewayは「その取り次ぎ口に、受付の帳簿を置く」ことです。帳簿には注文の中身が残りうるので、残す・残さないは自分で決めます。これは僕らのたとえで、公式の表現ではありません。

気をつけること

出典