📖 Manuel

Browser Agent Builder

1. Choisir le framework

Décision : Playwright par défaut sur tout nouveau projet. Puppeteer si contrainte Chrome-only ou lib existante. Selenium uniquement legacy/Java.

# Installation Playwright (Node.js)
npm init -y && npm i -D playwright
npx playwright install chromium   # ou --with-deps pour CI

# Python
pip install playwright && playwright install chromium

2. Architecture de l'agent

┌───────────────────────────────────────────────┐
│                  Orchestrateur                │
│  (LLM : planifie, décide, retry si échec)     │
└────────┬──────────────┬────────────┬──────────┘
         │              │            │
    Navigation      Extraction   Mémoire/État
  (goto/click/fill) (DOM/vision) (cookies, historique)

Composants minimaux :

• Navigator : wraps page.goto / click / fill / keyboard
• Extractor : page.$eval, locator, screenshot → LLM
• SessionStore : persist cookies + localStorage sur disque
• DecisionLoop : LLM reçoit DOM/screenshot, émet actions structurées

3. Implémenter l'interaction DOM robuste

// Sélecteurs stables — ordre de préférence
page.getByRole('button', { name: 'Valider' })      // 1er choix
page.getByTestId('submit-btn')                      // 2e choix
page.getByLabel('Email')                            // 3e choix
page.locator('[data-id="checkout"]')                // 4e choix
// Jamais : page.locator('.css-1a2b3c')             // ❌ généré dynamiquement

// Auto-wait + retry inclus dans Playwright — ne pas ajouter de sleep manuel
await page.getByRole('button', { name: 'Valider' }).click()

// Shadow DOM
const shadow = page.locator('my-component').locator('pierce=button')

// iFrame
const frame = page.frameLocator('#checkout-iframe')
await frame.getByLabel('Numéro carte').fill('4111111111111111')

4. Intégrer la vision LLM (multimodal)

Utiliser les screenshots quand le DOM est insuffisant (canvas, interfaces riches, CAPTCHAs visuels lisibles).

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()

async function describePageAndAct(page: Page): Promise<string> {
  const screenshot = await page.screenshot({ type: 'png' })
  const b64 = screenshot.toString('base64')

  const response = await client.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 512,
    messages: [{
      role: 'user',
      content: [
        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: b64 } },
        { type: 'text', text: 'Quelle action faut-il effectuer ensuite pour compléter le formulaire ?' }
      ]
    }]
  })
  return (response.content[0] as any).text
}

Règle : vision = fallback coûteux — toujours tenter le sélecteur DOM d'abord.

5. Gestion de session et authentification

// Sauvegarder l'état de session après login
await page.context().storageState({ path: 'session.json' })

// Réutiliser à la session suivante
const context = await browser.newContext({
  storageState: 'session.json'
})

// TOTP (2FA) avec otplib
import { totp } from 'otplib'
const code = totp.generate(process.env.TOTP_SECRET!)
await page.getByLabel('Code OTP').fill(code)

6. Anti-détection — périmètre légal uniquement

// Playwright : stealth via playwright-extra
import { chromium } from 'playwright-extra'
import StealthPlugin from 'puppeteer-extra-plugin-stealth'
chromium.use(StealthPlugin())

// Profil réaliste
const context = await chromium.launchPersistentContext('', {
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
  viewport: { width: 1366, height: 768 },
  locale: 'fr-FR',
  timezoneId: 'Africa/Tunis'
})

// Délais humains : randomiser, ne jamais fixer
const delay = (ms: number) => new Promise(r => setTimeout(r, ms))
await delay(500 + Math.random() * 1000)

7. Orchestration multi-pages et error recovery

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await fn()
    } catch (err) {
      if (i === maxAttempts - 1) throw err
      await page.screenshot({ path: `error_attempt_${i}.png` })
      await page.reload()
      await delay(2000)
    }
  }
  throw new Error('unreachable')
}

// State machine simple
type Step = 'login' | 'search' | 'extract' | 'done'
let step: Step = 'login'
while (step !== 'done') {
  switch (step) {
    case 'login':  await doLogin();  step = 'search'; break
    case 'search': await doSearch(); step = 'extract'; break
    case 'extract': await extract(); step = 'done'; break
  }
}

8. Tests et monitoring

// Playwright Test — test E2E du workflow critique
import { test, expect } from '@playwright/test'

test('workflow checkout complet', async ({ page }) => {
  await page.goto('https://shop.example.com')
  await page.getByRole('button', { name: 'Ajouter au panier' }).click()
  await expect(page.getByText('1 article')).toBeVisible()
})

# Lancer en CI (headless, reporters JUnit)
npx playwright test --reporter=junit --output=results.xml

Monitoring : alerter si taux d'échec > 5 % sur 1 h. Versionner les snapshots DOM avec des tests de régression sur les sélecteurs clés.

Anti-patterns / Pièges

• page.waitForTimeout(3000) — ne jamais utiliser de sleep fixe ; utiliser waitForSelector ou les auto-waits Playwright.
• Sélecteurs sur classes CSS générées (css-1x2y3z) — ils changent à chaque build ; toujours utiliser role, label, data-testid.
• Pas de gestion d'erreur sur les navigations — un réseau lent ou une redirection inattendue fait planter silencieusement. Toujours try/catch + screenshot.
• Scraper sans robots.txt check — vérifier GET /robots.txt avant d'automatiser et respecter les Crawl-delay.
• Screenshots en fin de workflow uniquement — capturer à chaque étape critique (avant/après form submit, après login, à chaque page nouvelle).
• Ouvrir un nouveau contexte pour chaque requête — coûteux ; réutiliser BrowserContext et changer seulement les cookies/state.
• Stocker des credentials en clair dans le code — utiliser .env + dotenv, ne jamais commit session.json.

Bonnes pratiques 2026

• Playwright MCP (@playwright/mcp) permet à Claude d'appeler directement les outils de navigation — idéal pour les agents LLM-driven sans coder les sélecteurs.
• Préférer les locator chainables aux $ / $$ (deprecated dans les nouvelles versions).
• Pour le scraping à grande échelle : Crawlee (Node) ou Scrapy + Playwright (Python) > code custom.
• Toujours isoler la logique de navigation de la logique métier pour faciliter les changements de sélecteurs sans modifier l'orchestrateur.