Table of Contents

🇬🇧 English version

L'outil firefox

Voir aussi : Inventaire des outils · Référence de configuration · RaggableTree · Limitations connues · Retour à l'index

firefox donne un navigateur à un agent : le Firefox installé sur la machine, piloté par WebDriver BiDi sur un WebSocket. Aucun binaire de pilote, aucun paquet d'éditeur, aucun téléchargement de navigateur. L'agent ouvre une page, la lit comme un plan de sections, de liens et de contrôles, clique, saisit, presse des touches, cherche dans la page par le sens, exécute un script et enregistre une capture d'écran. Les pages exécutent leur JavaScript : ce que web_scrape ne voit pas, firefox le voit.

  • Un navigateur par exĂ©cution d'agent. Firefox dĂ©marre Ă  la première action de l'exĂ©cution, garde ses pages d'une action Ă  la suivante et se ferme avec l'exĂ©cution. Des agents qui s'exĂ©cutent cĂ´te Ă  cĂ´te ont chacun leur navigateur, ou en partagent un avec des onglets Ă  eux quand l'hĂ´te le dit (SharedInstance). Hors de toute exĂ©cution, une action reçoit un navigateur Ă  elle, fermĂ© juste après. Un hĂ´te qui veut que le navigateur survive Ă  l'exĂ©cution le garde avec Lifetime: host (ci-dessous).
  • Un profil jetable par dĂ©faut : un dossier neuf, supprimĂ© Ă  la fermeture du navigateur. L'hĂ´te peut dĂ©marrer le navigateur sur un profil du Firefox installĂ© sur la machine Ă  la place, et nommer les profils qu'un agent peut demander et ceux qu'aucun navigateur n'utilise jamais (Profils).
  • La fenĂŞtre est visible par dĂ©faut — l'opĂ©rateur voit ce que fait l'agent. Headless la cache ; une machine sans affichage dĂ©marre de toute façon sans fenĂŞtre, avec un avertissement dans le journal.
  • Chaque adresse est vĂ©rifiĂ©e par la politique d'URL de l'hĂ´te (IUrlValidator), ou par la garde fermĂ©e par dĂ©faut quand l'hĂ´te n'en enregistre aucune : les adresses privĂ©es et de boucle locale sont refusĂ©es avant que le navigateur ne dĂ©marre. L'adresse oĂą une page arrive après un clic, une touche ou un script est vĂ©rifiĂ©e de la mĂŞme façon : une adresse refusĂ©e est quittĂ©e pour une page vide, et la rĂ©ponse le dit.
  • La page est un graphe. Un snapshot projette la page dans un RaggableTree Ă  elle — jamais l'index de code de l'hĂ´te — et chaque nĹ“ud porte un identifiant que les actions suivantes prennent.

Le donner Ă  un agent

agents:
  researcher:
    role: "Researcher"
    goal: "Trouver et résumer des sources sur le web"
    tools: [firefox]

Firefox doit être installé sur l'hôte (firefox sur le PATH, ou ExecutablePath). L'outil est enregistré par AddOrkeonWebTools(), que chaque hôte livré appelle ; un hôte bibliothèque a aussi besoin d'un IFileSystemService (la capture d'écran passe par lui) et, pour search, de AddOrkeonEphemeralSearch() avec un fournisseur d'embeddings configuré — sans lui, toutes les autres actions fonctionnent et search le dit.

Les actions

Un outil, un argument action. La classe de permission d'un appel dépend de l'action : les actions de lecture passent en mode plan, screenshot est une édition, les autres sont des exécutions.

Action Arguments Classe Ce qu'elle fait
navigate url Read Ouvre une page http ou https et rend son plan
back — Read Une page en arrière dans l'historique de l'onglet
snapshot max_nodes, offset Read Le plan de la page affichée : sections, liens, contrôles
read node_id, offset Read Le texte de la page, ou d'un nœud et des nœuds qu'il contient
find kind, name, node_id Read Les nœuds d'une sorte (section, link, control), dont le nom contient un texte, sous un nœud
search query, max_nodes Read Les sections les plus proches en sens d'une question (RAG)
screenshot save_to_path Edit Écrit le PNG de la partie visible de la page à un chemin virtuel
click node_id Execute Clique un élément, amené à l'écran d'abord
type node_id, text Execute Remplace ce qu'un champ contient ; un saut de ligne presse Entrée
press key Execute Une touche ou un accord sur l'élément qui a le focus : Enter, Tab, Control+a
evaluate script Execute Une expression JavaScript exécutée dans la page ; une promesse est attendue
tabs — Read Les onglets de l'agent, dans l'ordre d'ouverture : id, url, title, current
new_tab url Read Ouvre un onglet, sur url quand elle est donnée, et le pilote désormais
switch_tab tab Read Pilote désormais l'onglet tab (t1, t2), affiché devant les autres
close_tab tab Execute Ferme un onglet, le courant par défaut ; le dernier onglet n'est jamais fermé (close est là pour ça)
close profile Execute Ferme le navigateur de l'exécution ; l'action suivante en démarre un nouveau. Hors de toute exécution, sous Lifetime: host, ferme le navigateur de l'hôte du profil profile, celui du profil par défaut sans (profile ne compte que là)

Chaque réponse porte l'action, l'url et le title de la page affichée, tab, la poignée de l'onglet que les actions pilotent désormais, et profile, celui avec lequel le navigateur tourne. dialogs l'accompagne quand la page a ouvert des boîtes alert, confirm ou prompt pendant l'action : ce qu'elles disaient, fermées pour que la page ne se fige jamais (une question beforeunload est acceptée : partir était ce que l'agent demandait). Les listes qu'une action n'a pas produites - nodes, hits, tabs - sont absentes de sa réponse, jamais vides.

Chaque action accepte un profile facultatif : il compte à la première action d'une exécution, quand le navigateur démarre ; un navigateur déjà ouvert garde son profil, et une action qui en nomme un autre est refusée jusqu'à close. La règle tient sous Lifetime: host : l'exécution est liée au profil de sa première action, et une action sans profile va à ce navigateur, quel que soit le profil par défaut de l'hôte.

Onglets

Un agent pilote un onglet à la fois et ne voit que les siens : ceux qu'il a ouverts avec new_tab, et ceux qu'un lien d'une de ses pages a ouverts — l'agent suit un tel onglet, comme le feraient les yeux d'un utilisateur. Un onglet ouvert par l'utilisateur ou par un autre agent n'est jamais listé, lu ni fermé. close_tab sur l'onglet piloté ramène l'agent au précédent.

Identifiants de nœuds

snapshot, find et search nomment les nœuds p<lecture>#<index> — p2#7 est l'élément 7 de la deuxième lecture d'une page. Les identifiants restent valides tant que la page ne change pas : saisir dans un champ puis cliquer un bouton ne demande pas de nouveau snapshot. Après une navigation, ou quand une action a changé la page, un ancien identifiant est refusé avec la raison, et l'agent rappelle snapshot. Une liste est coupée à MaxNodes (Orkeon:Tools:Firefox, 40 par défaut, 200 au plus) : truncated et total_nodes le disent, et offset lit la suite.

Un enchaînement typique

navigate  url=https://example.org/docs           → plan : p1#0 section "Getting started" …
search    query="comment configure-t-on une crew ?" → hits : p1#5 (0.82) "Configuration" …
read      node_id=p1#5                           → le texte de cette section
find      kind=control name=search               → p1#12 textbox "Search"
type      node_id=p1#12 text="crew yaml\n"       → la page après Entrée, p2#…
click     node_id=p2#3                           → la page que le lien a ouverte
screenshot save_to_path=/output/docs.png         → saved_path

search envoie le texte de chaque section de la page au fournisseur d'embeddings comme source en ligne d'une collection éphémère nommée d'après la page (préfixe firefox) : une page lue deux fois n'est embarquée qu'une fois. Chaque résultat nomme le nœud de la section, et l'agent lit ou clique ce que la recherche a trouvé : c'est le lien entre le sous-système RAG et le graphe de la page.

Ce qui ne passe jamais par l'outil

  • Un secret : le texte de type est un argument d'outil, que le modèle Ă©crit et que la transcription garde. Une page qui demande un mot de passe est une page que l'agent ne doit pas remplir.
  • Une page hors de la politique : les sous-ressources qu'une page charge (images, scripts, cadres) sont rĂ©cupĂ©rĂ©es par Firefox lui-mĂŞme et ne sont pas vĂ©rifiĂ©es par la politique d'URL ; seules les pages que l'onglet affiche le sont. Gardez le navigateur sur un rĂ©seau isolĂ© quand la politique compte.
  • Le texte d'une page n'est pas filtrĂ© contre l'injection de consignes : un agent le lit comme il lit tout rĂ©sultat d'outil. Le Guardian de l'hĂ´te s'applique Ă  ce que l'agent dit et fait ensuite.

Profils

Un navigateur démarre sur l'un de trois genres de profil, et le profile de la réponse dit lequel :

  • disposable, par dĂ©faut : un dossier neuf sous ProfileRoot, avec les prĂ©fĂ©rences d'un premier dĂ©marrage silencieux, supprimĂ© Ă  la fermeture du navigateur. Rien ne survit au navigateur.
  • Un profil du Firefox installĂ© sur l'hĂ´te, par le nom que profiles.ini lui donne (about:profiles les montre) : utilisĂ© sur place, avec ses cookies, ses sessions, ses extensions et son historique, et jamais supprimĂ©. L'agent voit ce que voit l'utilisateur du profil, connectĂ© lĂ  oĂą il l'est : donnez Ă  un agent un profil fait pour lui, jamais celui de l'opĂ©rateur. Un profil qu'un autre Firefox tient ouvert est refusĂ© : fermez ce Firefox, ou prenez un autre profil.
  • Un dossier de profil, par son chemin : la mĂŞme chose, pour un profil que profiles.ini ne liste pas.

Qui choisit : Orkeon:Tools:Firefox:Profile nomme le profil sur lequel un navigateur démarre quand l'agent n'en nomme aucun. Un agent peut nommer disposable, ce profil, ou l'un de AllowedProfiles — rien d'autre. DeniedProfiles l'emporte sur tous : un profil qui y figure ne démarre aucun navigateur, qui que ce soit qui le demande. Les noms sont comparés sans égard à la casse.

"Orkeon": { "Tools": { "Firefox": {
  "Profile": "agent-work",
  "AllowedProfiles": ["agent-reviews"],
  "DeniedProfiles": ["default", "default-release"]
} } }

Un navigateur pour plusieurs exécutions

Par défaut, chaque exécution d'agent a son propre navigateur. SharedInstance: true donne à l'hôte un navigateur par profil, partagé entre les exécutions qui l'utilisent : chacune y pilote ses propres onglets, ne voit qu'eux, et le navigateur se ferme quand la dernière exécution le quitte — sauf si Lifetime: host le garde (ci-dessous) — ou quand l'hôte s'arrête. close ferme les onglets de l'exécution qui l'appelle, pas le navigateur que les autres partagent. C'est un profil nommé qui rend le partage utile : plusieurs agents sur une même session connectée, côte à côte.

Un navigateur qui survit à l'exécution

Lifetime: host garde le navigateur une fois l'exécution terminée : sa fenêtre, ses onglets et son profil — le jetable compris — restent comme la dernière action les a laissés, et l'exécution suivante, ou une action hors de toute exécution, les retrouve. Un navigateur par profil : une action nomme avec profile le navigateur qu'elle vise, ou reçoit celui du profil par défaut de l'hôte. Le navigateur se ferme quand un agent appelle close, quand l'utilisateur ferme la fenêtre, ou quand l'hôte s'arrête ; le dossier jetable part avec lui. Une action qui échoue ou est annulée le laisse ouvert. Un navigateur que l'utilisateur a fermé, ou qui est mort, est remarqué à l'action suivante, qui en démarre un nouveau. La session aussi est celle de l'hôte : tabs liste les onglets que les exécutions précédentes ont laissés, et l'exécution suivante pilote celui où la dernière s'est arrêtée.

Des exécutions qui se chevauchent sur un même profil mettent leurs actions en file sur son navigateur, une à la fois : le navigateur de l'hôte est partagé par toutes les exécutions de l'hôte, ce qui convient à une console à un seul opérateur — un agent qui reprend là où le précédent s'est arrêté, une page que l'utilisateur lit entre deux exécutions — pas à des agents qui naviguent côte à côte. Pour ceux-là, SharedInstance reste la réponse, et les deux se combinent : chaque exécution ne voit toujours que ses propres onglets, qui se ferment avec elle, et la fenêtre reste ouverte pour la suivante sur un onglet vierge ; si l'utilisateur ferme cet onglet, l'exécution suivante en ouvre un à elle.

{ "Orkeon": { "Tools": { "Firefox": { "Lifetime": "host" } } } }

Dans une exécution, close ferme le navigateur de l'exécution, comme toujours — ou, quand l'exécution n'en a pas encore utilisé, le navigateur de l'hôte du profil nommé, celui du profil par défaut sans ; hors de toute exécution — une console, un script — close ferme le navigateur de l'hôte de la même façon. Chaque fois qu'un profil jetable est créé, l'outil supprime d'abord, sous ProfileRoot, les dossiers jetables de plus de dix minutes qu'aucun Firefox ne tient : ce qu'un hôte tué avec ses navigateurs a laissé derrière lui.

Réglages

Orkeon:Tools:Firefox — voir la référence de configuration : ExecutablePath, Headless, Profile, AllowedProfiles, DeniedProfiles, SharedInstance, Lifetime, ProfileRoot, StartupTimeoutSeconds, CommandTimeoutSeconds, MaxNodes, MaxTextLength. Quand Firefox est un snap, la racine de profil par défaut est ~/snap/firefox/common/orkeon/profiles : un snap ne lit pas le dossier temporaire du système.

Un navigateur qui a ouvert son protocole distant mais laisse la première commande, session.new, sans réponse pendant CommandTimeoutSeconds est tué, son profil supprimé s'il est jetable, et redémarré une fois, avec un avertissement dans le journal ; un second silence fait échouer le démarrage avec une erreur qui dit que Firefox a été redémarré.