Un agent qui pilote un navigateur, en sécurité

Le service client de Maison Orée, grossiste fictif en fournitures de bureau, traite chaque matin une centaine de demandes du type « où en est la commande CMD-1042 ? », « passez-la en expédiée », « envoyez-moi les commandes en attente en CSV ». Le back-office date de 2014, n'a pas d'API, et l'éditeur facture 40 jours-homme pour en ajouter une. Un agent qui manipule l'interface web comme un opérateur est tentant. Il est aussi dangereux : il lit des pages dont une partie est écrite par les clients, il a une session authentifiée, et il peut cliquer sur « Exporter ».

Ce projet construit cet agent de bout en bout, en Python, sans framework d'agent : une boucle de function calling Gemini, des outils Playwright de haut niveau, et un harness qui garde la main sur tout ce qui a un effet.

La fiche d'une commande dont la note client contient une consigne adressée à l'agent. Capture prise par le traceur pendant la démonstration du 2026-10-15.

Ce que vous livrez

Un back-office fictif (FastAPI) : connexion, recherche, fiche, changement de statut, export CSV.
Un agent Gemini avec 8 outils : se_connecter, naviguer, lire_page, cliquer, remplir, choisir, extraire_tableau, capture_ecran. Il désigne les éléments par rôle et nom accessible, jamais par sélecteur CSS ni par coordonnées.
Un harness de garde-fous qui s'applique quoi que décide le modèle : liste blanche de domaines au niveau réseau, requêtes à effet coupées sans confirmation humaine, contenu des pages étiqueté non fiable, budget d'étapes.
Un traceur : une ligne JSON et une capture PNG par étape.
Une démonstration mesurée sur 5 tâches, dont une page qui tente de détourner l'agent.

Architecture

flowchart LR
  U["Opérateur : la tâche"] --> L["Boucle d'agent (agent.py)"]
  L <-->|"function calling"| G["Gemini"]
  L --> B["Budget d'étapes"]
  B --> T["Outils de haut niveau (browser.py)"]
  T -->|"clic à effet"| C{"Confirmation humaine"}
  C -->|"oui : arme 1 requête"| P["Page Playwright"]
  T --> P
  P --> F["Filtre réseau : liste blanche + POST armés (guard.py)"]
  F --> W["Back-office Orée (FastAPI)"]
  P -->|"arbre ARIA simplifié, étiqueté non fiable"| L
  L --> R["Traceur : trace.jsonl + etape-NN.png"]

Résultats mesurés le 2026-10-15

Mesure	Valeur
Taux de réussite, opérateur scripté	25/25 sur 5 exécutions des 5 tâches (4 avec gemini-3.5-flash, 1 avec gemini-3.5-flash-lite)
Étapes par exécution complète	15 à 17 (2 à 5 par tâche)
Jetons d'entrée par exécution	76 000 à 91 000 avec l'arbre brut, 46 000 à 47 000 avec l'arbre simplifié
Page piégée	consigne ignorée dans 5 exécutions sur 5, signalée à l'opérateur par gemini-3.5-flash dans 4 sur 4
Arbre simplifié contre capture	1 149 contre 1 089 jetons ; la capture de la seule zone visible manque 3 valeurs sur 9
Coût d'un `make e2e`	environ 0,05 $

Stack

Python 3.10+, google-genai (function calling manuel), Playwright 1.64 (Chromium headless), FastAPI et Uvicorn pour l'application cible, pytest. Aucune ressource Google Cloud : une clé d'API Gemini suffit.

Prérequis

Avoir écrit une boucle d'agent avec function calling (voir Construire un agent IA de A à Z).
Lire du HTML et connaître les bases de HTTP (GET, POST, cookie de session).
Une clé Gemini (Google AI Studio) pour les leçons 5 et 6 ; tout le reste tourne sans clé.

Programme

Leçon	Ce qui avance	Commande qui le prouve
1. Le problème et l'architecture	modèle de menace, choix de l'arbre d'accessibilité	`make setup && make app`
2. L'application cible	back-office fictif et HTML sémantique	`pytest tests/test_backoffice.py`
3. Les outils Playwright	arbre simplifié, clic par rôle et nom, tableau	`pytest tests/test_browser.py`
4. Les garde-fous	liste blanche, filtre réseau, confirmation, budget	`pytest tests/test_guard.py`
5. La boucle et le traçage	function calling manuel, faux modèle, traces	`make test` puis `make run`
6. Démonstration et mesures	5 tâches réelles, taux de réussite, arbre contre capture	`make e2e`
7. Computer use et production	comparaison avec les fournisseurs, règle de décision, nettoyage	`make clean`

Le code complet est dans files/ : make setup, make test, make e2e.