AI Gateway と Agents — AI アプリの観測とエージェント

Workers AI を呼ぶ最小の Worker を作り、gateway オプション 1 つで AI Gateway 経由に切り替えて、ダッシュボードでログとコストを観察します。所要 15 分。

1. プロジェクトを作成します（Hello World example → Worker only → TypeScript を選択。デプロイは No）。

   npm create cloudflare@latest -- hello-aig
   cd hello-aig

2. wrangler.jsonc に AI バインディングを追加します。

   {
     "name": "hello-aig",
     "main": "src/index.ts",
     "compatibility_date": "2026-08-10",
     "ai": {
       "binding": "AI"
     }
   }

3. src/index.ts を次の内容に置き換えます。gateway.id に "default" を指定するだけで、この呼び出しが AI Gateway を通るようになります（default ゲートウェイは初回リクエスト時に自動作成されます）。

   export interface Env {
     AI: Ai;
   }
   
   export default {
     async fetch(request, env): Promise<Response> {
       const response = await env.AI.run(
         "@cf/meta/llama-3.1-8b-instruct-fast",
         {
           prompt: "What is the origin of the phrase Hello, World",
         },
         {
           gateway: {
             id: "default", // これだけで AI Gateway 経由になる
           },
         },
       );
   
       return new Response(JSON.stringify(response), {
         headers: { "Content-Type": "application/json" },
       });
     },
   } satisfies ExportedHandler<Env>;

4. npx wrangler dev で起動し、表示された http://localhost:8787 をブラウザで数回開きます。{"response":"A fascinating question!..."} のような JSON が返れば成功です。
5. ダッシュボードで AI → AI Gateway → default を開き、Logs タブを確認します。リクエストごとに、送ったプロンプト・モデルの応答・プロバイダ・トークン数（In / Out）・推定コスト・所要時間が記録されています。

Analytics タブではリクエスト数・トークン消費・エラー率の推移がグラフで見られます。コードの変更は実質 1 行（gateway オプションの追加）だけで、AI 呼び出しの可観測性が手に入りました。

REST API 経由で同じリクエストを 2 回送り、キャッシュヘッダの効果をレスポンスヘッダで確認します。所要 10 分。

1. アカウント ID とトークンを環境変数にセットします。

   export ACCOUNT_ID=$(npx wrangler whoami | grep -oE '[0-9a-f]{32}')
   export CF_TOKEN=$(npx wrangler auth token)

   取得できない場合はダッシュボードでアカウント ID を確認し、AI Gateway - Read / Edit と Workers AI - Read 権限の API トークンを作成してください。

2. cf-aig-cache-ttl ヘッダ（60 秒以上、最長 1 か月）を付けて同じリクエストを 2 回送り、cf-aig-cache-status ヘッダを確認します。

   for i in 1 2; do
     curl -si -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/v1/chat/completions" \
       --header "Authorization: Bearer $CF_TOKEN" \
       --header "cf-aig-gateway-id: default" \
       --header "cf-aig-cache-ttl: 3600" \
       --header "Content-Type: application/json" \
       --data '{
         "model": "@cf/meta/llama-3.1-8b-instruct",
         "messages": [{ "role": "user", "content": "say hello in one word" }]
       }' | grep -i "cf-aig-cache-status"
   done

3. 期待される出力は 1 回目が cf-aig-cache-status: MISS、2 回目が cf-aig-cache-status: HIT です。2 回目はプロバイダに到達していないため応答も高速で、課金も発生しません。
4. ダッシュボードの Logs でも 2 件目に Cached のマークが付いていることを確認します。逆にキャッシュを確実に避けたいリクエストには cf-aig-skip-cache: true ヘッダを付けます。

Agents SDK のスターターからカウンターエージェントを作り、永続状態が複数のブラウザタブへリアルタイム同期される様子を確認します。所要 20 分。

1. スターターテンプレートからプロジェクトを作成し、起動します。

   npm create cloudflare@latest -- --template cloudflare/agents-starter
   cd agents-starter
   npm install
   npm run dev

2. src/server.ts を次の内容に置き換えます。@callable() を付けたメソッドがクライアントから呼べる API になります。

   import { Agent, routeAgentRequest, callable } from "agents";
   
   export type CounterState = {
     count: number;
   };
   
   export class CounterAgent extends Agent<Env, CounterState> {
     initialState: CounterState = { count: 0 };
   
     @callable()
     increment() {
       this.setState({ count: this.state.count + 1 });
       return this.state.count;
     }
   
     @callable()
     reset() {
       this.setState({ count: 0 });
     }
   }
   
   export default {
     async fetch(request: Request, env: Env, ctx: ExecutionContext) {
       return (
         (await routeAgentRequest(request, env)) ??
         new Response("Not found", { status: 404 })
       );
     },
   } satisfies ExportedHandler<Env>;

3. wrangler.jsonc にエージェントを登録します。class_name はエクスポートしたクラス名と完全一致させ、new_sqlite_classes で状態永続化用の SQLite を有効にします。

   {
     "name": "my-agent",
     "main": "src/server.ts",
     "compatibility_date": "2026-08-10",
     "compatibility_flags": ["nodejs_compat"],
     "durable_objects": {
       "bindings": [
         { "name": "CounterAgent", "class_name": "CounterAgent" }
       ]
     },
     "migrations": [
       { "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }
     ]
   }

4. src/client.tsx を useAgent を使う実装に置き換えます。

   import "./styles.css";
   import { createRoot } from "react-dom/client";
   import { useState } from "react";
   import { useAgent } from "agents/react";
   import type { CounterAgent, CounterState } from "./server";
   
   export default function App() {
     const [count, setCount] = useState(0);
   
     const agent = useAgent<CounterAgent, CounterState>({
       agent: "CounterAgent",
       onStateUpdate: (state) => setCount(state.count),
     });
   
     return (
       <div>
         <h1>Counter Agent</h1>
         <p>{count}</p>
         <button onClick={() => agent.stub.increment()}>+</button>
         <button onClick={() => agent.stub.reset()}>Reset</button>
       </div>
     );
   }
   
   const root = createRoot(document.getElementById("root")!);
   root.render(<App />);

5. http://localhost:5173 をブラウザタブ 2 つで開き、片方で「+」を押します。もう片方のタブのカウントも即座に増えれば成功です。裏では、クライアントの stub.increment() が WebSocket RPC でエージェントに届き、setState() が SQLite へ永続化と全クライアントへのブロードキャストを同時に行っています。開発サーバーを再起動してもカウントが残っていることも確認しましょう。
6. 仕上げに npm run deploy でデプロイすると、エージェントは Cloudflare のグローバルネットワーク上で動き、クライアントが誰もいない間はハイバネーションしてコストがかかりません。