Antigravity エージェントのシャドウモード本番投入ガイド — 新バージョンを安全に試す段階的リリース戦略

// src/worker/shadow-router.ts
import { Hono } from "hono";
 
type Bindings = {
  AGENT_V1_URL: string;
  AGENT_V2_URL: string;
  SHADOW_QUEUE: Queue;
  SHADOW_ENABLED: string; // "true" | "false"
};
 
const app = new Hono<{ Bindings: Bindings }>();
 
app.post("/api/agent/run", async (c) => {
  const body = await c.req.json();
  const requestId = crypto.randomUUID();
  const startedAt = Date.now();
 
  // 1. 本番エージェントを同期で呼ぶ — ここがクリティカルパス
  let primaryRes: Response;
  try {
    primaryRes = await fetch(c.env.AGENT_V1_URL, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ ...body, requestId, version: "v1" }),
    });
  } catch (err) {
    // 本番が落ちた場合はそのまま 503。シャドウは無関係。
    console.error("primary_failed", { requestId, err: String(err) });
    return c.json({ error: "agent_unavailable" }, 503);
  }
 
  const primaryJson = await primaryRes.clone().json<unknown>();
 
  // 2. シャドウは ctx.waitUntil でバックグラウンド投入(本番に絶対干渉させない)
  if (c.env.SHADOW_ENABLED === "true") {
    c.executionCtx.waitUntil(
      enqueueShadow(c.env.SHADOW_QUEUE, {
        requestId,
        startedAt,
        request: body,
        primaryResponse: primaryJson,
      }).catch((err) => {
        // シャドウキュー投入失敗はログだけで握りつぶす
        console.error("shadow_enqueue_failed", { requestId, err: String(err) });
      }),
    );
  }
 
  return new Response(primaryRes.body, {
    status: primaryRes.status,
    headers: primaryRes.headers,
  });
});
 
async function enqueueShadow(queue: Queue, payload: unknown): Promise<void> {
  await queue.send(payload, { contentType: "json" });
}
 
export default app;

// src/worker/shadow-consumer.ts
import { z } from "zod";
 
const AgentOutputSchema = z.object({
  status: z.enum(["ok", "refused", "error"]),
  message: z.string(),
  citations: z.array(z.string()).optional(),
});
type AgentOutput = z.infer<typeof AgentOutputSchema>;
 
type Env = {
  AGENT_V2_URL: string;
  EMBED_URL: string;
  METRICS_KV: KVNamespace;
  ALERT_WEBHOOK: string;
};
 
export default {
  async queue(batch: MessageBatch, env: Env): Promise<void> {
    for (const msg of batch.messages) {
      try {
        await processOne(msg.body as ShadowJob, env);
        msg.ack();
      } catch (err) {
        // リトライ予算を消費させる
        msg.retry({ delaySeconds: 30 });
        console.error("shadow_consumer_failed", { err: String(err) });
      }
    }
  },
};
 
type ShadowJob = {
  requestId: string;
  startedAt: number;
  request: unknown;
  primaryResponse: unknown;
};
 
async function processOne(job: ShadowJob, env: Env): Promise<void> {
  const t0 = Date.now();
 
  // 1. シャドウ側で v2 エージェントを呼ぶ(タイムアウトとサーキットブレーカ込み)
  const shadowRaw = await callWithTimeout(
    env.AGENT_V2_URL,
    job.request,
    /* timeoutMs */ 8000,
  );
  const shadowLatencyMs = Date.now() - t0;
 
  // 2. スキーマ検証 — 本番との互換性が壊れていないか
  const primaryParsed = AgentOutputSchema.safeParse(job.primaryResponse);
  const shadowParsed = AgentOutputSchema.safeParse(shadowRaw);
 
  // 3. 構造化スコアを計算
  const score = await computeScore({
    primary: primaryParsed.success ? primaryParsed.data : null,
    shadow: shadowParsed.success ? shadowParsed.data : null,
    embedUrl: env.EMBED_URL,
  });
 
  // 4. メトリクスストアに書き込む(KVは月次集計用、別途 R2 や ClickHouse へ流すと尚良し)
  await env.METRICS_KV.put(
    `shadow:${job.requestId}`,
    JSON.stringify({
      ...score,
      shadowLatencyMs,
      schemaValidShadow: shadowParsed.success,
      schemaValidPrimary: primaryParsed.success,
      ts: Date.now(),
    }),
    { expirationTtl: 60 * 60 * 24 * 30 },
  );
}
 
async function callWithTimeout(url: string, body: unknown, timeoutMs: number) {
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
  try {
    const res = await fetch(url, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
      signal: ctrl.signal,
    });
    if (!res.ok) throw new Error(`shadow_http_${res.status}`);
    return await res.json<unknown>();
  } finally {
    clearTimeout(timer);
  }
}
 
async function computeScore(args: {
  primary: AgentOutput | null;
  shadow: AgentOutput | null;
  embedUrl: string;
}): Promise<{ exactHash: boolean; cosine: number; lengthDiff: number }> {
  const { primary, shadow, embedUrl } = args;
  if (!primary || !shadow) {
    return { exactHash: false, cosine: 0, lengthDiff: 0 };
  }
  const exactHash = primary.message === shadow.message;
  const cosine = await embedSimilarity(embedUrl, primary.message, shadow.message);
  const lengthDiff = Math.abs(primary.message.length - shadow.message.length);
  return { exactHash, cosine, lengthDiff };
}
 
async function embedSimilarity(url: string, a: string, b: string): Promise<number> {
  const res = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ texts: [a, b] }),
  });
  if (!res.ok) return 0;
  const { vectors } = (await res.json()) as { vectors: number[][] };
  return cosine(vectors[0], vectors[1]);
}
 
function cosine(a: number[], b: number[]): number {
  let dot = 0, na = 0, nb = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    na += a[i] * a[i];
    nb += b[i] * b[i];
  }
  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-9);
}

// src/worker/shadow-watchdog.ts
type Env = {
  METRICS_KV: KVNamespace;
  CONFIG_KV: KVNamespace;
  ALERT_WEBHOOK: string;
};
 
export default {
  async scheduled(_event: ScheduledEvent, env: Env): Promise<void> {
    const samples = await collectRecentSamples(env.METRICS_KV, 1000);
    if (samples.length < 50) return; // 最小サンプル数を確保するまで判定しない
 
    const stats = summarize(samples);
 
    // しきい値はサービス特性によって調整する
    const tooSlow = stats.p95LatencyMs > 6000;
    const tooDivergent = stats.meanCosine < 0.7;
    const tooManyErrors = stats.errorRate > 0.1;
 
    if (tooSlow || tooDivergent || tooManyErrors) {
      await env.CONFIG_KV.put("SHADOW_ENABLED", "false");
      await postAlert(env.ALERT_WEBHOOK, {
        title: "🛑 Shadow auto-disabled",
        reason: { tooSlow, tooDivergent, tooManyErrors },
        stats,
      });
      console.warn("shadow_killed", stats);
    }
  },
};
 
type Sample = {
  cosine: number;
  shadowLatencyMs: number;
  schemaValidShadow: boolean;
};
 
async function collectRecentSamples(kv: KVNamespace, limit: number): Promise<Sample[]> {
  const list = await kv.list({ prefix: "shadow:", limit });
  const out: Sample[] = [];
  for (const k of list.keys) {
    const v = await kv.get(k.name, "json");
    if (v) out.push(v as Sample);
  }
  return out;
}
 
function summarize(samples: Sample[]) {
  const lat = samples.map((s) => s.shadowLatencyMs).sort((a, b) => a - b);
  const p95 = lat[Math.floor(lat.length * 0.95)] ?? 0;
  const mean = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / Math.max(xs.length, 1);
  return {
    p95LatencyMs: p95,
    meanCosine: mean(samples.map((s) => s.cosine)),
    errorRate: samples.filter((s) => !s.schemaValidShadow).length / samples.length,
    n: samples.length,
  };
}
 
async function postAlert(url: string, payload: unknown) {
  await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(payload),
  }).catch(() => undefined);
}