Antigravity Agent 本番障害対応 Runbook 設計 — 検知から復旧・再発防止までの実践フレームワーク

// monitoring/agent-alerts.ts
// Antigravity Agent 用のアラート定義（OpenTelemetry + PromQL ベース）
import { Counter, Gauge, Histogram } from "@opentelemetry/api";
 
// ① 動作系: そもそも Agent が動いているか
export const agentRunCount = new Counter({
  name: "antigravity_agent_run_total",
  help: "Total number of Agent runs by status",
  labelNames: ["agent_id", "status"], // status: success | failure | timeout
});
 
// ② 品質系: 出力が業務要件を満たしているか
export const agentEvalScore = new Histogram({
  name: "antigravity_agent_eval_score",
  help: "Eval score (0-1) for Agent outputs",
  labelNames: ["agent_id", "eval_type"],
  buckets: [0.5, 0.7, 0.8, 0.9, 0.95],
});
 
// ③ コスト系: トークン消費が予算内か
export const agentTokenSpend = new Counter({
  name: "antigravity_agent_token_spend_usd",
  help: "Cumulative USD spend per Agent",
  labelNames: ["agent_id", "model"],
});
 
// ④ ループ系: 同じツールを暴走呼び出ししていないか
export const agentToolCallStreak = new Gauge({
  name: "antigravity_agent_tool_call_streak",
  help: "Consecutive identical tool calls (potential loop)",
  labelNames: ["agent_id", "tool_name"],
});

# monitoring/alerts.yml
# Antigravity Agent の本番アラートルール
groups:
  - name: antigravity_agent_alerts
    interval: 30s
    rules:
      # ① 動作系: 失敗率が 5 分間で 20% 超
      - alert: AgentFailureRateHigh
        expr: |
          (
            sum(rate(antigravity_agent_run_total{status="failure"}[5m])) by (agent_id)
            / sum(rate(antigravity_agent_run_total[5m])) by (agent_id)
          ) > 0.2
        for: 5m
        labels:
          severity: page
          runbook: agent-failure-rate
        annotations:
          summary: "Agent {{ $labels.agent_id }} failure rate > 20%"
 
      # ② コスト系: 1 時間で $20 超え（個人開発スケール）
      - alert: AgentTokenSpendBurst
        expr: |
          increase(antigravity_agent_token_spend_usd[1h]) > 20
        for: 5m
        labels:
          severity: page
          runbook: agent-cost-burst
        annotations:
          summary: "Agent {{ $labels.agent_id }} burned ${{ $value }} in 1h"
 
      # ③ ループ系: 同じツールを 30 回連続呼び出し
      - alert: AgentToolLoopDetected
        expr: antigravity_agent_tool_call_streak > 30
        for: 1m
        labels:
          severity: page
          runbook: agent-tool-loop
        annotations:
          summary: "Agent {{ $labels.agent_id }} stuck on {{ $labels.tool_name }}"
 
      # ④ 品質系: Eval スコアが過去 1 時間で 0.7 を下回る
      - alert: AgentQualityDegraded
        expr: |
          histogram_quantile(0.5, sum(rate(antigravity_agent_eval_score_bucket[1h])) by (le, agent_id)) < 0.7
        for: 15m
        labels:
          severity: ticket
          runbook: agent-quality-drop
        annotations:
          summary: "Agent {{ $labels.agent_id }} median eval score < 0.7"

## トリアージ・チェックリスト（5 分以内に完了）
 
- [ ] **alert ID** を取得 (例: `AgentFailureRateHigh-2026-04-28-02-15`)
- [ ] Manager Surface で該当 `agent_id` の `runId` を上から 3 件開く
- [ ] エラーメッセージのパターンを判定:
  - [ ] `ToolTimeout` → L2-A: タイムアウト緩和フロー
  - [ ] `RateLimitExceeded` → L2-B: バックオフ延長フロー
  - [ ] `MaxIterationsReached` → L2-C: ループ検出フロー
  - [ ] `EvalScoreDrop` → L2-D: モデルロールバックフロー
  - [ ] その他 → L2-E: Kill switch 発動を検討
- [ ] ユーザー影響を `cmd+K` で `is_user_facing` フィールド検索:
  - 「あり」: 60 秒以内に L2 を発動
  - 「なし」: 15 分内で L3 へ移行
- [ ] 横展開リスクの確認:
  - [ ] 同じ tool を使う他の Agent の失敗率 (PromQL: `rate(antigravity_agent_run_total{status="failure", tool_name="<name>"}[5m])`)
  - [ ] 下流サービス (DB, 外部 API) の応答時間
- [ ] **#incidents-agent** チャネルに `[L1完了] agent_id=xxx pattern=ToolTimeout user_impact=あり` を投稿

// runbook/mitigations.ts
// 本番障害の即時抑制ライブラリ
import { ConfigStore } from "./config-store";
 
interface MitigationContext {
  agentId: string;
  reason: string;
  operator: string; // 実行者の名前
  durationMinutes?: number;
}
 
export class AgentMitigator {
  constructor(private config: ConfigStore) {}
 
  // パターン A: Kill Switch — Agent を完全停止
  async killSwitch(ctx: MitigationContext): Promise<void> {
    await this.config.set(`agent:${ctx.agentId}:enabled`, false, {
      ttlMinutes: ctx.durationMinutes ?? 60,
      audit: { reason: ctx.reason, operator: ctx.operator },
    });
    console.log(`[KILL] ${ctx.agentId} stopped for ${ctx.durationMinutes ?? 60}min`);
    // 通知も忘れずに
    await this.notifySlack(`🚨 ${ctx.agentId} を ${ctx.durationMinutes ?? 60}分間停止しました (${ctx.operator}: ${ctx.reason})`);
  }
 
  // パターン B: フォールバック — 単純な決定論的処理に切り替え
  async fallbackToDeterministic(ctx: MitigationContext): Promise<void> {
    await this.config.set(`agent:${ctx.agentId}:mode`, "fallback", {
      ttlMinutes: ctx.durationMinutes ?? 30,
      audit: { reason: ctx.reason, operator: ctx.operator },
    });
    await this.notifySlack(`🔄 ${ctx.agentId} をフォールバックモードに切替`);
  }
 
  // パターン C: モデルダウングレード — 安定版に戻す
  async downgradeModel(ctx: MitigationContext, fallbackModel: string): Promise<void> {
    await this.config.set(`agent:${ctx.agentId}:model`, fallbackModel, {
      ttlMinutes: ctx.durationMinutes ?? 1440,
      audit: { reason: ctx.reason, operator: ctx.operator },
    });
    await this.notifySlack(`⬇️ ${ctx.agentId} を ${fallbackModel} にダウングレード`);
  }
 
  // パターン D: トラフィック制限 — 同時実行数を絞る
  async throttle(ctx: MitigationContext, maxConcurrent: number): Promise<void> {
    await this.config.set(`agent:${ctx.agentId}:max_concurrent`, maxConcurrent, {
      ttlMinutes: ctx.durationMinutes ?? 60,
      audit: { reason: ctx.reason, operator: ctx.operator },
    });
    await this.notifySlack(`🐌 ${ctx.agentId} の並列度を ${maxConcurrent} に絞りました`);
  }
 
  // パターン E: ループ強制脱出 — 進行中のループを中断
  async breakLoop(ctx: MitigationContext, runId: string): Promise<void> {
    await this.config.set(`run:${runId}:cancel`, true, {
      ttlMinutes: 5,
      audit: { reason: ctx.reason, operator: ctx.operator },
    });
    await this.notifySlack(`✂️ runId=${runId} のループを強制終了`);
  }
 
  private async notifySlack(message: string): Promise<void> {
    const webhookUrl = process.env.SLACK_INCIDENT_WEBHOOK_URL;
    if (!webhookUrl) {
      console.warn("SLACK_INCIDENT_WEBHOOK_URL not set, skipping notification");
      return;
    }
    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ text: message, channel: "#incidents-agent" }),
      });
    } catch (e) {
      console.error("Slack notify failed:", e);
      // 通知失敗で抑制処理を止めないこと（ここが重要）
    }
  }
}
 
// 使い方の例: Kill Switch を 1 行で打つ
// const mitigator = new AgentMitigator(configStore);
// await mitigator.killSwitch({ agentId: "code-reviewer", reason: "暴走検知", operator: "masaki" });

// runbook/postmortem-data.ts
// 障害ポストモーテム用のデータ収集スクリプト
// 使い方: node postmortem-data.ts <traceId>
 
import { AntigravityClient } from "@antigravity/sdk";
import { writeFileSync } from "node:fs";
 
interface PostmortemBundle {
  traceId: string;
  agentId: string;
  startedAt: string;
  endedAt: string;
  totalTokens: number;
  totalUsd: number;
  toolCalls: Array<{
    spanId: string;
    toolName: string;
    durationMs: number;
    success: boolean;
    inputHash: string;
    outputHash: string;
  }>;
  modelMessages: Array<{
    role: string;
    contentSummary: string; // 最初の 200 文字
    tokens: number;
  }>;
  evalScores: Array<{ evalType: string; score: number }>;
}
 
async function collectBundle(traceId: string): Promise<PostmortemBundle> {
  const client = new AntigravityClient({
    apiKey: process.env.ANTIGRAVITY_API_KEY!,
  });
 
  try {
    const trace = await client.traces.get(traceId);
    const spans = await client.traces.spans(traceId);
    const evals = await client.traces.evals(traceId);
 
    return {
      traceId,
      agentId: trace.agentId,
      startedAt: trace.startedAt,
      endedAt: trace.endedAt ?? new Date().toISOString(),
      totalTokens: trace.totalTokens,
      totalUsd: trace.totalUsd,
      toolCalls: spans
        .filter((s) => s.type === "tool_call")
        .map((s) => ({
          spanId: s.id,
          toolName: s.attributes.tool_name,
          durationMs: s.durationMs,
          success: s.status === "ok",
          inputHash: s.attributes.input_hash,
          outputHash: s.attributes.output_hash,
        })),
      modelMessages: spans
        .filter((s) => s.type === "model_message")
        .map((s) => ({
          role: s.attributes.role,
          contentSummary: (s.attributes.content ?? "").slice(0, 200),
          tokens: s.attributes.tokens ?? 0,
        })),
      evalScores: evals.map((e) => ({ evalType: e.type, score: e.score })),
    };
  } catch (e) {
    console.error(`Failed to collect bundle for ${traceId}:`, e);
    throw new Error(`Trace ${traceId} not found or API error`);
  }
}
 
// CLI エントリポイント
const traceId = process.argv[2];
if (!traceId) {
  console.error("Usage: node postmortem-data.ts <traceId>");
  process.exit(1);
}
 
collectBundle(traceId)
  .then((bundle) => {
    const filename = `postmortem-${traceId.slice(0, 8)}-${Date.now()}.json`;
    writeFileSync(filename, JSON.stringify(bundle, null, 2));
    console.log(`✅ Saved bundle: ${filename}`);
    console.log(`   Tool calls: ${bundle.toolCalls.length}`);
    console.log(`   Token cost: $${bundle.totalUsd.toFixed(2)}`);
    console.log(`   Failures: ${bundle.toolCalls.filter((c) => !c.success).length}`);
  })
  .catch((e) => {
    console.error("❌ Bundle collection failed:", e.message);
    process.exit(1);
  });

✅ Saved bundle: postmortem-abc12345-1714356123456.json
   Tool calls: 247
   Token cost: $18.42
   Failures: 12