Claude × Playwright のブラウザエージェントが「成功したつもり」で失敗するとき — 操作を検証し UI の変化に先回りする実装メモ

// 操作の提案はモデル、合否は検証関数。役割をはっきり分ける
interface ActionProposal {
  type: 'click' | 'fill' | 'navigate';
  selector?: string;
  value?: string;
  url?: string;
  // モデルが「この操作で何が起きるはず」と宣言する事後条件
  expectedEffect: string;
}
 
interface VerifiedStep {
  proposal: ActionProposal;
  reasoning: string;
  verified: boolean;       // 検証関数の判定（モデルの自己申告ではない）
  evidence: string;        // 合否の根拠（観測した事実）
}

// src/agent/verify.ts
import { Page } from 'playwright';
 
interface VerificationResult {
  verified: boolean;
  evidence: string;
}
 
// 目標に固有の検証を、観測可能な事実で行う
export async function verifyCartAdded(
  page: Page,
  expectedCount: number
): Promise<VerificationResult> {
  // 1. UI のテキストではなく、状態を持つ要素を狙う
  const badge = page.locator('[data-testid="cart-count"]');
  // 2. 非同期更新を「待つ」。撮影タイミングのズレをここで吸収する
  try {
    await badge.waitFor({ state: 'visible', timeout: 5000 });
  } catch {
    return { verified: false, evidence: 'cart-count バッジが現れませんでした' };
  }
  const text = (await badge.textContent())?.trim() ?? '';
  const actual = parseInt(text, 10);
  // 3. 期待した状態と一致するかで合否を出す
  if (Number.isNaN(actual)) {
    return { verified: false, evidence: `cart-count が数値ではありません: "${text}"` };
  }
  return actual >= expectedCount
    ? { verified: true, evidence: `cart-count=${actual}（期待 ${expectedCount} 以上）` }
    : { verified: false, evidence: `cart-count=${actual}（期待 ${expectedCount} に未達）` };
}

// src/agent/step.ts
import Anthropic from '@anthropic-ai/sdk';
import { Page } from 'playwright';
import { VerificationResult } from './verify';
 
type Verifier = (page: Page) => Promise<VerificationResult>;
 
export async function runVerifiedStep(
  client: Anthropic,
  page: Page,
  proposal: ActionProposal,
  verify: Verifier,
  history: Anthropic.MessageParam[]
): Promise<VerifiedStep> {
  // 1. 提案された操作を実行
  await applyAction(page, proposal);
 
  // 2. 目標に固有の検証（モデルの自己申告ではない）
  const result = await verify(page);
 
  // 3. 落ちたら、観測した事実をモデルに差し戻す
  if (!result.verified) {
    history.push({
      role: 'user',
      content:
        `直前の操作（${proposal.type} ${proposal.selector ?? ''}）は` +
        `期待した効果「${proposal.expectedEffect}」を生みませんでした。` +
        `観測した事実: ${result.evidence}。別の方法を提案してください。`,
    });
  }
 
  return {
    proposal,
    reasoning: proposal.expectedEffect,
    verified: result.verified,
    evidence: result.evidence,
  };
}
 
async function applyAction(page: Page, a: ActionProposal): Promise<void> {
  if (a.type === 'click' && a.selector) await page.click(a.selector, { timeout: 8000 });
  else if (a.type === 'fill' && a.selector) await page.fill(a.selector, a.value ?? '');
  else if (a.type === 'navigate' && a.url) await page.goto(a.url, { waitUntil: 'networkidle' });
}

const tools: Anthropic.Tool[] = [
  {
    name: 'execute_action',
    description: 'ブラウザ操作を実行する。expectedEffect に状態で測れる事後条件を必ず書く',
    input_schema: {
      type: 'object',
      properties: {
        type: { type: 'string', enum: ['click', 'fill', 'navigate'] },
        selector: { type: 'string' },
        value: { type: 'string' },
        expectedEffect: {
          type: 'string',
          description: '例: "cart-count が 1 増える"（見た目ではなく状態で書く）',
        },
      },
      required: ['type', 'expectedEffect'],
    },
  },
  {
    name: 'observe_state',
    description: '事後条件の確認に使う観測（要素の件数・テキスト・存在・現在URL）',
    input_schema: {
      type: 'object',
      properties: {
        selector: { type: 'string' },
        property: { type: 'string', enum: ['count', 'text', 'exists', 'url'] },
      },
      required: ['property'],
    },
  },
];
 
const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1536,
  tools,
  messages: history,
});

const system: Anthropic.TextBlockParam[] = [
  {
    type: 'text',
    text:
      'あなたはブラウザを操作するエージェントです。' +
      '各操作には状態で測れる expectedEffect を必ず添え、' +
      '検証に落ちたら同じ操作を繰り返さず別経路を試してください。' +
      '目標達成を自己申告で断定せず、観測された事実に委ねてください。',
    cache_control: { type: 'ephemeral' }, // 現行 SDK は messages.create に直接指定できる
  },
];
 
const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1536,
  system,
  messages: recentHistory,
});

// src/monitor/drift.ts
import { chromium } from 'playwright';
 
interface Anchor { url: string; selector: string; label: string; }
 
// 各サイトの「検証に使っている観測点」をアンカーとして登録
const ANCHORS: Anchor[] = [
  { url: 'https://example.com/product/1', selector: '[data-testid="add-to-cart"]', label: '追加ボタン' },
  { url: 'https://example.com/cart', selector: '[data-testid="cart-count"]', label: 'カート件数バッジ' },
];
 
export async function checkDrift(): Promise<{ ok: boolean; missing: string[] }> {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();
  const missing: string[] = [];
  for (const a of ANCHORS) {
    await page.goto(a.url, { waitUntil: 'domcontentloaded' });
    const exists = (await page.locator(a.selector).count()) > 0;
    if (!exists) missing.push(`${a.label}（${a.selector}）`);
  }
  await browser.close();
  return { ok: missing.length === 0, missing };
}

// src/agent/breaker.ts
export class VerificationBreaker {
  private window: boolean[] = [];
  constructor(private size = 50, private maxFailRate = 0.2) {}
 
  record(verified: boolean): void {
    this.window.push(verified);
    if (this.window.length > this.size) this.window.shift();
  }
 
  shouldHalt(): boolean {
    if (this.window.length < this.size) return false;
    const fails = this.window.filter((v) => !v).length;
    return fails / this.window.length > this.maxFailRate;
  }
}