---
title: Outil d'utilisation du navigateur
url: https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool
description: Permettez à Claude de naviguer, de lire et d'interagir avec des pages web dans votre propre environnement de navigateur grâce à l'outil d'utilisation du navigateur.
featureMetadata:
status: ga
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-opus-4-8
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Google Cloud: ga
---
**Commencez avec les ensembles d'outils du SDK :** les SDK Python et TypeScript disposent d'une classe pour l'ensemble d'outils du navigateur, en bêta. Partez de [l'intégration d'un partenaire](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-sdk#partner-integrations), ou consultez [Utilisation du navigateur et de l'ordinateur avec les ensembles d'outils du SDK](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-sdk). Utilisez cette page comme référence de l'outil, ou lorsque vous gérez vous-même les appels d'outils.
L'outil d'utilisation du navigateur permet à Claude de naviguer, de lire et d'interagir avec des pages web dans un navigateur exécuté par votre application. Claude travaille avec la page à la fois par sa structure, c'est-à-dire l'« accessibility tree » (arbre d'accessibilité), les éléments, les formulaires et les onglets, et par des captures d'écran et des coordonnées du « viewport » (fenêtre d'affichage).
L'outil est un [« client toolset » (ensemble d'outils client)](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets) défini par Anthropic : une seule entrée `browser_toolset_20260801` dans `tools` donne à Claude 27 « member tools » (outils membres) par défaut, tels que `navigate`, `read_page`, `left_click` et `screenshot`, plus quatre autres lorsque vous [les activez](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). Votre application exécute chaque appel avec sa propre automatisation de navigateur ; rien ne s'exécute du côté d'Anthropic. L'outil n'est actuellement pas disponible dans [Claude Managed Agents](https://platform.claude.com/docs/fr/managed-agents/tools).
Choisissez l'utilisation du navigateur lorsque la tâche reste à l'intérieur de pages web et implique d'agir sur celles-ci, ou lorsque les pages construisent leur contenu avec JavaScript. Lorsqu'une tâche nécessite un bureau complet, utilisez l'[outil d'utilisation de l'ordinateur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool), qui fonctionne uniquement au moyen de captures d'écran et de coordonnées. Pour lire des pages vers lesquelles vous pouvez orienter Claude, ou pour trouver des sources sur le web, l'[outil de récupération web](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/web-fetch-tool) et l'[outil de recherche web](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/web-search-tool) sont plus légers. Ce sont des [outils serveur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/server-tools) que l'API exécute pour vous, sans navigateur à piloter.
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é](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#security-considerations) avant de déployer.
## Démarrage rapide
L'outil d'utilisation du navigateur est disponible sur la Claude API et sur [Google Cloud](https://platform.claude.com/docs/fr/build-with-claude/claude-on-vertex-ai) : ajoutez une entrée de type `browser_toolset_20260801`, sans `name`, au tableau `tools` d'une requête de l'[API Messages](https://platform.claude.com/docs/fr/api/messages/create).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 2048,
"tools": [
{
"type": "browser_toolset_20260801"
}
],
"messages": [
{
"role": "user",
"content": "Open example.com/docs and tell me how to get started."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 2048
tools:
- type: browser_toolset_20260801
messages:
- role: user
content: Open example.com/docs and tell me how to get started.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 2048,
tools: [{ type: "browser_toolset_20260801" }],
messages: [
{
role: "user",
content: "Open example.com/docs and tell me how to get started."
}
]
});
console.log(response);
```
```csharp C#
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 2048,
Tools = [new BrowserToolset20260801()],
Messages =
[
new MessageParam
{
Role = Role.User,
Content = "Open example.com/docs and tell me how to get started.",
},
],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 2048,
Tools: []anthropic.ToolUnionParam{
{OfBrowserToolset20260801: &anthropic.BrowserToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open example.com/docs and tell me how to get started.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.BrowserToolset20260801;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(2048L)
.addTool(BrowserToolset20260801.builder().build())
.addUserMessage("Open example.com/docs and tell me how to get started.")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 2048,
messages: [
['role' => 'user', 'content' => 'Open example.com/docs and tell me how to get started.'],
],
model: 'claude-opus-5-5',
tools: [
['type' => 'browser_toolset_20260801'],
],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 2048,
tools: [
{ type: "browser_toolset_20260801" }
],
messages: [
{
role: "user",
content: "Open example.com/docs and tell me how to get started."
}
]
)
puts response
```
La première réponse de Claude se termine par `stop_reason: "tool_use"` et contient un ou plusieurs blocs `tool_use` de membres, chacun nommant un outil membre dans `name` et portant `"toolset_name": "browser"` :
```json Output
{
"id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
"type": "message",
"role": "assistant",
"model": "claude-opus-5-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 « executor » (exécuteur), c'est-à-dire la partie de votre application qui pilote le navigateur et produit les résultats d'outils, exécute `navigate`, puis `read_page`. Votre application renvoie un `tool_result` par bloc dans sa requête suivante, en reprenant `toolset_name` sur chacun. Le résultat de `navigate` indique l'onglet dans lequel la page a été chargée dans un bloc `browser_state` ; le résultat de `read_page` est un texte dans lequel chaque élément porte une référence :
```json
{
"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 dispose désormais de références sur lesquelles il peut agir ; son tour suivant peut donc 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 la forme d'une « agent loop » (boucle d'agent) dans votre application : 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 par du texte.
* Ajoutez l'entrée `browser_toolset_20260801`, et éventuellement d'autres outils, à votre requête API.
* Incluez un prompt utilisateur qui nécessite de travailler avec des pages web, par exemple : « Ouvre example.com/docs et dis-moi comment démarrer. »
* Claude renvoie un ou plusieurs blocs `tool_use` dans un seul tour d'assistant ; plusieurs blocs dans un même tour forment une action par lot, par exemple `left_click`, puis `type`, puis `key`.
* Le `name` de chaque bloc est le nom du membre, chaque bloc porte `"toolset_name": "browser"`, et `input` ne contient que les paramètres de ce membre, sans champ `action`. Le `stop_reason` de la réponse est `tool_use`.
* Parcourez chaque bloc `tool_use` de `response.content` (ne supposez pas qu'il n'y en a qu'un seul) et exécutez-les séquentiellement, dans l'ordre où ils apparaissent, car les appels ultérieurs dépendent généralement des précédents.
* Renvoyez un `tool_result` par bloc dans un nouveau message `user`, associé par `tool_use_id`, et reprenez `"toolset_name": "browser"` sur chacun. Chaque appel doit recevoir une réponse, sinon la requête suivante est rejetée.
* Si un appel échoue, renvoyez `is_error: true` avec une description textuelle pour ce bloc, puis appliquez la règle d'arrêt décrite dans [Actions par lot](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#batch-actions) à chaque bloc ultérieur du tour.
* Claude lit les résultats (texte de page, arbres d'accessibilité, captures d'écran, état des onglets) et, s'il a besoin de plus, renvoie d'autres appels de membres, ce qui vous ramène à l'étape 3.
* Sinon, il renvoie une réponse textuelle à l'utilisateur.
Voici un squelette de l'étape d'appel d'outils de cette boucle, en deux parties. D'abord, des gestionnaires de membres factices remplacent 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.
```python Python
# 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}")
```
```typescript TypeScript
// Données d'image fictives ; un exécuteur réel capture la fenêtre d'affichage en octets PNG
const PLACEHOLDER_PNG =
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function navigate(url: string): string {
return `navigated to ${url}`;
}
function readPage(): string {
return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]';
}
function clickElement(ref: string): string {
return `clicked ${ref}`;
}
function clickAt(x: number, y: number): string {
return `clicked at (${x}, ${y})`;
}
function typeText(text: string): string {
return `typed: ${text}`;
}
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshot répond avec un bloc image plutôt que du texte
return [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: PLACEHOLDER_PNG
}
}
];
}
function handleBrowserAction(
action: string,
input: unknown
): string | Anthropic.ImageBlockParam[] {
const params: object = typeof input === "object" && input !== null ? input : {};
if (action === "navigate" && "url" in params) {
return navigate(String(params.url));
} else if (action === "read_page") {
return readPage();
} else if (action === "left_click" && "target" in params) {
// target est une référence d'élément issue de read_page ou une coordonnée de la fenêtre d'affichage
const target: object =
typeof params.target === "object" && params.target !== null ? params.target : {};
if ("type" in target && target.type === "ref" && "ref" in target) {
return clickElement(String(target.ref));
} else if ("x" in target && "y" in target) {
return clickAt(Number(target.x), Number(target.y));
}
} else if (action === "type" && "text" in params) {
return typeText(String(params.text));
} else if (action === "screenshot") {
return captureScreenshot();
}
// Gérez les autres actions selon les besoins
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Données d'image fictives ; un exécuteur réel capture la fenêtre d'affichage et renvoie les octets PNG
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
string Navigate(string url) => $"navigated to {url}";
string ReadPage() =>
"""
link "Docs" [ref_1]
button "Search" [ref_2]
""";
string ClickRef(string elementRef) => $"clicked {elementRef}";
string ClickAt(int x, int y) => $"clicked at ({x}, {y})";
// target vaut {"type": "ref", "ref": "ref_1"} ou {"type": "coordinate", "x": 640, "y": 380}
string Click(JsonElement target) =>
target.GetProperty("type").GetString() == "ref"
? ClickRef(target.GetProperty("ref").GetString()!)
: ClickAt(target.GetProperty("x").GetInt32(), target.GetProperty("y").GetInt32());
string TypeText(string text) => $"typed: {text}";
// screenshot répond avec un bloc image plutôt que du texte : renvoyer la liste de contenu du résultat
List CaptureScreenshot() =>
[
new ImageBlockParam(
new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
),
];
ToolResultBlockParamContent HandleBrowserAction(
string action,
IReadOnlyDictionary input
) =>
action switch
{
"navigate" => Navigate(input["url"].GetString()!),
"read_page" => ReadPage(),
"left_click" => Click(input["target"]),
"type" => TypeText(input["text"].GetString()!),
"screenshot" => CaptureScreenshot(),
// Gérer les autres actions selon les besoins
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG remplace une capture réelle : un exécuteur renvoie le
// viewport sous forme de données PNG encodées en base64.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// textContent encapsule du texte en tant que contenu tool_result.
func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfText: &anthropic.TextBlockParam{Text: text}},
}
}
func navigate(url string) string {
return fmt.Sprintf("navigated to %s", url)
}
func readPage() string {
return "link \"Docs\" [ref_1]\nbutton \"Search\" [ref_2]"
}
func clickRef(ref string) string {
return fmt.Sprintf("clicked %s", ref)
}
func clickAt(x, y int) string {
return fmt.Sprintf("clicked at (%d, %d)", x, y)
}
func typeText(text string) string {
return fmt.Sprintf("typed: %s", text)
}
// captureScreenshot renvoie un bloc image plutôt que du texte.
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
func handleBrowserAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
switch action {
case "navigate":
if url, ok := params["url"].(string); ok {
return textContent(navigate(url)), nil
}
case "read_page":
return textContent(readPage()), nil
case "left_click":
// target est soit une référence d'élément issue de read_page, soit une coordonnée du viewport
target, _ := params["target"].(map[string]any)
if ref, ok := target["ref"].(string); ok && target["type"] == "ref" {
return textContent(clickRef(ref)), nil
}
x, xok := target["x"].(float64)
y, yok := target["y"].(float64)
if xok && yok {
return textContent(clickAt(int(x), int(y))), nil
}
case "type":
if text, ok := params["text"].(string); ok {
return textContent(typeText(text)), nil
}
case "screenshot":
return captureScreenshot(), nil
// Gérez les autres actions selon les besoins
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Atteint lorsqu'il manque un champ dans l'entrée d'un membre ou qu'un champ a le mauvais type
return nil, fmt.Errorf("invalid input for %s", action)
}
```
```java Java
/** Placeholder pixels; a real executor captures the viewport and base64-encodes the PNG. */
static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
ToolResultBlockParam.Content captureScreenshot() {
ImageBlockParam image = ImageBlockParam.builder()
.source(Base64ImageSource.builder()
.mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
.data(PLACEHOLDER_PNG)
.build())
.build();
return ToolResultBlockParam.Content.ofBlocks(
List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
}
String navigate(String url) {
return "navigated to " + url;
}
String readPage() {
return """
link "Docs" [ref_1]
button "Search" [ref_2]""";
}
String clickRef(String ref) {
return "clicked " + ref;
}
String clickAt(long x, long y) {
return "clicked at (" + x + ", " + y + ")";
}
String typeText(String text) {
return "typed: " + text;
}
/** Runs one browser toolset member; {@code action} is the tool_use block's name. */
ToolResultBlockParam.Content handleBrowserAction(String action, Map input) {
if (action.equals("screenshot")) {
return captureScreenshot(); // the one member here that answers with an image block
}
String output = switch (action) {
case "navigate" -> navigate(input.get("url").asStringOrThrow());
case "read_page" -> readPage();
case "left_click" -> {
// target est {"type": "ref", "ref": "ref_1"} ou {"type": "coordinate", "x": 640, "y": 380}
Map target =
(Map) input.get("target").asObject().get();
if (target.get("type").asStringOrThrow().equals("ref")) {
yield clickRef(target.get("ref").asStringOrThrow());
}
long x = ((Number) target.get("x").asNumber().get()).longValue();
long y = ((Number) target.get("y").asNumber().get()).longValue();
yield clickAt(x, y);
}
case "type" -> typeText(input.get("text").asStringOrThrow());
// Gérer les autres actions selon les besoins
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Substitut aux vrais octets PNG ; un véritable exécuteur capture la fenêtre d'affichage
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function navigateTo(string $url): string
{
return "navigated to {$url}";
}
function readPage(): string
{
return <<<'TEXT'
link "Docs" [ref_1]
button "Search" [ref_2]
TEXT;
}
function clickTarget(array $target): string
{
// Une cible est une référence d'élément issue de read_page ou find, ou une coordonnée en pixels de la fenêtre d'affichage
if ($target['type'] === 'ref') {
return "clicked {$target['ref']}";
}
return "clicked at ({$target['x']}, {$target['y']})";
}
function typeText(string $text): string
{
return "typed: {$text}";
}
function captureScreenshot(): array
{
// screenshot répond avec un bloc image plutôt que du texte, donc renvoyer la liste de contenu du résultat
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function handleBrowserAction(string $name, array $input): string|array
{
return match ($name) {
'navigate' => navigateTo($input['url']),
'read_page' => readPage(),
'left_click' => clickTarget($input['target']),
'type' => typeText($input['text']),
'screenshot' => captureScreenshot(),
// Gérer les autres actions selon les besoins
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Données d'image factices ; un exécuteur réel capture la fenêtre d'affichage en PNG.
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def navigate(url)
"navigated to #{url}"
end
def read_page
<<~TREE
link "Docs" [ref_1]
button "Search" [ref_2]
TREE
end
def click(target)
return "clicked #{target[:ref]}" if target[:type] == "ref"
"clicked at (#{target[:x]}, #{target[:y]})"
end
def type_text(text)
"typed: #{text}"
end
def capture_screenshot
[
{
type: "image",
source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
}
]
end
def handle_browser_action(name, input)
case name
when "navigate"
navigate(input[:url])
when "read_page"
read_page
when "left_click"
# target est une référence d'élément (issue de read_page ou find) ou une coordonnée
click(input[:target])
when "type"
type_text(input[:text])
when "screenshot"
capture_screenshot
# Gérer les autres actions selon les besoins
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#batch-actions), 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop), avec l'ensemble d'outils du navigateur dans `tools`.
```python Python
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
```
```typescript TypeScript
const HALT_TEXT = "Not executed: an earlier action in this turn failed.";
function browserResult(
toolUseId: string,
content: string | Anthropic.ImageBlockParam[],
isError?: boolean
): Anthropic.ToolResultBlockParam {
return {
type: "tool_result",
tool_use_id: toolUseId,
toolset_name: "browser",
content,
is_error: isError
};
}
function processToolCalls(response: Anthropic.Message): Anthropic.ToolResultBlockParam[] {
const toolResults: Anthropic.ToolResultBlockParam[] = [];
let failed = false;
for (const block of response.content) {
if (block.type !== "tool_use") {
continue;
}
if (block.toolset_name !== "browser") {
// Cet exemple ne déclare que le jeu d'outils du navigateur ; routez les autres outils
// ici si vous en ajoutez.
continue;
}
if (failed) {
// Un lot s'arrête à son premier échec ; répondez aux actions suivantes comme non exécutées
toolResults.push(browserResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Une chaîne ou une liste de blocs image ; un exécuteur réel ajoute aussi un
// bloc browser_state aux résultats de navigation et de gestion des onglets
const result = handleBrowserAction(block.name, block.input);
toolResults.push(browserResult(block.id, result));
} catch (error) {
failed = true;
const message = error instanceof Error ? error.message : String(error);
toolResults.push(browserResult(block.id, `Error: ${message}`, true));
}
}
return toolResults;
}
```
```csharp C#
const string HaltText = "Not executed: an earlier action in this turn failed.";
List ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "browser")
{
// Cet exemple ne déclare que le jeu d'outils du navigateur ; acheminez les autres outils
// ici si vous en ajoutez.
continue;
}
if (failed)
{
// Un lot s'arrête à son premier échec ; répondre aux actions suivantes sans les exécuter
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "browser",
}
);
continue;
}
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
var result = HandleBrowserAction(toolUse.Name, toolUse.Input);
toolResults.Add(
new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "browser" }
);
}
catch (Exception e)
{
failed = true;
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = $"Error: {e.Message}",
IsError = true,
ToolsetName = "browser",
}
);
}
}
return toolResults;
}
```
```go Go
const notExecuted = "Not executed: an earlier action in this turn failed."
// browserToolResult construit le résultat d'une action de navigateur. Contrairement à un
// résultat d'outil ordinaire, il doit reprendre le nom du toolset. Un exécuteur réel ajoute
// aussi un bloc browser_state aux résultats de navigation et de gestion des onglets.
func browserToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
result := anthropic.ToolResultBlockParam{
ToolUseID: toolUseID,
ToolsetName: anthropic.String("browser"),
Content: content,
}
if isError {
result.IsError = anthropic.Bool(true)
}
return anthropic.ContentBlockParamUnion{OfToolResult: &result}
}
// processToolCalls exécute dans l'ordre les actions de navigateur de la réponse de Claude et
// construit un tool_result par bloc tool_use. Après le premier échec, il ignore
// le reste : Claude les a planifiées en supposant que les actions précédentes avaient réussi.
func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
var toolResults []anthropic.ContentBlockParamUnion
failed := false
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.ToolUseBlock:
// Cet exemple ne déclare que le toolset navigateur ; routez ici les autres outils si vous en ajoutez.
if variant.ToolsetName != "browser" {
continue
}
if failed {
toolResults = append(toolResults, browserToolResult(variant.ID, textContent(notExecuted), true))
continue
}
var input map[string]any
var content []anthropic.ToolResultBlockParamContentUnion
err := json.Unmarshal(variant.Input, &input)
if err == nil {
content, err = handleBrowserAction(variant.Name, input)
}
if err != nil {
failed = true
content = textContent("Error: " + err.Error())
}
toolResults = append(toolResults, browserToolResult(variant.ID, content, err != nil))
}
}
return toolResults
}
```
```java Java
/** The exact text the toolset contract prescribes for member calls skipped after a failure. */
static final String HALT_TEXT = "Not executed: an earlier action in this turn failed.";
/** Every result answering a browser toolset member echoes toolset_name. */
ToolResultBlockParam.Builder browserResult(ToolUseBlock toolUse) {
return ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.toolsetName("browser");
}
/**
* Run the browser actions in Claude's response in order and build one
* tool_result per tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// Cet exemple ne déclare que le jeu d'outils du navigateur ; routez ici les autres outils si vous en ajoutez.
if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("browser"))) {
continue;
}
ToolUseBlock toolUse = block.asToolUse();
ToolResultBlockParam result;
if (failed) {
result = browserResult(toolUse).content(HALT_TEXT).isError(true).build();
} else {
try {
Map input =
(Map) toolUse._input().asObject().get();
ToolResultBlockParam.Content output = handleBrowserAction(toolUse.name(), input);
// Un exécuteur réel ajoute aussi un bloc browser_state aux résultats de navigation et
// de gestion des onglets ; voir « Suivre les onglets avec browser_state » sur cette page.
result = browserResult(toolUse).content(output).build();
} catch (RuntimeException e) {
failed = true;
result = browserResult(toolUse).content("Error: " + e.getMessage()).isError(true).build();
}
}
toolResults.add(ContentBlockParam.ofToolResult(result));
}
return toolResults;
}
```
```php PHP
const HALT_TEXT = 'Not executed: an earlier action in this turn failed.';
function processToolCalls(Message $response): array
{
$toolResults = [];
$failed = false;
foreach ($response->content as $block) {
// Cet exemple ne déclare que le jeu d'outils du navigateur ; routez ici les autres outils si vous en ajoutez.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'browser') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'browser'];
if ($failed) {
// Un lot s'arrête à son premier échec ; les actions restantes reçoivent une réponse sans être exécutées
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Un véritable exécuteur renvoie aussi un bloc browser_state pour les résultats de navigation et de gestion d'onglets
$toolResults[] = [...$result, 'content' => handleBrowserAction($block->name, $block->input)];
} catch (\Throwable $e) {
$failed = true;
$toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
}
}
return $toolResults;
}
```
```ruby Ruby
NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
# Exécuter dans l'ordre les actions de navigateur de la réponse de Claude et construire un
# tool_result par bloc tool_use. Après le premier échec, ignorer le reste :
# Claude les a planifiées en supposant que les actions précédentes avaient réussi.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Cet exemple ne déclare que le jeu d'outils du navigateur ; routez ici les autres outils
# si vous en ajoutez.
next unless block.type == :tool_use && block.toolset_name == "browser"
result = { type: "tool_result", tool_use_id: block.id, toolset_name: "browser" }
if failed
result.update(content: NOT_EXECUTED, is_error: true)
else
begin
# Une String, ou des blocs de contenu pour une capture d'écran. 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)
rescue => e
result.update(content: "Error: #{e.message}", is_error: true)
failed = true
end
end
tool_results << result
end
tool_results
end
```
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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets) 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 avec un [résultat d'erreur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor) plutôt que de l'ignorer.
Lorsque vous recevez la réponse en streaming, l'`input` de chaque membre arrive sous la 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/parallel-tool-use) ; 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 :
```json
{
"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.` L'appui 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). 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é dans [Renvoyer des erreurs depuis votre exécuteur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
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 renverra 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)). Le reste du contrat décrit dans [Actions par lot pour l'outil d'utilisation de l'ordinateur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#batch-actions) 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#member-tools) 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-management-results)), 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#tool-parameters) 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 de la section [Outils membres](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#member-tools) indiquent `Target` pour un paramètre qui accepte l'une ou l'autre forme.
| Forme | `target.type` | Champs | Accepté par |
| ------------------ | -------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CoordinateTarget` | `"coordinate"` | `x`, `y` (entiers, pixels du viewport) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `left_click_drag` (`from` et `target`), `left_mouse_down`, `left_mouse_up`, `mouse_move`, `scroll` |
| `RefTarget` | `"ref"` | `ref` (une référence d'élément telle que `"ref_2"`) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `scroll_to`, `form_input`, `file_upload` |
**Les coordonnées sont des pixels du viewport**, l'espace de pixels d'une `screenshot` du viewport 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 modifie 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](https://platform.claude.com/docs/fr/build-with-claude/vision#evaluate-image-size) 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](https://platform.claude.com/docs/fr/build-with-claude/vision#request-limits), est rejetée. Redimensionnez avant de renvoyer, et remettez à l'échelle les coordonnées de Claude par l'inverse de votre facteur avant de les répartir ([Dimensionner les captures d'écran pour respecter les limites d'image](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
**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 :
```text wrap
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 la forme d'une 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 en fonction de ce que la page expose ; votre prompt et ce que renvoie votre exécuteur 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 recompositions 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 de l'arbre d'une page typique coûte souvent moins de tokens 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 importent.
## 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.
Pour réduire ces risques, prenez des précautions telles que les suivantes :
1. Exécutez le navigateur et votre exécuteur dans un conteneur ou une machine virtuelle dédiés avec des privilèges minimaux, un profil vierge ne contenant aucun identifiant, et aucun accès aux systèmes de fichiers sensibles ni aux réseaux internes ; isolez de la même manière tout outil que vous exécutez à côté.
2. Restreignez les hôtes que le navigateur peut atteindre à une « allowlist » (liste d'autorisation) de domaines appliquée au niveau de la couche réseau et revérifiée dans votre gestionnaire `navigate` après les redirections, et bloquez les plages loopback, link-local et privées, sauf si la tâche en a besoin.
3. Traitez tout ce qu'une page fournit comme une entrée non fiable, y compris les titres et URL des onglets, ainsi que les champs `url`, `path` et `error` de chaque téléchargement, que vous signalez dans un bloc [`browser_state`](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), et construisez les lectures de page à partir de ce que la page affiche (l'arbre d'accessibilité ou le texte visible), et non du code source DOM brut, afin que le texte masqué n'atteigne pas Claude.
4. Dans votre gestionnaire `navigate`, acceptez les mots-clés d'historique `"back"`, `"forward"` et `"reload"`, traitez une URL sans schéma comme `https://`, puis analysez l'URL et refusez tout schéma autre que `http` ou `https` (`javascript:`, `file:`, `data:`, `chrome:`, etc.) avec un [résultat d'erreur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor). Vérifiez le schéma avec un analyseur d'URL plutôt qu'avec un préfixe de chaîne ; l'API ne filtre pas les URL que Claude ouvre, elle ne peut donc pas en rejeter une à votre place.
5. Laissez `javascript_exec` et `file_upload` désactivés sauf si vous en avez besoin, et lisez [Activer les membres optionnels](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) avant d'activer l'un ou l'autre.
6. Faites confirmer par un humain les actions lourdes de conséquences et tout ce qui nécessite un consentement explicite (achats, modification de comptes, envoi de messages et acceptation de conditions), et effectuez cette vérification dans votre exécuteur avant chaque appel, car un seul tour peut en contenir plusieurs.
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](https://platform.claude.com/docs/fr/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks), 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.
Anthropic a entraîné le modèle à résister à ces injections de prompt et a ajouté une couche de défense supplémentaire. Si vous utilisez l'outil d'utilisation du navigateur, des classificateurs analyseront automatiquement ce que renvoie le navigateur, comme le texte des pages ou les captures d'écran, afin de signaler les injections de prompt potentielles. Lorsque ces classificateurs identifient une injection de prompt potentielle, ils orienteront automatiquement le modèle pour qu'il vérifie si l'instruction provient réellement de vous avant d'agir en conséquence.
Cette protection supplémentaire ne sera pas idéale pour tous les cas d'usage (par exemple, les cas d'usage sans humain dans la boucle) ; si vous souhaitez la désactiver, [contactez le support](https://support.claude.com/en/). Les précautions ci-dessus restent importantes même avec ces classificateurs en place.
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 la valeur de l'onglet actif. `Target`, `CoordinateTarget` et `RefTarget` sont les formes décrites dans [Cibles et coordonnées](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates). 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). Les bornes d'entrée et les conventions de sortie indiquées dans la ligne de chaque membre sont communiqué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`](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools) 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-management-results)). 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#batch-actions) 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
| Membre | Entrée | Description |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `navigate` | `url`, `tab_id?` | Charge une URL `http` ou `https`, ou se déplace dans l'historique avec `"back"`, `"forward"` ou `"reload"`. Traitez une URL sans schéma comme `https://` et refusez tout autre schéma avec un résultat d'erreur. Renvoyez un court accusé de réception, plus un bloc `browser_state` lorsque l'URL ou le titre de l'onglet a changé. |
| `screenshot` | `tab_id?` | Capture le viewport et renvoie un bloc `image`. |
| `zoom` | `region`, `tab_id?` | Renvoie une `image` recadrée et agrandie de `region`, donnée sous la forme `[x0, y0, x1, y1]` en pixels du viewport, pour une inspection plus précise de petits textes ou contrôles. |
### Pointeur
| Membre | Entrée | Description |
| ----------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `left_click` | `target: Target`, `modifiers?`, `tab_id?` | Clic gauche sur une coordonnée ou un élément référencé. `modifiers` est une combinaison de touches maintenue pendant le clic, par exemple `"shift"` ou `"ctrl+shift"`. |
| `right_click` | `target: Target`, `modifiers?`, `tab_id?` | Clic droit sur une coordonnée ou un élément. |
| `middle_click` | `target: Target`, `modifiers?`, `tab_id?` | Clic du milieu sur une coordonnée ou un élément. |
| `double_click` | `target: Target`, `modifiers?`, `tab_id?` | Double clic gauche sur une coordonnée ou un élément. |
| `triple_click` | `target: Target`, `modifiers?`, `tab_id?` | Triple clic gauche sur une coordonnée ou un élément, ce qui sélectionne généralement une ligne ou un paragraphe. |
| `hover` | `target: Target`, `tab_id?` | Déplace le pointeur au-dessus d'une coordonnée ou d'un élément sans cliquer. |
| `left_click_drag` | `from: CoordinateTarget`, `target: CoordinateTarget`, `tab_id?` | Appuie à `from`, glisse jusqu'à `target` et relâche. |
| `left_mouse_down` | `target: CoordinateTarget`, `tab_id?` | Appuie et maintient le bouton gauche à une coordonnée ; à associer avec `left_mouse_up` pour un glissement personnalisé. |
| `left_mouse_up` | `target: CoordinateTarget`, `tab_id?` | Relâche le bouton gauche à une coordonnée. |
| `mouse_move` | `target: CoordinateTarget`, `tab_id?` | Déplace le pointeur vers une coordonnée. |
| `scroll` | `target: CoordinateTarget`, `scroll_direction`, `scroll_amount?`, `tab_id?` | Fait défiler à une position du viewport. `scroll_direction` vaut `"up"`, `"down"`, `"left"` ou `"right"` ; `scroll_amount` est exprimé en crans de molette, de 1 à 10, 3 par défaut. |
| `scroll_to` | `target: RefTarget`, `tab_id?` | Fait défiler un élément référencé jusqu'à ce qu'il soit visible. |
### Clavier et temporisation
| Membre | Entrée | Description |
| ---------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `text`, `tab_id?` | Saisit une chaîne littérale au niveau du focus actuel. |
| `key` | `text`, `repeat?`, `tab_id?` | Appuie sur une touche ou une combinaison. `text` est une touche unique (`"Enter"`), une combinaison jointe par `+` (`"ctrl+a"`) ou une séquence séparée par des espaces (`"Backspace Backspace"`) ; `repeat` va de 1 à 100, 1 par défaut. |
| `hold_key` | `text`, `duration`, `tab_id?` | Maintient une touche ou une combinaison pendant `duration` secondes, de 0 à 30. |
| `wait` | `duration`, `tab_id?` | Fait une pause de `duration` secondes, de 0 à 30. |
### Lecture de page
| Membre | Entrée | Description |
| --------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_page` | `filter?`, `depth?`, `ref?`, `tab_id?` | Renvoie l'arbre d'accessibilité de la page sous forme de texte, chaque élément étant étiqueté avec une référence telle que `[ref_2]`. Avec `filter` omis, renvoie chaque élément visible ; avec `"interactive"`, uniquement les éléments interactifs visibles ; avec `"all"`, également les éléments hors du viewport. `depth` plafonne la profondeur de l'arbre (minimum 1, 15 par défaut) et `ref` limite la lecture au sous-arbre de cet élément. Plafonnez la sortie à 50 000 caractères et indiquez-le dans le texte ; Claude affine alors avec une `depth` plus petite ou un `ref`. |
| `find` | `query`, `tab_id?` | Recherche les éléments correspondant à une description en langage naturel telle que `"search field"` ou `"add to cart button"`, et renvoie jusqu'à 20 correspondances dans le même format étiqueté que `read_page`. |
| `get_page_text` | `tab_id?` | Renvoie le texte visible de la page sous forme de texte brut, en privilégiant le contenu principal de l'article ; adapté aux articles, à la documentation et aux autres pages riches en texte. |
### Formulaires et fichiers
| Membre | Entrée | Description |
| ------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_input` | `target: RefTarget`, `value`, `tab_id?` | Définit directement la valeur d'un élément de formulaire. `value` est une `string`, un `number` ou un `boolean` ; utilisez un `boolean` pour les cases à cocher et la valeur ou le texte visible d'une option pour les listes de sélection. |
| `file_upload` (désactivé par défaut) | `target: RefTarget`, `paths?`, `document_ids?`, `tab_id?` | Définit les fichiers d'un élément d'entrée de fichier à partir de `paths` sur le système de fichiers de l'exécuteur, de `document_ids` que votre application a préparés, ou des deux ; au moins l'un est requis. Voir [Téléverser des fichiers](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#upload-files). |
### Diagnostics et scripts
| Membre | Entrée | Description |
| ---------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_console` (désactivé par défaut) | `tab_id?` | Renvoie les entrées de console de l'onglet (lignes de journal, d'avertissement et d'erreur) accumulées depuis la dernière lecture, une ligne par entrée. Voir [Lire l'activité de la console et du réseau](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#read-console-and-network-activity). |
| `read_network` (désactivé par défaut) | `tab_id?` | Renvoie les requêtes réseau de l'onglet (méthode, URL, statut, type MIME, chronométrage) depuis la dernière lecture, une ligne par entrée. |
| `javascript_exec` (désactivé par défaut) | `text`, `tab_id?` | Exécute `text` en tant que JavaScript dans le contexte de la page et renvoie la valeur de la dernière expression sous forme de texte. Voir [Activer les membres optionnels](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). |
### Gestion des onglets
| Membre | Entrée | Description |
| ------------ | ----------------- | ------------------------------------------ |
| `new_tab` | (aucune) | Ouvre un onglet et en fait l'onglet actif. |
| `list_tabs` | (aucune) | Indique l'inventaire des onglets. |
| `switch_tab` | `tab_id` (requis) | Fait de `tab_id` l'onglet actif. |
| `close_tab` | `tab_id` (requis) | Ferme `tab_id`. |
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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-management-results).
## 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 dans [Ensembles d'outils client](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets), 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 :
| Champ | Valeur par défaut | Signification |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `true`, sauf `false` pour les quatre [membres optionnels](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) | Indique si le membre est proposé à Claude. |
| `defer_loading` | `false` | Indique si la définition de l'ensemble d'outils est différée pour la recherche d'outils. Doit se résoudre à la même valeur sur chaque membre activé. Avec les quatre membres optionnels laissés désactivés, différer l'ensemble d'outils signifie le définir sur les 27 autres ; voir [Ensembles d'outils client](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets). |
### 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 :
```json
{
"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 voit Claude ; 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 avec un [résultat d'erreur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
### 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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool), 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 ``, 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.
```json
{
"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 contrôlé par la page. 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é, figurant sur une liste d'autorisation, 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 décrite dans [Considérations de sécurité](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#security-considerations), 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 défaillante (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 souhaitez pas voir 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.
```json
{
"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 illustré ici) signale les effets de bord de l'appel. Il contient une entrée `tab_opened` pour chaque onglet ouvert par l'appel et encore ouvert à la fin de celui-ci, dont le `tab_id` doit aussi figurer dans `tabs`, ainsi que les [événements de téléchargement](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#report-downloads). Omettez ce champ lorsqu'il n'y a rien à signaler ; un tableau vide est rejeté.
* N'envoyez le bloc que sur les résultats qui répondent à un appel d'un membre du navigateur, au plus une fois par `tool_result`, et jamais sur un résultat avec `is_error: true`. Pour indiquer « aucun état d'onglet à signaler », omettez le bloc.
* L'API convertit `tabs`, ainsi que les éventuelles entrées de téléchargement de `state_changes`, en texte destiné à Claude. Les deux sections suivantes et [Signaler les téléchargements](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#report-downloads) présentent ce texte.
**Vous 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 ces limites 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`.
Les titres et les URL des onglets proviennent de la page et sont insérés dans le texte que Claude lit. Ils constituent donc une surface d'attaque par « prompt injection » (injection de prompt). L'API reproduit les URL des onglets telles quelles : assainissez les URL fournies par les pages avant de remplir `tabs`. En revanche, l'API échappe les guillemets doubles et les barres obliques inverses des titres lors de leur rendu. N'échappez donc pas les titres au préalable, sinon ils parviendront à Claude doublement échappés. Il reste utile de tronquer ou d'écarter les titres suspects. Les champs `url`, `path` et `error` d'une entrée de téléchargement sont eux aussi insérés dans le texte que Claude lit : traitez-les également comme non fiables. L'API les met entre guillemets et les échappe comme les titres. Les limites de longueur et de caractères imposées par l'API constituent un minimum, pas une protection.
### 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`.
| Membre | Texte que Claude voit |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `switch_tab` | `Switched to tab {tab_id}`, tiré du `input.tab_id` de l'appel |
| `close_tab` | `Closed tab {tab_id}`, tiré du `input.tab_id` de l'appel |
| `new_tab` | `Created new tab with tab_id: {tab_id}, URL: {url}. It is now the current tab.`, tiré de l'entrée marquée `active: true` |
| `list_tabs` | `Available tabs:` suivi d'une ligne par onglet, ou `No tabs available` lorsque `tabs` est vide |
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 :
```text wrap
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` :
```json
{
"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 redirige ensuite ; 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, afin que Claude reçoive le nouvel état sans appel `list_tabs` distinct :
```text wrap
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` (par exemple, un résultat `screenshot` ne contenant qu'une image). Rien n'est rendu ni mémorisé pour ce résultat. Le contexte des onglets apparaît sur le prochain résultat qui contient à la fois du texte et un bloc `browser_state`. Incluez donc un court bloc de texte à côté de l'image si vous voulez que Claude voie un changement d'onglet sur ce même résultat. L'exception est un résultat dont le bloc signale un [événement de téléchargement](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#report-downloads) : l'API ajoute alors les lignes de téléchargement sous forme de bloc de texte, et le pied de page les suit comme sur tout résultat contenant du texte.
* Un résultat dont la liste `tabs` est vide, pour un appel sans `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 ainsi qu'un bloc dont les `state_changes` nomment l'onglet ouvert, en marquant l'onglet que votre exécuteur a laissé actif :
```json
{
"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'onglet 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 :
| `type` | Champs | Quand l'envoyer |
| -------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `download_started` | `download_id`, `url` | Sur le résultat de l'appel pendant lequel le téléchargement a commencé. `url` est l'URL finale depuis laquelle le fichier est servi, après redirections. |
| `download_completed` | `download_id`, `url`, `path?`, `size_bytes?` | Sur le résultat de l'appel ultérieur en cours d'exécution lorsque le téléchargement se termine. N'incluez `path` que lorsqu'un autre outil du même environnement (par exemple, l'[outil bash](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/bash-tool) ou `file_upload`) peut y lire le fichier ; sinon `download_id` est le seul identifiant du téléchargement. |
| `download_failed` | `download_id`, `url`, `error?` | Lorsque le téléchargement échoue ou est annulé, avec la raison dans `error` si le navigateur en fournit une. |
L'API convertit chaque entrée en une ligne de texte pour Claude, dans l'ordre où les entrées apparaissent. Elle ajoute ces lignes après le texte du résultat, séparées par une ligne vide, et avant l'éventuel pied de page Tab Context. Tous les types de résultats de membres contiennent ces lignes, y compris les résultats `zoom` et de gestion des onglets. Un résultat sans bloc `text` les reçoit dans un bloc de texte distinct. Chaque ligne indique le `download_id` et l'`url`, ainsi que `path` et `size_bytes` (pour `download_completed`) ou `error` (pour `download_failed`) lorsque vous les envoyez. Vous n'avez pas besoin de décrire le téléchargement dans votre propre texte. L'API met `url`, `path` et `error` entre guillemets doubles et échappe les guillemets doubles et les barres obliques inverses qu'ils contiennent. N'échappez donc pas ces valeurs au préalable.
Par exemple, un clic sur « Download price list (CSV) » (`ref_8`) dans l'onglet Pricing déclenche un téléchargement. Le résultat du clic contient donc une entrée `download_started` avec le `download_id` `"dl-1"` et l'URL du fichier. Le téléchargement se termine pendant l'exécution d'un appel `screenshot` ultérieur. Le `content` de ce résultat contient alors l'image, un bloc de texte tel que `Screenshot captured.`, et ce bloc `browser_state` qui signale la fin du téléchargement sous le même `download_id` :
```json
{
"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
}
]
}
```
Claude voit `Screenshot captured.` suivi d'une ligne vide et d'une ligne comme celle-ci :
```text wrap
Download completed with download_id: dl-1, URL: "https://example.com/pricing/price-list.csv". Saved to "/home/user/downloads/price-list.csv". Size: 48213 bytes.
```
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 sous forme de résultat d'erreur ordinaire : `is_error: true`, un contenu textuel 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 :
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01LeUTyqkhRxBFq1QTG3pkwN",
"toolset_name": "browser",
"is_error": true,
"content": "Error: Navigation refused. Only http and https URLs are allowed."
}
```
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"toolset_name": "browser",
"is_error": true,
"content": "Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references."
}
```
```json
{
"type": "tool_result",
"tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
"toolset_name": "browser",
"is_error": true,
"content": "Error: javascript_exec is not enabled in this environment."
}
```
Lorsque le `left_click` sur `ref_3` de [Actions par lot](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#batch-actions) échoue avec l'erreur de référence obsolète montrée précédemment, les appels `type` et `key` qui le suivent reçoivent chacun ce résultat :
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
"toolset_name": "browser",
"is_error": true,
"content": "Not executed: an earlier action in this turn failed."
}
```
### 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é.
| Requête | Pourquoi elle échoue et que faire |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Une option ou une combinaison que l'entrée du toolset n'accepte pas, par exemple un `name`, `strict: true`, `input_examples`, `defer_loading` sur l'entrée elle-même, une clé `configs` qui n'est pas un nom de membre, un champ autre que `enabled` ou `defer_loading` dans la valeur `configs` d'un membre ([Configurer le toolset](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)), des membres activés dont les valeurs `defer_loading` diffèrent ([Configurer le toolset](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)), un `configs` qui ne laisse aucun membre activé, un appelant d'exécution de code dans `allowed_callers`, l'ancien en-tête bêta `fine-grained-tool-streaming-2025-05-14` sur la requête, un `tool_choice` de type `tool` nommant `browser` ou un membre, ou une seconde entrée de toolset navigateur ou un autre outil nommé `browser` | Ceux-ci ne sont pas pris en charge sur les toolsets clients. Consultez [Toolsets clients](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets) pour chaque règle et son alternative. |
| Un `tool_result` répondant à un appel de membre sans `"toolset_name": "browser"` ou avec une valeur différente, ou `toolset_name` sur un résultat dont l'appel n'était pas un appel de membre | Répétez `toolset_name` exactement sur les résultats de membre, et uniquement sur ceux-ci. |
| Un `tool_use` de membre d'un tour antérieur sans `tool_result` correspondant | Répondez à chaque appel de membre, y compris ceux que vous n'avez pas exécutés après un échec. |
| Un bloc de contenu autre que `text`, `image` ou `browser_state` dans un résultat de membre | Les résultats de membre n'acceptent que ces trois types de blocs. |
| Un bloc `browser_state` qui enfreint une règle de [Suivre les onglets avec `browser_state`](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), par exemple un bloc sur un résultat `is_error: true` ou sur un résultat qui ne répond pas à un appel de membre du navigateur, plus d'un dans un résultat, un `tabs` non vide sans exactement une entrée `active: true`, un `tab_id` en double, un tableau `state_changes` vide, un `tab_opened` dont le `tab_id` n'est pas dans `tabs`, deux changements d'état pour un même `download_id` ou un champ de changement d'état que son `type` ne déclare pas ([Rapporter les téléchargements](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#report-downloads)), ou un champ dépassant ses limites | Corrigez le bloc. « Rien à rapporter » s'exprime en omettant le bloc ou le champ `state_changes`, jamais par une valeur vide. |
| Un résultat `new_tab`, `switch_tab`, `close_tab` ou `list_tabs` réussi dont le `content` n'est pas exactement un bloc `browser_state`, ou un résultat `new_tab` sans exactement un `tab_opened` correspondant à l'onglet actif | L'API rend ces résultats à partir du bloc et en a besoin sous cette forme exacte ; consultez [Résultats de gestion des onglets](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#tab-management-results). |
| Une `image` dans un résultat dépassant les [limites de taille d'image](https://platform.claude.com/docs/fr/build-with-claude/vision#evaluate-image-size) de votre modèle, ou dépassant la limite par image plus stricte qui s'applique dès que la requête contient [plus de 20 images](https://platform.claude.com/docs/fr/build-with-claude/vision#request-limits), en comptant les captures d'écran et les images `zoom` des résultats antérieurs | L'API ne réduit pas la taille des images de toolset. Redimensionnez les captures d'écran avant de les renvoyer ([Dimensionner les captures d'écran pour respecter les limites d'image](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)). |
| Un `model` qui ne prend pas en charge `browser_toolset_20260801` | Consultez [Compatibilité](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/browser-use-tool#compatibility) pour les modèles pris en charge. |
## Limitations
* **Disponibilité par plateforme :** l'utilisation du navigateur est disponible sur la Claude API et [Google Cloud](https://platform.claude.com/docs/fr/build-with-claude/claude-on-vertex-ai).
* **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 clients](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference#client-toolsets)).
* **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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#understand-computer-use-limitations) de l'outil d'utilisation de l'ordinateur), et ses recommandations sous [Optimiser les performances du modèle avec le prompting](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting), [Gérer l'historique des captures d'écran](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#manage-screenshot-history) et [Suivre les bonnes pratiques d'implémentation](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/computer-use-tool#follow-implementation-best-practices) (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](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/overview#pricing). Lorsque vous utilisez l'outil d'utilisation du navigateur :
**Surcoût lié à la définition de l'ensemble d'outils :** Déclarer `browser_toolset_20260801` avec ses membres par défaut ajoute environ 6 600 tokens d'entrée à une requête (environ 6 670 sur Claude Sonnet 5 et environ 6 610 sur les autres modèles pris en charge), ce qui couvre les définitions des outils membres et l'invite système d'utilisation d'outils. L'activation des quatre membres optionnels ajoute environ 880 tokens, 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 tokens](https://platform.claude.com/docs/fr/build-with-claude/token-counting).
**Consommation de tokens supplémentaire :**
* Les captures d'écran et les images de zoom renvoyées dans les résultats d'outils, facturées comme entrée d'image (voir la [tarification de la vision](https://platform.claude.com/docs/fr/build-with-claude/vision#evaluate-image-size))
* 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
Si vous utilisez également l'outil d'utilisation de l'ordinateur, l'outil bash, l'outil d'édition de texte ou vos propres outils en parallèle de l'utilisation du navigateur, ces outils ont leurs propres coûts en tokens, tels que documentés sur leurs pages respectives.
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](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention) pour les durées de conservation et l'éligibilité selon les fonctionnalités.
## Étapes suivantes
Partez du pilote d'un partenaire, ou écrivez le vôtre en Python ou en TypeScript. Le SDK exécute la boucle et les vérifications que vous configurez.
Donnez à Claude le contrôle d'un bureau complet lorsque la tâche sort du navigateur ; ses recommandations d'implémentation s'appliquent également aux exécuteurs de navigateur.
Formatez les blocs `tool_result`, renvoyez des images et des erreurs, et poursuivez la conversation.
Parcourez les toolsets client et tous les autres outils fournis par Anthropic, avec leurs versions et leurs paramètres.