Gemini API + Cloudflare Durable Objects でつくるステートフルAIエージェント本番ガイド

# wrangler.toml
name = "gemini-stateful-agent"
main = "src/worker.ts"
compatibility_date = "2026-04-01"
compatibility_flags = ["nodejs_compat"]
 
[[durable_objects.bindings]]
name = "AGENT"
class_name = "ChatAgent"
 
[[migrations]]
tag = "v1"
new_sqlite_classes = ["ChatAgent"]
 
[vars]
GEMINI_MODEL = "gemini-2.5-pro"
 
# secret は wrangler secret put で投入する
# - GEMINI_API_KEY

// src/worker.ts
export { ChatAgent } from "./agent";
 
export interface Env {
  AGENT: DurableObjectNamespace;
  GEMINI_API_KEY: string;
  GEMINI_MODEL: string;
}
 
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const sessionId = url.searchParams.get("session");
 
    if (!sessionId) {
      return new Response("session query param required", { status: 400 });
    }
 
    // sessionId をキーに DO の ID を生成。
    // idFromName は決定論的なので、同じ sessionId は常に同じ DO に届く。
    const id = env.AGENT.idFromName(sessionId);
    const stub = env.AGENT.get(id);
 
    // リクエストをそのまま DO に丸ごと渡す
    return stub.fetch(request);
  },
};

// src/agent.ts
import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
const HISTORY_LIMIT = 30; // 圧縮前の最大ターン数
 
interface Turn {
  role: "user" | "model";
  text: string;
  ts: number;
}
 
export class ChatAgent extends DurableObject<Env> {
  private sql: SqlStorage;
 
  constructor(state: DurableObjectState, env: Env) {
    super(state, env);
    this.sql = state.storage.sql;
 
    // SQLite テーブルを 1 度だけ作成
    this.sql.exec(`
      CREATE TABLE IF NOT EXISTS turns (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        role TEXT NOT NULL,
        text TEXT NOT NULL,
        ts INTEGER NOT NULL
      );
      CREATE TABLE IF NOT EXISTS summary (
        id INTEGER PRIMARY KEY CHECK (id = 1),
        content TEXT NOT NULL DEFAULT ''
      );
      INSERT OR IGNORE INTO summary (id, content) VALUES (1, '');
    `);
  }
 
  async fetch(request: Request): Promise<Response> {
    const upgrade = request.headers.get("Upgrade");
    if (upgrade !== "websocket") {
      return new Response("WebSocket only", { status: 426 });
    }
 
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);
 
    // Hibernation 対応の WebSocket 受け入れ。
    // 重要: server.accept() を直接呼ばず、acceptWebSocket を使う
    this.ctx.acceptWebSocket(server);
 
    return new Response(null, {
      status: 101,
      webSocket: client,
    });
  }
 
  // Hibernation API: メッセージ受信ハンドラ
  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
    if (typeof message !== "string") {
      ws.send(JSON.stringify({ type: "error", reason: "binary not supported" }));
      return;
    }
 
    let parsed: { type: string; text?: string };
    try {
      parsed = JSON.parse(message);
    } catch {
      ws.send(JSON.stringify({ type: "error", reason: "invalid json" }));
      return;
    }
 
    if (parsed.type !== "user_message" || !parsed.text) {
      ws.send(JSON.stringify({ type: "error", reason: "missing text" }));
      return;
    }
 
    await this.handleUserMessage(ws, parsed.text);
  }
 
  async webSocketClose(ws: WebSocket, code: number) {
    // 切断時に特別な処理は不要。Hibernation で自動的にメモリ解放される
    console.log("ws closed", code);
  }
 
  private async handleUserMessage(ws: WebSocket, userText: string) {
    const now = Date.now();
 
    // 1. ユーザー発話を保存
    this.sql.exec(
      "INSERT INTO turns (role, text, ts) VALUES (?, ?, ?)",
      "user",
      userText,
      now,
    );
 
    // 2. 履歴と要約を取得
    const turns = this.fetchRecentTurns();
    const summary = this.fetchSummary();
 
    // 3. Gemini にストリームリクエスト
    const reply = await this.callGeminiStream(ws, summary, turns, userText);
 
    // 4. AI 応答を保存
    this.sql.exec(
      "INSERT INTO turns (role, text, ts) VALUES (?, ?, ?)",
      "model",
      reply,
      Date.now(),
    );
 
    // 5. 履歴が増えすぎたら古い部分を要約して圧縮
    const totalTurns = this.countTurns();
    if (totalTurns > HISTORY_LIMIT) {
      // バックグラウンドで実行（クライアントを待たせない）
      this.ctx.waitUntil(this.compressHistory());
    }
  }
 
  private fetchRecentTurns(): Turn[] {
    const cursor = this.sql.exec<Turn>(
      "SELECT role, text, ts FROM turns ORDER BY id DESC LIMIT ?",
      HISTORY_LIMIT,
    );
    return [...cursor].reverse();
  }
 
  private fetchSummary(): string {
    const cursor = this.sql.exec<{ content: string }>(
      "SELECT content FROM summary WHERE id = 1",
    );
    return [...cursor][0]?.content ?? "";
  }
 
  private countTurns(): number {
    const cursor = this.sql.exec<{ n: number }>("SELECT COUNT(*) AS n FROM turns");
    return [...cursor][0]?.n ?? 0;
  }
 
  private async callGeminiStream(
    ws: WebSocket,
    summary: string,
    turns: Turn[],
    userText: string,
  ): Promise<string> {
    const systemInstruction = summary
      ? `これまでの会話の要約: ${summary}\n\n上記を踏まえてユーザーに応答してください。`
      : "丁寧で簡潔に応答してください。";
 
    const contents = [
      ...turns.map((t) => ({
        role: t.role,
        parts: [{ text: t.text }],
      })),
      { role: "user", parts: [{ text: userText }] },
    ];
 
    const url =
      `https://generativelanguage.googleapis.com/v1beta/models/${this.env.GEMINI_MODEL}:streamGenerateContent` +
      `?alt=sse&key=${this.env.GEMINI_API_KEY}`;
 
    const res = await fetch(url, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        systemInstruction: { parts: [{ text: systemInstruction }] },
        contents,
        generationConfig: { temperature: 0.7, maxOutputTokens: 4096 },
      }),
    });
 
    if (!res.ok) {
      const errBody = await res.text();
      ws.send(JSON.stringify({ type: "error", reason: `gemini ${res.status}` }));
      throw new Error(`Gemini API ${res.status}: ${errBody.slice(0, 200)}`);
    }
 
    // Server-Sent Events を読みながら WebSocket に流す
    const reader = res.body!.getReader();
    const decoder = new TextDecoder();
    let buffer = "";
    let fullText = "";
 
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
 
      // "data: {...}\n\n" で区切られる
      const lines = buffer.split("\n\n");
      buffer = lines.pop() ?? "";
 
      for (const line of lines) {
        if (!line.startsWith("data: ")) continue;
        const json = line.slice(6).trim();
        if (!json) continue;
 
        try {
          const chunk = JSON.parse(json);
          const delta = chunk.candidates?.[0]?.content?.parts?.[0]?.text ?? "";
          if (delta) {
            fullText += delta;
            ws.send(JSON.stringify({ type: "delta", text: delta }));
          }
        } catch (e) {
          // 部分的な JSON は無視（次のチャンクで補完される）
          continue;
        }
      }
    }
 
    ws.send(JSON.stringify({ type: "done" }));
    return fullText;
  }
 
  private async compressHistory() {
    const oldCursor = this.sql.exec<{ id: number; role: string; text: string }>(
      "SELECT id, role, text FROM turns ORDER BY id ASC LIMIT ?",
      HISTORY_LIMIT - 10, // 直近 10 ターンは圧縮対象から除外
    );
    const oldTurns = [...oldCursor];
    if (oldTurns.length === 0) return;
 
    const oldText = oldTurns.map((t) => `${t.role}: ${t.text}`).join("\n");
    const prevSummary = this.fetchSummary();
 
    const url =
      `https://generativelanguage.googleapis.com/v1beta/models/${this.env.GEMINI_MODEL}:generateContent` +
      `?key=${this.env.GEMINI_API_KEY}`;
 
    const res = await fetch(url, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        contents: [
          {
            role: "user",
            parts: [
              {
                text:
                  `以前の要約:\n${prevSummary}\n\n` +
                  `追加の会話:\n${oldText}\n\n` +
                  `これらを 500 字以内の要約に統合してください。会話の論点と決定事項を必ず残してください。`,
              },
            ],
          },
        ],
        generationConfig: { temperature: 0.2, maxOutputTokens: 1024 },
      }),
    });
 
    if (!res.ok) return; // 失敗したら次の機会まで先延ばし
 
    const data = (await res.json()) as {
      candidates?: { content?: { parts?: { text?: string }[] } }[];
    };
    const newSummary = data.candidates?.[0]?.content?.parts?.[0]?.text ?? "";
    if (!newSummary) return;
 
    const ids = oldTurns.map((t) => t.id);
    // SQLite トランザクションで「要約更新 + 古い行の削除」を原子的に行う
    this.ctx.storage.transactionSync(() => {
      this.sql.exec("UPDATE summary SET content = ? WHERE id = 1", newSummary);
      const placeholders = ids.map(() => "?").join(",");
      this.sql.exec(`DELETE FROM turns WHERE id IN (${placeholders})`, ...ids);
    });
  }
}

<!-- index.html (Pages にデプロイする想定) -->
<!doctype html>
<html lang="ja">
<head><meta charset="utf-8"><title>Gemini Stateful Agent</title></head>
<body>
  <ul id="log"></ul>
  <input id="input" type="text" placeholder="質問を入力" style="width: 80%">
  <button id="send">送信</button>
<script>
  const sessionId = localStorage.getItem("sid") ||
    (() => { const s = crypto.randomUUID(); localStorage.setItem("sid", s); return s; })();
  const ws = new WebSocket(
    `wss://gemini-stateful-agent.YOUR-SUBDOMAIN.workers.dev/?session=${sessionId}`
  );
 
  const log = document.getElementById("log");
  let currentBubble = null;
 
  ws.onmessage = (ev) => {
    const msg = JSON.parse(ev.data);
    if (msg.type === "delta") {
      if (!currentBubble) {
        currentBubble = document.createElement("li");
        currentBubble.textContent = "AI: ";
        log.appendChild(currentBubble);
      }
      currentBubble.textContent += msg.text;
    } else if (msg.type === "done") {
      currentBubble = null;
    } else if (msg.type === "error") {
      const li = document.createElement("li");
      li.textContent = "[error] " + msg.reason;
      log.appendChild(li);
    }
  };
 
  document.getElementById("send").onclick = () => {
    const input = document.getElementById("input");
    const text = input.value.trim();
    if (!text) return;
    const li = document.createElement("li");
    li.textContent = "You: " + text;
    log.appendChild(li);
    ws.send(JSON.stringify({ type: "user_message", text }));
    input.value = "";
  };
</script>
</body>
</html>

// handleUserMessage の末尾。waitUntil による圧縮呼び出しはここから外す
private async scheduleCompactionIfNeeded() {
  const { count } = this.sql
    .exec<{ count: number }>("SELECT COUNT(*) AS count FROM turns")
    .one();
  if (count <= HISTORY_LIMIT) return;
 
  // 既にアラームが入っているなら二重予約しない
  const existing = await this.ctx.storage.getAlarm();
  if (existing !== null) return;
 
  // 応答を返し切った 2 秒後に圧縮する
  await this.ctx.storage.setAlarm(Date.now() + 2_000);
}
 
// Durable Objects のアラームハンドラ
async alarm() {
  const rows = this.sql
    .exec<Turn>("SELECT id, role, text, ts FROM turns ORDER BY id ASC")
    .toArray();
  if (rows.length <= HISTORY_LIMIT) return;
 
  const older = rows.slice(0, rows.length - HISTORY_LIMIT);
  const newSummary = await this.summarize(this.fetchSummary(), older);
 
  // 要約の更新と古い行の削除は必ず 1 つのトランザクションで
  this.ctx.storage.transactionSync(() => {
    this.sql.exec("UPDATE summary SET content = ? WHERE id = 1", newSummary);
    this.sql.exec(
      "DELETE FROM turns WHERE id IN (SELECT id FROM turns ORDER BY id ASC LIMIT ?)",
      older.length,
    );
  });
}

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Workers
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Deploy
        run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}