Outil d'utilisation du navigateur

Le « browser use tool » (outil d'utilisation du navigateur) permet à Claude de naviguer, de lire et d'interagir avec des pages web dans un navigateur que votre application exécute. Il travaille avec la page à la fois par sa structure (l'« accessibility tree » (arbre d'accessibilité), les éléments, les formulaires et les onglets) et par les pixels (captures d'écran et coordonnées du viewport), alors que l'outil d'utilisation de l'ordinateur travaille avec un bureau entier uniquement au moyen de captures d'écran et de coordonnées. Il s'agit d'un « client toolset » (ensemble d'outils client) défini par Anthropic (ensemble d'outils client) : une seule entrée browser_toolset_20260801 dans votre tableau tools donne à Claude 27 outils membres par défaut, tels que navigate, read_page, left_click et screenshot, plus quatre autres (javascript_exec, file_upload, read_console et read_network) lorsque vous les activez. Votre application exécute chaque appel avec sa propre automatisation de navigateur ; rien ne s'exécute du côté d'Anthropic. Il n'est actuellement pas disponible dans Claude Managed Agents. Cette page emploie « votre application » pour désigner la boucle d'agent qui appelle l'API Messages et « votre exécuteur » pour la partie de celle-ci qui pilote le navigateur et produit les résultats d'outils.

Choisissez l'utilisation du navigateur plutôt que l'utilisation de l'ordinateur lorsque la tâche reste à l'intérieur de pages web : Claude peut lire la structure d'une page, agir sur un élément par référence en plus de par coordonnée, définir directement les valeurs de formulaire et travailler sur plusieurs onglets, et vous n'avez pas besoin d'exécuter un bureau. Si Claude a seulement besoin de lire des pages vers lesquelles vous pouvez le diriger, ou de trouver des sources sur le web, l'outil web fetch et l'outil web search sont encore plus légers, car ce sont des outils serveur que l'API exécute pour vous sans navigateur à faire fonctionner. Choisissez plutôt l'utilisation du navigateur lorsque les pages construisent leur contenu avec JavaScript ou que la tâche implique d'agir sur la page plutôt que de seulement la lire.

Avec l'utilisation du navigateur, Claude lit et agit sur des pages web en direct, de sorte que tout ce qu'une page fournit est une entrée non fiable et que les actions entreprises par Claude peuvent avoir des effets réels. Consultez les Considérations de sécurité avant de déployer.



Démarrage rapide

L'outil d'utilisation du navigateur est disponible sur l'API Claude sans en-tête bêta : ajoutez une entrée de type browser_toolset_20260801, sans name, au tableau tools d'une requête de l'API Messages.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    tools=[{"type": "browser_toolset_20260801"}],
    messages=[
        {
            "role": "user",
            "content": "Open example.com/docs and tell me how to get started.",
        }
    ],
)
print(response)

La première réponse de Claude se termine par stop_reason: "tool_use" et contient un ou plusieurs blocs tool_use membres, chacun nommant un outil membre dans name et portant "toolset_name": "browser" :

{
  "id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the documentation and read the page to find the getting-started instructions."
    },
    {
      "type": "tool_use",
      "id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "name": "navigate",
      "toolset_name": "browser",
      "input": { "url": "https://example.com/docs" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "name": "read_page",
      "toolset_name": "browser",
      "input": { "filter": "interactive" }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Votre exécuteur exécute navigate, puis read_page, et votre application renvoie un tool_result par bloc dans sa requête suivante, en répétant toolset_name sur chacun. Le résultat de navigate indique l'onglet qu'il a chargé dans un bloc browser_state ; le résultat de read_page est du texte dans lequel chaque élément porte une référence :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Navigated to https://example.com/docs" },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            }
          ]
        }
      ]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "toolset_name": "browser",
      "content": [
        {
          "type": "text",
          "text": "link \"Documentation\" [ref_1]\nlink \"Getting started\" [ref_2]\ntextbox \"Search docs\" [ref_3]\nbutton \"Search\" [ref_4]\nlink \"Pricing\" [ref_5]"
        }
      ]
    }
  ]
}

Claude détient maintenant des références sur lesquelles il peut agir, de sorte que son tour suivant peut cliquer sur ref_2 pour ouvrir la page de démarrage, sans avoir besoin de localiser d'abord le lien dans une capture d'écran.



Fonctionnement de l'utilisation du navigateur

L'utilisation du navigateur s'exécute sous forme d'« agent loop » (boucle d'agent) : Claude renvoie des appels d'outils membres, votre exécuteur les exécute sur le navigateur, et vous renvoyez les résultats jusqu'à ce que Claude réponde en texte.

Voici un squelette de l'étape d'appel d'outils de cette boucle, en deux parties. D'abord, des gestionnaires de membres factices tiennent lieu de votre automatisation de navigateur. Cinq membres (navigate, read_page, left_click, type et screenshot) renvoient le texte, ou pour screenshot le bloc image, qui devient le contenu du résultat, et le répartiteur lève une erreur pour tout membre qu'il n'implémente pas.

# Données d'image fictives ; un exécuteur réel capture la fenêtre d'affichage et renvoie les octets PNG
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="


def navigate(url):
    return f"navigated to {url}"


def read_page():
    return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]'


def click(target):
    # Une cible est une référence d'élément issue de read_page ou find, ou une coordonnée de la fenêtre d'affichage
    if target["type"] == "ref":
        return f"clicked {target['ref']}"
    return f"clicked at ({target['x']}, {target['y']})"


def type_text(text):
    return f"typed: {text}"


def capture_screenshot() -> list[ImageBlockParam]:
    # screenshot répond avec un bloc image plutôt que du texte : renvoyer la liste de contenu du résultat
    return [
        {
            "type": "image",
            "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
        }
    ]


def handle_browser_action(name, tool_input):
    if name == "navigate":
        return navigate(tool_input["url"])
    elif name == "read_page":
        return read_page()
    elif name == "left_click":
        return click(tool_input["target"])
    elif name == "type":
        return type_text(tool_input["text"])
    elif name == "screenshot":
        return capture_screenshot()
    # Gérer les autres actions selon les besoins
    raise ValueError(f"Unknown or unimplemented member: {name}")

La seconde partie exécute un lot dans l'ordre, répartit chaque bloc vers ces gestionnaires, répète toolset_name sur chaque résultat et applique la règle d'arrêt décrite dans Actions par lot, en transformant une erreur de gestionnaire en résultat d'erreur. La boucle d'échantillonnage qui l'appelle est celle présentée dans Comprendre la boucle d'agent, avec l'ensemble d'outils du navigateur dans tools.

NOT_EXECUTED = "Not executed: an earlier action in this turn failed."


def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
    """
    Run the browser actions in Claude's response in order and answer each
    one. After the first failure the rest are skipped, because Claude planned
    them assuming the earlier actions succeeded.
    """
    tool_results: list[ToolResultBlockParam] = []
    failed = False
    for block in response.content:
        # Seul le jeu d'outils du navigateur est déclaré ; routez ici les autres outils si vous en ajoutez
        if block.type != "tool_use" or block.toolset_name != "browser":
            continue
        result: ToolResultBlockParam = {
            "type": "tool_result",
            "tool_use_id": block.id,
            "toolset_name": "browser",
        }
        if failed:
            result["content"] = NOT_EXECUTED
            result["is_error"] = True
        else:
            try:
                # Une chaîne ou une liste de blocs de contenu ; un exécuteur réel ajoute aussi un
                # bloc browser_state aux résultats de navigation et de gestion des onglets
                result["content"] = handle_browser_action(block.name, block.input)
            except Exception as err:
                result["content"] = f"Error: {err}"
                result["is_error"] = True
                failed = True
        tool_results.append(result)
    return tool_results

Répartissez chaque bloc selon la paire (toolset_name, name) plutôt que selon name seul, car un outil personnalisé dans la même requête peut partager le nom d'un membre ; Ensembles d'outils client décrit les parties de ce contrat que les deux ensembles d'outils partagent. Si Claude nomme un membre que votre exécuteur n'implémente pas, ou un membre que vous avez désactivé, répondez à ce bloc par un résultat d'erreur plutôt que de l'ignorer.

Lorsque vous recevez la réponse en streaming, l'input de chaque membre arrive sous forme d'un seul input_json_delta complet plutôt que de fragments ; attendez donc la fin du tour avant d'exécuter le lot.



Actions par lot

Un tour comportant plusieurs appels membres est une « batch action » (action par lot) : exécutez les appels dans l'ordre où ils apparaissent, arrêtez-vous au premier échec et répondez à chaque appel ultérieur avec is_error: true et le texte exact Not executed: an earlier action in this turn failed. Un lot utilise la même forme de réponse que l'utilisation d'outils en parallèle ; la différence est que vous exécutez les blocs dans l'ordre plutôt que simultanément. Ici, Claude clique sur le champ de recherche qu'il a trouvé précédemment, saisit une requête et appuie sur Entrée en un seul tour :

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "left_click",
      "toolset_name": "browser",
      "input": { "target": { "type": "ref", "ref": "ref_3" } }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ez4kLb1nQ2vXo8sJ9pWm3c",
      "name": "type",
      "toolset_name": "browser",
      "input": { "text": "install" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
      "name": "key",
      "toolset_name": "browser",
      "input": { "text": "Enter" }
    }
  ]
}

Votre application renvoie trois blocs tool_result dans un seul message user, chacun portant toolset_name et un court accusé de réception textuel tel que Clicked element ref_3. Appuyer sur Entrée charge une page de résultats, de sorte que le résultat de key porte également un bloc browser_state avec l'URL mise à jour de l'onglet (Contexte d'onglet sur les autres résultats). Si le clic avait échoué à la place, son résultat porterait votre texte d'erreur et les deux autres résultats porteraient le texte d'arrêt, comme indiqué sous Renvoyer des erreurs depuis votre exécuteur.

Vous n'avez pas besoin de renvoyer une capture d'écran après chaque appel. Claude termine généralement un lot par un appel d'observation (screenshot, read_page ou get_page_text), et votre application peut également joindre sa propre observation, telle qu'une capture d'écran récente ou un arbre d'accessibilité, sous forme de bloc de contenu supplémentaire sur le dernier résultat du lot afin d'économiser un aller-retour. Comme un résultat de gestion d'onglets doit être exactement un bloc browser_state, joignez-la au dernier résultat qui n'est pas un appel de gestion d'onglets.

Si votre exécuteur ne peut exécuter qu'un seul appel par aller-retour, définissez disable_parallel_tool_use sur true dans tool_choice et Claude renvoie au plus un appel membre par tour, au prix d'un plus grand nombre d'allers-retours (Désactiver l'utilisation d'outils en parallèle). Le reste du contrat décrit sous Actions par lot pour l'outil d'utilisation de l'ordinateur s'applique également, y compris un tool_result pour chaque tool_use dans le message user suivant, à deux exceptions près : le texte d'arrêt et ce que contient le content d'un résultat réussi. Le contenu des résultats suit plutôt Outils membres sur cette page : un résultat de new_tab, switch_tab, close_tab ou list_tabs est exactement un bloc browser_state sans texte ni image (Résultats de gestion d'onglets), et le résultat de tout autre membre peut ajouter un bloc browser_state à son texte ou son image (Contexte d'onglet sur les autres résultats). L'endroit où les points de rupture de cache à l'intérieur d'un lot prennent effet est décrit dans la ligne cache_control des Paramètres de l'outil de l'outil d'utilisation de l'ordinateur.



Cibles et coordonnées

Les outils membres qui agissent sur un emplacement prennent un objet target, qui est soit une coordonnée en pixels du viewport, soit une référence à un élément renvoyé par read_page ou find. Les tableaux Outils membres indiquent Target pour un paramètre qui accepte l'une ou l'autre forme.

Les coordonnées sont des pixels du viewport, c'est-à-dire l'espace de pixels d'une screenshot du « viewport » (zone d'affichage) complet avec l'origine en haut à gauche de la page rendue ; il n'y a ni bureau ni cadre de fenêtre environnant. L'ensemble d'outils ne déclare aucune dimension d'affichage et Claude déduit la taille du viewport à partir des captures d'écran que vous renvoyez ; conservez-leur donc une taille cohérente. Un zoom ne change pas le cadre, de sorte que sa region et toutes les coordonnées que Claude émet après avoir vu l'image zoomée restent des pixels du viewport complet.

Les captures d'écran doivent respecter les limites d'image. L'API ne réduit pas les images de l'ensemble d'outils : une capture d'écran ou une image de zoom dépassant les limites de taille d'image de votre modèle, ou la limite par image plus stricte qui s'applique dès qu'une requête contient plus de 20 images, est rejetée. Redimensionnez avant de renvoyer, et remettez les coordonnées de Claude à l'échelle par l'inverse de votre facteur avant de les répartir (Dimensionner les captures d'écran pour respecter les limites d'image).

Les références d'éléments proviennent de read_page et find. Chaque élément de leur sortie porte une étiquette telle que [ref_2], comme dans le résultat du Démarrage rapide :

link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]

Claude renvoie une référence sous forme de cible {"type": "ref", "ref": "ref_2"} lors d'un appel ultérieur de clic, hover, scroll_to, form_input ou file_upload, ou comme paramètre ref de read_page pour lire un sous-arbre. Votre exécuteur attribue les références, conserve la correspondance entre chacune et le nœud sous-jacent (un identifiant de nœud d'accessibilité, un sélecteur stocké ou équivalent), et agit sur ce nœud lorsqu'une référence revient.

Les références sont limitées à l'onglet qui les a produites et restent valides jusqu'à ce que cet onglet navigue ou que son DOM change de manière significative. L'API ne peut pas détecter une référence obsolète ou inconnue ; lorsque Claude transmet une référence que votre exécuteur ne reconnaît plus, renvoyez donc un résultat d'erreur tel que Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references. Claude relit alors la page. Ne renumérotez pas les références que vous avez déjà distribuées pour un onglet tant qu'il n'a pas navigué, car cela invalide silencieusement des références que Claude détient encore.

Claude utilise les deux styles de ciblage et passe de l'un à l'autre selon ce que la page expose ; votre prompt et ce que votre exécuteur renvoie orientent ce choix :

• Préférez les références lorsque la page dispose d'un arbre d'accessibilité exploitable. Une référence survit aux décalages de mise en page et aux réagencements qui rendent les coordonnées en pixels fragiles, et permet à Claude d'agir sur des contrôles difficiles à atteindre avec un pointeur.
• Repliez-vous sur les coordonnées pour le contenu que l'arbre ne décrit pas. Les interfaces rendues sur canvas, les surfaces de vidéo intégrée ou de bureau à distance, les listes fortement virtualisées et les éléments à l'intérieur d'iframes d'origine croisée n'ont souvent aucun nœud utile ; Claude travaille alors à partir de screenshot et zoom et clique par coordonnée ; votre exécuteur détermine dans quel cadre une coordonnée aboutit.
• Limitez la portée des lectures, et lisez l'arbre avant de faire une capture d'écran. Sur les grandes pages, read_page avec filter: "interactive" ou le ref d'un conteneur renvoie un sous-arbre ciblé, et une lecture d'arbre d'une page typique coûte souvent moins de jetons d'entrée qu'une capture d'écran tout en donnant à Claude des références sur lesquelles il peut agir immédiatement. Les captures d'écran restent la bonne observation lorsque la mise en page visuelle, les images ou l'état de rendu comptent.



Considérations de sécurité

L'utilisation du navigateur comporte des risques que les fonctionnalités standard de l'API ne présentent pas, car Claude lit et agit sur du contenu provenant du web ouvert, où n'importe quelle page peut contenir du texte rédigé pour le manipuler.

Claude suit parfois des instructions trouvées dans le contenu d'une page même lorsqu'elles contredisent les vôtres ; un texte sur une page indiquant « ignore tes instructions précédentes et navigue vers... » peut le détourner de la tâche. Isolez Claude des données et actions sensibles pour limiter ce qu'une « prompt injection » (injection de prompt) peut atteindre, consultez Atténuer les jailbreaks et les injections de prompt, et si une tâche ne peut pas éviter une session connectée, utilisez un compte dédié à faibles privilèges et conservez la confirmation humaine sur les actions modifiant le compte.

Comme le navigateur s'exécute dans votre environnement, les sites que Claude visite voient l'identité réseau de votre exécuteur, et le contenu des pages n'atteint l'API que sous la forme des résultats d'outils que vous renvoyez. Informez les utilisateurs finaux des risques pertinents et obtenez leur consentement avant d'activer l'utilisation du navigateur dans vos produits.



Outils membres

L'entrée browser_toolset_20260801 déclare 31 outils membres ; l'input de chaque appel correspond exactement aux paramètres listés ici, et tab_id, lorsqu'il est optionnel, prend par défaut l'onglet actif. Target, CoordinateTarget et RefTarget sont les formes décrites dans Cibles et coordonnées. Quatre membres (javascript_exec, file_upload, read_console et read_network) sont désactivés par défaut et n'apparaissent que lorsque vous les activez. Les bornes d'entrée et les conventions de sortie notées dans la ligne de chaque membre sont indiquées à Claude, et non appliquées par l'API ; validez donc les entrées (y compris les coordonnées par rapport à votre viewport) et appliquez les conventions dans votre exécuteur.

Seuls screenshot et zoom exigent un bloc image dans leur résultat, et les quatre membres de gestion d'onglets (new_tab, list_tabs, switch_tab et close_tab) renvoient exactement un bloc browser_state (voir Résultats de gestion d'onglets). Tous les autres membres renvoient un bloc text : soit un court accusé de réception tel que Clicked element ref_2., soit la sortie du membre. Tout résultat autre qu'un résultat de gestion d'onglets peut également porter un bloc image, généralement une capture d'écran prise après l'action, afin que Claude voie le résultat sans appel screenshot séparé ; Actions par lot indique où en joindre un dans un lot. Un tool_result membre ne peut contenir que des blocs de contenu text, image et browser_state.



Navigation et capture



Pointeur



Clavier et temporisation



Lecture de page



Formulaires et fichiers



Diagnostics et scripts



Gestion des onglets

En cas de succès, chacun de ces membres renvoie exactement un bloc browser_state et aucun texte ni image ; voir Résultats de gestion d'onglets.



Configurer l'ensemble d'outils

Outre type, l'entrée de l'ensemble d'outils accepte configs, cache_control et allowed_callers ; les règles que ces champs partagent avec l'ensemble d'outils d'utilisation de l'ordinateur sont listées sous Ensembles d'outils client, et cette section couvre les valeurs par défaut propres au navigateur. configs est un objet indexé par nom de membre, et la valeur de chaque membre accepte deux champs :



Activer ou désactiver des outils membres

Ne listez dans configs que les membres que vous souhaitez modifier ; chaque membre que vous omettez conserve sa valeur par défaut. Par exemple, un exécuteur qui implémente les lectures de console mais pas le contrôle bas niveau du pointeur ou du maintien de touche active read_console et retire trois membres :

{
  "type": "browser_toolset_20260801",
  "configs": {
    "read_console": { "enabled": true },
    "left_mouse_down": { "enabled": false },
    "left_mouse_up": { "enabled": false },
    "hold_key": { "enabled": false }
  }
}

Un membre désactivé disparaît de la définition que Claude voit ; cela ne garantit pas que Claude ne le nomme jamais, de sorte que votre exécuteur répond tout de même à un tel appel par un résultat d'erreur.



Combiner avec d'autres outils

Déclarez l'outil d'utilisation du navigateur aux côtés de vos propres outils et d'autres outils fournis par Anthropic dans le même tableau tools. Un outil personnalisé peut partager le nom d'un membre (votre propre navigate, par exemple), car toolset_name distingue les appels de Claude, mais aucune autre entrée ne peut être nommée browser, et une requête ne peut contenir qu'une seule entrée d'ensemble d'outils du navigateur.

Vous pouvez également le déclarer aux côtés de l'outil d'utilisation de l'ordinateur, qu'il s'agisse de l'ensemble d'outils ou d'une version antérieure de l'outil d'utilisation de l'ordinateur. Les deux fonctionnent indépendamment, chacun dans son propre repère de coordonnées (pixels du viewport ici, pixels de capture d'écran du bureau là), et les appels de Claude aux membres qui partagent un nom, tels que screenshot ou key, sont distingués par toolset_name.



Activer les membres optionnels

Quatre outils membres sont désactivés par défaut : javascript_exec et file_upload parce qu'ils élargissent ce qu'une page manipulée pourrait faire faire à Claude, et read_console et read_network parce que toutes les piles d'automatisation de navigateur ne peuvent pas fournir ces journaux et qu'ils élargissent le contenu contrôlé par la page qui atteint Claude. Activez chacun avec configs (par exemple, "configs": {"file_upload": {"enabled": true}}) uniquement lorsque votre exécuteur l'implémente et que la tâche en a besoin.



Téléverser des fichiers

file_upload définit directement les fichiers d'un élément <input type="file">, ce qui est plus fiable que de piloter un sélecteur de fichiers natif. Son target est uniquement une référence, car l'appel a besoin de l'identité de l'élément, et il prend paths, document_ids ou les deux :

• paths sont des chemins de fichiers sur le système de fichiers de l'exécuteur, pour les déploiements où l'exécuteur peut lire directement les fichiers de votre application (la même condition que celle dans laquelle vous renseignez le path d'un téléchargement).
• document_ids sont des identifiants de fichiers que votre application a préparés pour le navigateur, pour les déploiements où il ne le peut pas. Votre application définit ce que signifient les identifiants ; limitez leur résolution de la même manière que vous limitez paths, aux fichiers préparés pour cette tâche.

{
  "type": "tool_use",
  "id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
  "name": "file_upload",
  "toolset_name": "browser",
  "input": {
    "target": { "type": "ref", "ref": "ref_12" },
    "paths": ["/home/user/uploads/summary.pdf"],
    "tab_id": "tab-2"
  }
}

Claude écrit ces chemins pendant qu'il lit des pages non fiables, de sorte qu'une implémentation sans restriction permettrait à une page malveillante de diriger le téléversement de n'importe quel fichier lisible par l'exécuteur vers un site que la page contrôle. N'activez le membre que lorsque votre exécuteur résout chaque chemin (en suivant les liens symboliques et les segments ..) et n'accepte rien en dehors d'un répertoire de téléversement dédié et autorisé qui ne contient que des fichiers destinés à la tâche. Ne réutilisez pas le répertoire de téléchargement du navigateur à cette fin ; si vous le faites, chaque fichier qu'une page fait télécharger au navigateur devient téléversable.



Exécuter du JavaScript dans la page

javascript_exec exécute l'expression que Claude écrit dans le contexte de la page et renvoie la valeur de la dernière expression sous forme de texte ; Claude écrit une expression, et non une instruction return. Le code s'exécute avec tous les privilèges de la page, y compris ses cookies, son stockage et ses requêtes de même origine. N'activez le membre que dans des sessions ne contenant aucun identifiant, maintenez en vigueur la liste d'autorisation de domaines des Considérations de sécurité, traitez la valeur renvoyée comme une entrée non fiable et journalisez le code que Claude émet.



Lire l'activité de la console et du réseau

read_console renvoie les entrées de console de l'onglet et read_network renvoie ses requêtes réseau, chacune sous forme de texte avec une ligne par entrée accumulée depuis la lecture précédente de cet onglet. Une ligne de console porte une entrée de journal, d'avertissement ou d'erreur ; une ligne réseau porte la méthode, l'URL, le statut, le type MIME et le chronométrage. Les entrées n'existent qu'à partir du moment où votre automatisation de navigateur s'est attachée à l'onglet, de sorte qu'un résultat vide ne signifie pas qu'un onglet déjà ouvert n'a eu aucun trafic.

Ces membres permettent à Claude de diagnostiquer une page qui se comporte mal (une requête échouée derrière un indicateur de chargement, une erreur de script derrière un bouton inactif) sans captures d'écran répétées. Les entrées de console et de réseau sont contrôlées par la page et contiennent souvent des secrets tels que des jetons dans les URL de requête ; masquez donc les valeurs ressemblant à des identifiants que vous ne voulez pas dans le contexte de Claude et tronquez les entrées très longues avant de les renvoyer.



Suivre les onglets avec browser_state

Claude désigne les onglets par tab_id, votre application est la source de vérité quant aux onglets qui existent, et vous rapportez cet état dans un bloc de contenu browser_state que Claude ne voit jamais directement : l'API génère le texte que Claude lit à partir de celui-ci.

{
  "type": "browser_state",
  "tabs": [
    {
      "tab_id": "tab-1",
      "title": "Documentation",
      "url": "https://example.com/docs",
      "active": true
    },
    { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
  ]
}

• tabs est l'inventaire complet des onglets ouverts après l'appel, et non un delta. Il peut être vide ; lorsqu'il ne l'est pas, exactement une entrée porte "active": true.
• state_changes (non montré ici) rapporte les effets de bord de l'appel : une entrée tab_opened pour chaque onglet ouvert par l'appel et toujours ouvert lorsqu'il se termine, dont le tab_id doit également apparaître dans tabs, ainsi que les événements de téléchargement. Omettez le champ lorsqu'il n'y a rien à rapporter ; un tableau vide est rejeté.
• Envoyez le bloc uniquement sur les résultats qui répondent à un appel de membre du navigateur, au plus une fois par tool_result, et jamais sur un résultat avec is_error: true. Vous exprimez « aucun état d'onglet à rapporter » en omettant le bloc.
• L'API génère tabs sous forme de texte pour Claude comme le décrivent les deux sections suivantes ; les entrées de téléchargement dans state_changes sont validées mais non rendues.

C'est vous qui attribuez les valeurs de tab_id. N'importe quelle chaîne stable convient, comme l'identifiant de page de votre bibliothèque d'automatisation ou votre propre compteur, tant que vous ne réutilisez pas un tab_id alors qu'un onglet portant cet identifiant est encore listé comme ouvert dans un résultat antérieur. L'API applique les limites suivantes au bloc :

• Chaque tab_id, title et url peut comporter au plus 4 096 caractères, tab_id doit être non vide, et aucun ne peut contenir de caractères de contrôle (y compris les sauts de ligne) ni de séparateurs de ligne ou de paragraphe Unicode.
• Un bloc peut lister au plus 100 onglets et 200 changements d'état.
• Les mêmes limites s'appliquent au tab_id que Claude transmet à switch_tab et close_tab, car l'API le rend dans le texte du résultat ; répondez donc à un appel dont le tab_id les enfreint par un résultat d'erreur plutôt que par un bloc browser_state.



Résultats de gestion des onglets

Pour new_tab, switch_tab, close_tab et list_tabs, le content d'un résultat réussi est exactement un bloc browser_state sans texte ni image, et l'API écrit le texte que Claude voit. Le bloc d'un résultat new_tab doit également porter exactement un changement d'état tab_opened dont le tab_id correspond à l'entrée marquée active: true.

Un résultat list_tabs dont le bloc liste deux onglets, le premier étant actif, est rendu comme suit, chaque ligne étant indentée de deux espaces et (current) étant ajouté uniquement à l'onglet actif :

Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs) (current)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Un résultat d'erreur pour l'un de ces membres est l'inverse : un texte d'erreur ordinaire dans content, is_error: true, et aucun bloc browser_state.

Par exemple, lorsque Claude appelle new_tab (son input est vide), votre exécuteur ouvre l'onglet, le rend actif et renvoie l'inventaire avec une entrée tab_opened :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01WvHSbQVV9j5nWGvTmk4vNL",
      "toolset_name": "browser",
      "content": [
        {
          "type": "browser_state",
          "tabs": [
            { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" },
            { "tab_id": "tab-3", "title": "", "url": "about:blank", "active": true }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-3" }]
        }
      ]
    }
  ]
}

Claude voit Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab. Rapportez l'URL à laquelle l'onglet a été ouvert, comme ici, et non celle vers laquelle il est redirigé par la suite ; les résultats ultérieurs rapportent l'URL alors courante de l'onglet.



Contexte d'onglet sur les autres résultats

Sur tous les autres membres, le bloc est facultatif : envoyez-le lorsque l'ensemble des onglets ouverts, l'onglet actif, ou le titre ou l'URL d'un onglet a changé, ou lorsqu'il y a des state_changes à rapporter, et incluez toujours l'inventaire tabs complet. Lorsqu'un résultat porte à la fois du texte et un bloc browser_state, l'API ajoute un pied de page Tab Context au texte de ce résultat, séparé de votre texte par une ligne vide, de sorte que Claude reçoit le nouvel état sans appel list_tabs séparé :

Tab Context:
- Executed on tab_id: tab-1
- Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Executed on nomme l'onglet sur lequel l'appel s'est exécuté, c'est-à-dire son entrée tab_id lorsqu'elle est présente et sinon l'onglet actif, et les lignes d'onglet du pied de page ne portent aucun marqueur (current). N'ajoutez pas ce texte vous-même ; envoyez le bloc structuré et laissez l'API le rendre. Le pied de page est dédupliqué, de sorte qu'un état d'onglet identique n'est pas rendu à nouveau sur les résultats ultérieurs et que remplir le bloc généreusement ne coûte rien.

Trois cas ne rendent aucun pied de page même lorsque le bloc est présent :

• Tout résultat zoom.
• Un résultat sans bloc text (un résultat screenshot contenant uniquement une image, par exemple). Rien n'est rendu ni mémorisé pour ce résultat ; le contexte d'onglet apparaît sur le prochain résultat qui porte à la fois du texte et un bloc browser_state, incluez donc un court bloc de texte à côté de l'image lorsque vous voulez que Claude voie un changement d'onglet sur ce même résultat.
• Un résultat dont la liste tabs est vide sur un appel qui ne portait aucun tab_id, car il n'y a aucun onglet à nommer.

Par exemple, lorsque Claude a cliqué sur le lien « Pricing » (ref_5) plus tôt dans cette session, la page l'a ouvert dans un nouvel onglet que Claude n'avait pas demandé, et sans rapport Claude devrait appeler list_tabs pour le découvrir. Renvoyez l'accusé de réception du clic plus un bloc dont les state_changes nomment l'onglet ouvert, en marquant l'onglet que votre exécuteur a laissé actif :

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01EgTXj1FjE2FCTt2zNFWLao",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Clicked element ref_5." },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-2" }]
        }
      ]
    }
  ]
}

Claude voit Clicked element ref_5. suivi du pied de page Tab Context montré précédemment. Un onglet ouvert pendant un appel qui a échoué ne reçoit aucune entrée tab_opened, car les résultats d'erreur ne portent pas de browser_state ; il apparaît à la place dans l'inventaire tabs du prochain résultat réussi. Dans un lot, attachez le bloc au résultat de l'appel pendant lequel le changement s'est produit, et donnez à chaque résultat de gestion d'onglets réussi son propre bloc même lorsqu'un résultat antérieur du même tour a rapporté le même état.



Rapporter les téléchargements

Lorsqu'un clic ou une navigation déclenche le téléchargement d'un fichier, rapportez-le dans state_changes sur le résultat de l'appel pendant lequel il s'est produit, corrélé entre les résultats par un download_id que vous attribuez. Les téléchargements s'exécutent de manière asynchrone et peuvent s'étendre sur plusieurs résultats, il existe donc trois types d'événements :

L'API valide ces entrées mais ne les rend pas dans le texte que Claude voit ; lorsque Claude doit agir sur le fichier, mentionnez donc également le nom du fichier ou le path dans le bloc text du même résultat.

Par exemple, un clic sur « Download price list (CSV) » (ref_8) dans l'onglet Pricing déclenche un téléchargement, de sorte que le résultat du clic porte une entrée download_started avec le download_id "dl-1" et l'URL du fichier. Le téléchargement se termine pendant qu'un appel screenshot ultérieur est en cours, de sorte que le content de ce résultat contient l'image, un bloc de texte tel que Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes)., et ce bloc browser_state rapportant l'achèvement sous le même download_id :

{
  "type": "browser_state",
  "tabs": [
    { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
    {
      "tab_id": "tab-2",
      "title": "Pricing",
      "url": "https://example.com/pricing",
      "active": true
    }
  ],
  "state_changes": [
    {
      "type": "download_completed",
      "download_id": "dl-1",
      "url": "https://example.com/pricing/price-list.csv",
      "path": "/home/user/downloads/price-list.csv",
      "size_bytes": 48213
    }
  ]
}

Les rapports de téléchargement suivent ces règles :

• Au plus une entrée par download_id dans un même bloc, de sorte qu'un téléchargement qui commence et se termine pendant le même appel ne rapporte que download_completed.
• N'envoyez jamais de state_changes sur un résultat is_error: true ; rapportez un événement de téléchargement survenu pendant un appel échoué sur le prochain résultat réussi.
• state_changes n'est pas un inventaire des téléchargements en cours ; rapportez chaque événement une seule fois.
• Chaque entrée ne porte que les champs que son type déclare. size_bytes est un entier non négatif, download_id est non vide, et download_id, url, path et error comportent chacun au plus 4 096 caractères sans caractères de contrôle ni séparateurs de ligne ou de paragraphe Unicode. L'url provient du serveur distant et porte souvent des identifiants signés dans la chaîne de requête après redirections ; supprimez donc les paramètres de requête que vous ne voulez pas dans le contexte de Claude et assainissez-la avant de la rapporter ou de l'utiliser dans un chemin du système de fichiers.



Gérer les erreurs

Rapportez un appel échoué à Claude comme un résultat d'erreur ordinaire : is_error: true, un contenu texte indiquant ce qui s'est mal passé, toolset_name répété, et aucun bloc browser_state.



Renvoyer des erreurs depuis votre exécuteur

Rendez le texte d'erreur précis, car Claude le lit et s'adapte : Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable. donne à Claude quelque chose sur quoi agir, là où un simple Error: navigation failed ne le fait pas. Autres cas courants :



Erreurs de requête

L'API valide l'entrée du toolset ainsi que chaque bloc tool_use et tool_result de membre dans la conversation. Lorsque l'un d'eux est mal formé, l'API renvoie une invalid_request_error avant que Claude ne s'exécute. Dans le tableau suivant, la colonne de gauche nomme ce que vous avez envoyé.



Limitations

• Disponibilité par plateforme : l'utilisation du navigateur est disponible uniquement sur l'API Claude.
• Streaming de l'entrée complète uniquement : lorsque vous utilisez le streaming, l'input de chaque membre arrive sous la forme d'un seul input_json_delta complet (Toolsets client).
• Les références d'éléments sont fournies au mieux : les pages très dynamiques (listes virtualisées, interfaces rendues sur canvas, pages qui se re-rendent au défilement) peuvent ne pas exposer de références stables, et Claude se rabat alors sur les captures d'écran et les clics par coordonnées.
• read_console et read_network dépendent de votre automatisation de navigateur : ils ne rapportent que ce qu'elle peut capturer, et uniquement à partir du moment où elle s'est attachée à un onglet.
• Les limitations générales des agents s'appliquent : la latence, la précision de la vision et les risques d'injection de prompt sont hérités de l'utilisation de l'ordinateur (consultez les Limitations de l'outil d'utilisation de l'ordinateur), et ses recommandations sous Optimiser les performances du modèle avec le prompting, Gérer l'historique des captures d'écran et Suivre les bonnes pratiques d'implémentation (délais entre actions, validation des actions et journalisation) s'appliquent également aux exécuteurs de navigateur.



Tarification et conservation des données

Le « browser use » (utilisation du navigateur) suit la tarification standard de l'utilisation d'outils. Lors de l'utilisation de l'outil browser use :

Surcharge liée à la définition du toolset : Déclarer browser_toolset_20260801 avec ses membres par défaut ajoute environ 6 600 jetons d'entrée à une requête (environ 6 610 sur Claude Fable 5, Claude Mythos 5, Claude Opus 5 et Claude Opus 4.8, et environ 6 670 sur Claude Sonnet 5), ce qui couvre les définitions des outils membres et l'invite système de l'utilisation d'outils. L'activation des quatre membres optionnels ajoute environ 880 jetons, et la désactivation de membres avec configs réduit ce nombre. Le nombre exact pour une requête est indiqué dans le champ usage de la réponse, et vous pouvez l'estimer à l'avance avec le point de terminaison de comptage des jetons.

Consommation de jetons supplémentaire :

• Les captures d'écran et images de zoom renvoyées dans les résultats d'outils, facturées comme entrée d'image (voir la tarification de la vision)
• Les résultats d'outils textuels renvoyés à Claude, tels que les arbres d'accessibilité, le texte des pages et les entrées de console ou de réseau

La session de navigateur, les téléchargements et les fichiers téléversés restent dans votre environnement ; les captures d'écran, le texte des pages et l'état des onglets que vous renvoyez font partie du contenu de votre requête API et suivent la politique de conservation standard, ou votre accord ZDR si vous en avez un. L'outil d'utilisation du navigateur est éligible au ZDR ; consultez API et conservation des données pour les durées de conservation et l'éligibilité selon les fonctionnalités.



Étapes suivantes