cloudflare-workers

Cloudflare Workers

googleadsagent.ai™によるAgent Skills™の一部です。

説明

Cloudflare Workers は、Durable Objects、KV、R2、D1、AI バインディング、Vectorize を使用して、エッジファーストなアプリケーションを構築するための包括的なガイダンスを提供します。このスキルには、googleadsagent.ai™を支える実際の Workers（AI オーケストレーションを担う buddy-agent、D1/Vectorize を使用したナレッジストレージを担う buddy-brain、エッジでの静的コンテンツ生成を担う blog-engine）で使われている本番環境向けのパターンがまとめられています。

Workers は、300 か所以上のエッジロケーションにある V8 アイソレートで実行され、コールドスタートは 1 ミリ秒未満で、コンテナのオーバーヘッドもありません。これにより、アプリケーションのアーキテクチャは根本的に変わります。計算処理はユーザーの近くで行われ、状態はグローバルに分散されたストレージに保存され、従来のサーバーの概念（プロセス、スレッド、ファイルシステム）は当てはまりません。正しく高性能な Worker コードを生成するには、エージェントがこれらの制約を理解する必要があります。

Durable Objects は、Workers だけでは実現できないステートフルな調整レイヤーを提供します。各 Durable Object インスタンスは、トランザクション対応の SQLite ストレージ、WebSocket サポート、アラームのスケジュール設定機能を備えた、シングルスレッドのアクターです。ルーティングにステートレスな Workers を、調整にステートフルな Durable Objects を組み合わせることが、複雑なエッジアプリケーションすべての基盤となるパターンです。

使用する場面

• Cloudflare Workers 上にサーバーレス API を構築する場合
• Durable Objects を使用してステートフルな調整を実装する場合
• KV、R2、D1、Vectorize にデータを保存する場合
• Workers AI を使用してエッジで推論を実行する場合
• googleadsagent.ai™と同様のアーキテクチャでアプリケーションをデプロイする場合
• 従来のサーバーアーキテクチャからエッジファーストに移行する場合

動作の仕組み

graph TD
    A[Client Request] --> B[Worker: Route + Auth]
    B --> C{Request Type}
    C -->|API| D[Durable Object: buddy-agent]
    C -->|Content| E[KV: Cached Pages]
    C -->|Upload| F[R2: Object Storage]
    C -->|Query| G[D1: SQLite Database]
    D --> H[Workers AI: Inference]
    D --> I[Vectorize: Embeddings]
    G --> J[buddy-brain: Knowledge Base]
    E --> K[blog-engine: Page Serving]
    H --> L[Response to Client]
    I --> L
    J --> L
    K --> L

Worker はステートレスなルーターとして機能します。リクエストを認証し、適切なバインディングを特定して、専用のストレージレイヤーまたはコンピュートレイヤーに処理を委譲します。Durable Objects は、強い一貫性が必要な調整（セッション、キュー、レート制限）を処理します。

実装

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname.startsWith("/api/chat")) {
      const id = env.BUDDY_AGENT.idFromName("default");
      const agent = env.BUDDY_AGENT.get(id);
      return agent.fetch(request);
    }

    const cached = await env.PAGE_CACHE.get(url.pathname);
    if (cached) return new Response(cached, {
      headers: { "Content-Type": "text/html", "Cache-Control": "public, max-age=3600" },
    });

    return new Response("Not Found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;

export class BuddyAgent extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const body = await request.json<{ message: string }>();

    const embedding = await this.env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [body.message],
    });

    const similar = await this.env.VECTORIZE.query(embedding.data[0], {
      topK: 5,
      returnMetadata: "all",
    });

    const context = similar.matches.map(m => m.metadata?.text).join("\n");
    const response = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [
        { role: "system", content: `Context: ${context}` },
        { role: "user", content: body.message },
      ],
    });

    return Response.json({ reply: response.response });
  }
}

// wrangler.jsonc
{
  "name": "buddy-agent",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-01",
  "durable_objects": {
    "bindings": [{ "name": "BUDDY_AGENT", "class_name": "BuddyAgent" }]
  },
  "kv_namespaces": [{ "binding": "PAGE_CACHE", "id": "abc123" }],
  "vectorize": [{ "binding": "VECTORIZE", "index_name": "buddy-brain" }],
  "ai": { "binding": "AI" }
}

ベストプラクティス

• Workers ではグローバルな可変状態を使用しないでください。リクエスト間でアイソレートが再利用されない場合があります
• 大きなレスポンスはメモリにバッファリングせず、ストリーミングしてください（上限は 128MB です）
• レスポンスをブロックしないバックグラウンド処理には waitUntil() を使用してください
• compatibility_date を固定し、自動ではなく、意図的に更新してください
• Durable Objects は、主なユーザーベースに近い locationHint に配置してください
• シークレットは Wrangler のシークレット（wrangler secret put）に保存し、決して vars に保存しないでください

プラットフォームの互換性

プラットフォーム	サポート	備考
Cursor	完全	Wrangler CLI との統合
VS Code	完全	Cloudflare 拡張機能を利用可能
Windsurf	完全	Workers 対応のデプロイ
Claude Code	完全	Shell と wrangler にアクセス可能
Cline	完全	ターミナルベースの開発
aider	一部	設定ファイルの生成

関連スキル

• エッジレンダリング
• オブザーバビリティ
• サービスディスカバリー
• サンドボックスの強化

キーワード

cloudflare-workers durable-objects kv r2 d1 workers-ai vectorize edge-computing serverless buddy-agent

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License