---
title: Strumento browser use
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool
description: Consenti a Claude di navigare, leggere e interagire con le pagine web nel tuo ambiente browser con lo strumento di uso del browser.
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
---
**Inizia con i toolset dell'SDK:** gli SDK Python e TypeScript dispongono di una classe toolset per il browser, in beta. Parti dall'[integrazione di un partner](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-sdk#partner-integrations), oppure consulta [Uso del browser e del computer con i toolset dell'SDK](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-sdk). Usa questa pagina come riferimento dello strumento, o quando gestisci tu stesso le chiamate agli strumenti.
Lo strumento di uso del browser consente a Claude di navigare, leggere e interagire con le pagine web in un browser eseguito dalla tua applicazione. Claude lavora con la pagina sia attraverso la sua struttura (l'"accessibility tree" (albero di accessibilità), gli elementi, i moduli e le schede) sia attraverso screenshot e coordinate del viewport.
Lo strumento è un ["client toolset" (set di strumenti client)](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets) definito da Anthropic: una voce `browser_toolset_20260801` in `tools` fornisce a Claude 27 "member tools" (strumenti membro) per impostazione predefinita, come `navigate`, `read_page`, `left_click` e `screenshot`, più altri quattro quando li [abiliti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). La tua applicazione esegue ogni chiamata sulla propria automazione del browser; nulla viene eseguito dal lato di Anthropic. Lo strumento non è attualmente disponibile in [Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/tools).
Scegli l'uso del browser quando l'attività resta all'interno delle pagine web e richiede di agire su di esse, o quando le pagine costruiscono il loro contenuto con JavaScript. Quando un'attività richiede un intero desktop, usa lo [strumento di uso del computer](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool), che funziona solo tramite screenshot e coordinate. Per leggere pagine a cui puoi indirizzare Claude, o per trovare fonti sul web, lo [strumento web fetch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-fetch-tool) e lo [strumento di ricerca web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool) sono più leggeri. Sono [strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools) che l'API esegue per te, senza alcun browser da gestire.
Con browser use, Claude legge e agisce su pagine web reali, quindi tutto ciò che una pagina fornisce è input non attendibile e le azioni che Claude compie possono avere effetti reali. Consulta [Considerazioni sulla sicurezza](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#security-considerations) prima di distribuire in produzione.
## Avvio rapido
Lo strumento browser use è disponibile sulla Claude API e su [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai): aggiungi una voce di tipo `browser_toolset_20260801`, senza `name`, all'array `tools` di una richiesta [Messages API](https://platform.claude.com/docs/it/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 prima risposta di Claude termina con `stop_reason: "tool_use"` e contiene uno o più blocchi `tool_use` membro, ciascuno dei quali indica uno strumento membro in `name` e riporta `"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
}
```
Il tuo "executor" (esecutore), ovvero la parte della tua applicazione che controlla il browser e produce i risultati degli strumenti, esegue `navigate`, poi `read_page`. La tua applicazione restituisce un `tool_result` per blocco nella richiesta successiva, ripetendo `toolset_name` su ciascuno. Il risultato di `navigate` riporta la scheda caricata in un blocco `browser_state`; il risultato di `read_page` è testo in cui ogni elemento porta un riferimento:
```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 ora possiede riferimenti su cui può agire, quindi nel turno successivo può fare clic su `ref_2` per aprire la pagina introduttiva, senza bisogno di individuare prima il link in uno screenshot.
## Come funziona browser use
L'uso del browser viene eseguito come un "agent loop" (ciclo dell'agente) nella tua applicazione: Claude restituisce chiamate agli strumenti membro, il tuo executor le esegue sul browser e tu restituisci i risultati finché Claude non risponde con del testo.
* Aggiungi la voce `browser_toolset_20260801`, e facoltativamente altri strumenti, alla tua richiesta API.
* Includi un prompt utente che richieda di lavorare con pagine web, ad esempio "Apri example.com/docs e dimmi come iniziare."
* Claude restituisce uno o più blocchi `tool_use` in un singolo turno dell'assistente; più blocchi in un turno formano un'azione batch, ad esempio `left_click`, poi `type`, poi `key`.
* Il `name` di ogni blocco è il nome del membro, ciascuno riporta `"toolset_name": "browser"` e `input` contiene solo i parametri di quel membro, senza alcun campo `action`. Lo `stop_reason` della risposta è `tool_use`.
* Itera su ogni blocco `tool_use` in `response.content` (non dare per scontato che ce ne sia esattamente uno) ed eseguili in sequenza, nell'ordine in cui compaiono, perché le chiamate successive di solito dipendono da quelle precedenti.
* Restituisci un `tool_result` per ogni blocco in un nuovo messaggio `user`, associato tramite `tool_use_id`, e ripeti `"toolset_name": "browser"` su ciascuno. Ogni chiamata deve ricevere una risposta, altrimenti la richiesta successiva viene rifiutata.
* Se una chiamata fallisce, restituisci `is_error: true` con una descrizione testuale per quel blocco, quindi applica la regola di interruzione descritta in [Azioni batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#batch-actions) a ogni blocco successivo del turno.
* Claude legge i risultati (testo della pagina, alberi di accessibilità, screenshot, stato delle schede) e, se ha bisogno di altro, restituisce ulteriori chiamate ai membri, riportandoti al passaggio 3.
* Altrimenti, restituisce una risposta testuale all'utente.
Ecco uno scheletro del passaggio di chiamata degli strumenti di quel ciclo, in due parti. Nella prima, handler membro fittizi sostituiscono la tua automazione del browser. Cinque membri (`navigate`, `read_page`, `left_click`, `type` e `screenshot`) restituiscono il testo, o per `screenshot` il blocco immagine, che diventa il contenuto del risultato, e il dispatcher solleva un errore per qualsiasi membro che non implementa.
```python Python
# Dati immagine segnaposto; un executor reale cattura il viewport e restituisce i byte 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):
# Un target è un riferimento a un elemento da read_page o find, oppure una coordinata del viewport
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 risponde con un blocco immagine anziché testo: restituisci la lista di contenuti del risultato
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()
# Gestisci le altre azioni secondo necessità
raise ValueError(f"Unknown or unimplemented member: {name}")
```
```typescript TypeScript
// Dati immagine segnaposto; un executor reale cattura il viewport come byte 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 risponde con un blocco immagine anziché testo
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 è un riferimento a un elemento da read_page o una coordinata del viewport
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();
}
// Gestisci altre azioni secondo necessità
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Dati immagine segnaposto; un executor reale cattura il viewport e restituisce i byte 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 è {"type": "ref", "ref": "ref_1"} oppure {"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 risponde con un blocco immagine anziché testo: restituisci la lista dei contenuti del risultato
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(),
// Gestisci altre azioni secondo necessità
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG sostituisce una cattura reale: un executor restituisce il
// viewport come dati PNG codificati in base64.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// textContent racchiude il testo come contenuto 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 restituisce un blocco immagine anziché testo.
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 è un riferimento a un elemento da read_page oppure una coordinata del 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
// Gestisci le altre azioni secondo necessità
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Raggiunto quando l'input di un membro manca di un campo o un campo ha il tipo errato
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 è {"type": "ref", "ref": "ref_1"} oppure {"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());
// Gestisci altre azioni secondo necessità
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Segnaposto per i byte PNG reali; un executor reale cattura il viewport
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
{
// Un target è un riferimento a un elemento da read_page o find, oppure una coordinata in pixel del viewport
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 risponde con un blocco immagine anziché testo, quindi restituisci la lista dei contenuti del risultato
$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(),
// Gestisci le altre azioni secondo necessità
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Dati immagine segnaposto; un executor reale cattura il viewport come 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 è un riferimento a un elemento (da read_page o find) o una coordinata
click(input[:target])
when "type"
type_text(input[:text])
when "screenshot"
capture_screenshot
# Gestisci altre azioni secondo necessità
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
La seconda parte esegue un batch in ordine, invia ogni blocco a quegli handler, ripete `toolset_name` su ogni risultato e applica la regola di arresto di [Azioni batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#batch-actions), trasformando un errore dell'handler in un risultato di errore. Il ciclo di campionamento che la chiama è quello mostrato in [Comprendere il ciclo dell'agente](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop), con il toolset del browser in `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:
# È dichiarato solo il toolset del browser; instrada qui altri strumenti se li aggiungi
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:
# Una stringa o una lista di blocchi di contenuto; un executor reale aggiunge anche un
# blocco browser_state ai risultati di navigazione e gestione delle schede
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") {
// Questo esempio dichiara solo il toolset del browser; instrada qui altri strumenti
// se li aggiungi.
continue;
}
if (failed) {
// Un batch si ferma al primo errore; rispondi alle azioni successive come non eseguite
toolResults.push(browserResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Una stringa o una lista di blocchi immagine; un executor reale aggiunge anche un
// blocco browser_state ai risultati di navigazione e gestione delle schede
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")
{
// Questo esempio dichiara solo il toolset del browser; instrada qui altri strumenti
// se li aggiungi.
continue;
}
if (failed)
{
// Un batch si ferma al primo errore; rispondi alle azioni successive senza eseguirle
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "browser",
}
);
continue;
}
try
{
// Una stringa o una lista di blocchi di contenuto; un executor reale aggiunge anche un
// blocco browser_state ai risultati di navigazione e gestione delle schede
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 costruisce il risultato per un'azione del browser. A differenza di un
// normale risultato di strumento, deve riportare il nome del toolset. Un executor reale inoltre
// aggiunge un blocco browser_state ai risultati di navigazione e gestione delle schede.
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 esegue in ordine le azioni del browser nella risposta di Claude e
// costruisce un tool_result per ogni blocco tool_use. Dopo il primo errore salta
// il resto: Claude le ha pianificate presumendo che le azioni precedenti fossero riuscite.
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:
// Questo esempio dichiara solo il toolset del browser; instrada qui altri strumenti se li aggiungi.
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()) {
// Questo esempio dichiara solo il toolset del browser; instrada qui altri strumenti se li aggiungi.
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 executor reale aggiunge anche un blocco browser_state ai risultati di navigazione e
// di gestione delle schede; vedi "Traccia le schede con browser_state" in questa pagina.
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) {
// Questo esempio dichiara solo il toolset del browser; instrada qui altri strumenti se li aggiungi.
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 batch si ferma al primo errore; alle azioni rimanenti si risponde senza eseguirle
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Un executor reale restituisce anche un blocco browser_state nei risultati di navigazione e gestione delle schede
$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."
# Esegui in ordine le azioni del browser nella risposta di Claude e crea un
# tool_result per ogni blocco tool_use. Dopo il primo errore, salta il resto:
# Claude le ha pianificate presumendo che le azioni precedenti fossero riuscite.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Questo esempio dichiara solo il toolset del browser; instrada qui altri strumenti
# se li aggiungi.
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
# Una String, o blocchi di contenuto per uno screenshot. Un executor reale aggiunge anche
# un blocco browser_state ai risultati di navigazione e gestione delle schede.
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
```
Invia ogni blocco in base alla coppia (`toolset_name`, `name`) anziché solo a `name`, perché uno strumento personalizzato nella stessa richiesta potrebbe condividere il nome di un membro; [Client toolsets](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets) descrive le parti di questo contratto che entrambi i toolset condividono. Se Claude indica un membro che il tuo executor non implementa, o uno che hai disabilitato, rispondi a quel blocco con un [risultato di errore](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor) anziché scartarlo.
Quando trasmetti la risposta in streaming, l'`input` di ogni membro arriva come un unico `input_json_delta` completo anziché come frammenti, quindi attendi che il turno finisca prima di eseguire il batch.
### Azioni batch
Un turno con più chiamate ai membri è un'azione batch: esegui le chiamate nell'ordine in cui appaiono, fermati al primo fallimento e rispondi a ogni chiamata successiva con `is_error: true` e il testo esatto `Not executed: an earlier action in this turn failed.` Un batch usa la stessa forma di risposta dell'[uso parallelo degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/parallel-tool-use); la differenza è che esegui i blocchi in ordine anziché in modo concorrente. Qui Claude fa clic sulla casella di ricerca trovata in precedenza, digita una query e preme Invio in un unico turno:
```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" }
}
]
}
```
La tua applicazione restituisce tre blocchi `tool_result` in un unico messaggio `user`, ciascuno con `toolset_name` e una breve conferma testuale come `Clicked element ref_3.` Premere Invio carica una pagina di risultati, quindi il risultato di `key` contiene anche un blocco `browser_state` con l'URL aggiornato della scheda ([Contesto della scheda su altri risultati](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). Se invece il clic fosse fallito, il suo risultato conterrebbe il tuo testo di errore e gli altri due risultati conterrebbero il testo di arresto, come mostrato in [Restituire errori dal tuo executor](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
Non è necessario restituire uno screenshot dopo ogni chiamata. Claude in genere termina un batch con una chiamata di osservazione (`screenshot`, `read_page` o `get_page_text`), e la tua applicazione può anche allegare la propria osservazione, come uno screenshot aggiornato o un albero di accessibilità, come blocco di contenuto aggiuntivo sull'ultimo risultato del batch per risparmiare un round trip. Poiché un risultato di gestione delle schede deve essere esattamente un blocco `browser_state`, allegalo all'ultimo risultato che non sia una chiamata di gestione delle schede.
Se il tuo executor può eseguire solo una chiamata per round trip, imposta `disable_parallel_tool_use` su `true` in `tool_choice` e Claude restituirà al massimo una chiamata a un membro per turno, al costo di più round trip ([Disabilitare l'uso parallelo degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)). Il resto del contratto descritto in [Azioni batch per lo strumento computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#batch-actions) si applica anche qui, incluso un `tool_result` per ogni `tool_use` nel messaggio `user` successivo, tranne due cose: il testo di arresto e ciò che contiene il `content` di un risultato riuscito. Il contenuto del risultato segue invece [Strumenti membro](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#member-tools) in questa pagina: un risultato di `new_tab`, `switch_tab`, `close_tab` o `list_tabs` è esattamente un blocco `browser_state` senza testo né immagine ([Risultati della gestione delle schede](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-management-results)), e il risultato di qualsiasi altro membro può aggiungere un blocco `browser_state` al suo testo o immagine ([Contesto della scheda su altri risultati](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). Dove hanno effetto i breakpoint della cache all'interno di un batch è descritto nella riga `cache_control` dei [Parametri dello strumento](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#tool-parameters) dello strumento computer use.
### Target e coordinate
Gli strumenti membro che agiscono su una posizione accettano un oggetto `target`, che è una coordinata in pixel del viewport oppure un riferimento a un elemento restituito da `read_page` o `find`. Le tabelle di [Strumenti membro](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#member-tools) scrivono `Target` per un parametro che accetta entrambe le forme.
| Forma | `target.type` | Campi | Accettato da |
| ------------------ | -------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CoordinateTarget` | `"coordinate"` | `x`, `y` (interi, pixel del viewport) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `left_click_drag` (`from` e `target`), `left_mouse_down`, `left_mouse_up`, `mouse_move`, `scroll` |
| `RefTarget` | `"ref"` | `ref` (un riferimento a un elemento come `"ref_2"`) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `scroll_to`, `form_input`, `file_upload` |
**Le coordinate sono pixel del viewport**, lo spazio di pixel di uno `screenshot` a viewport intero con l'origine in alto a sinistra della pagina renderizzata; non c'è alcun desktop circostante né cornice della finestra. Il toolset non dichiara dimensioni del display e Claude deduce la dimensione del viewport dagli screenshot che restituisci, quindi mantienili di una dimensione costante. Uno `zoom` non cambia il sistema di riferimento, quindi la sua `region` e qualsiasi coordinata che Claude emette dopo aver visto l'immagine ingrandita sono ancora pixel del viewport intero.
**Gli screenshot devono rispettare i limiti delle immagini.** L'API non ridimensiona le immagini del toolset: uno screenshot o un'immagine di zoom che supera i [limiti di dimensione delle immagini](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size) del tuo modello, o il limite per immagine più restrittivo che si applica quando una richiesta contiene [più di 20 immagini](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits), viene rifiutato. Ridimensiona prima di restituire e riporta le coordinate di Claude alla scala originale moltiplicandole per l'inverso del tuo fattore prima di inviarle ([Dimensionare gli screenshot per rispettare i limiti delle immagini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
**I riferimenti agli elementi provengono da `read_page` e `find`.** Ogni elemento nel loro output porta un tag come `[ref_2]`, come nel risultato dell'Avvio rapido:
```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 restituisce un riferimento come target `{"type": "ref", "ref": "ref_2"}` in una successiva chiamata di clic, `hover`, `scroll_to`, `form_input` o `file_upload`, oppure come parametro `ref` su `read_page` per leggere un sottoalbero. Il tuo executor assegna i riferimenti, mantiene la mappatura da ciascuno al nodo sottostante (un ID di nodo di accessibilità, un selettore memorizzato o equivalente) e agisce su quel nodo quando un riferimento ritorna.
I riferimenti sono limitati alla scheda che li ha prodotti e restano validi finché quella scheda non naviga o il suo DOM non cambia in modo sostanziale. L'API non può rilevare un riferimento obsoleto o sconosciuto, quindi quando Claude passa un riferimento che il tuo executor non riconosce più, restituisci un risultato di errore come `Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.` Claude quindi rilegge la pagina. Non rinumerare i riferimenti che hai già distribuito per una scheda finché questa non naviga, perché ciò invalida silenziosamente i riferimenti che Claude possiede ancora.
Claude usa entrambi gli stili di targeting e passa dall'uno all'altro in base a ciò che la pagina espone; il tuo prompt e ciò che il tuo executor restituisce orientano la scelta:
* **Preferisci i riferimenti dove la pagina ha un albero di accessibilità utilizzabile.** Un riferimento sopravvive agli spostamenti di layout e ai reflow che rendono fragili le coordinate in pixel, e consente a Claude di agire su controlli difficili da colpire con un puntatore.
* **Ripiega sulle coordinate per i contenuti che l'albero non descrive.** Interfacce renderizzate su canvas, video incorporati o superfici di desktop remoto, liste fortemente virtualizzate ed elementi all'interno di iframe cross-origin spesso non hanno un nodo utile, quindi Claude lavora a partire da `screenshot` e `zoom` e fa clic tramite coordinata; il tuo executor determina in quale frame ricade una coordinata.
* **Limita l'ambito delle letture e leggi l'albero prima di fare uno screenshot.** Su pagine grandi, `read_page` con `filter: "interactive"` o con il `ref` di un contenitore restituisce un sottoalbero mirato, e la lettura dell'albero di una pagina tipica spesso costa meno token di input di uno screenshot, fornendo al contempo a Claude riferimenti su cui può agire immediatamente. Gli screenshot restano l'osservazione giusta quando contano il layout visivo, le immagini o lo stato di rendering.
## Considerazioni sulla sicurezza
Browser use comporta rischi che le funzionalità API standard non hanno, perché Claude legge e agisce su contenuti del web aperto, dove qualsiasi pagina può contenere testo scritto per manipolarlo.
Per ridurre questi rischi, adotta precauzioni come le seguenti:
1. Esegui il browser e il tuo executor in un container o una macchina virtuale dedicati con privilegi minimi, un profilo nuovo che non contenga credenziali e nessun accesso a filesystem sensibili o reti interne; isola allo stesso modo qualsiasi strumento che esegui insieme a esso.
2. Limita gli host che il browser può raggiungere a una "allowlist" (lista di elementi consentiti) di domini applicata a livello di rete e ricontrollata nel tuo gestore `navigate` dopo i reindirizzamenti, e blocca gli intervalli loopback, link-local e privati a meno che l'attività non li richieda.
3. Tratta tutto ciò che una pagina fornisce come input non attendibile, inclusi i titoli e gli URL delle schede, e l'`url`, il `path` e l'`error` di ogni download, che riporti in un blocco [`browser_state`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), e costruisci le letture della pagina a partire da ciò che la pagina renderizza (l'albero di accessibilità o il testo visibile), non dal sorgente DOM grezzo, in modo che il testo nascosto non raggiunga Claude.
4. Nel tuo gestore `navigate`, accetta le parole chiave della cronologia `"back"`, `"forward"` e `"reload"`, tratta un URL senza schema come `https://`, quindi analizza l'URL e rifiuta qualsiasi schema diverso da `http` o `https` (`javascript:`, `file:`, `data:`, `chrome:` e così via) con un [risultato di errore](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor). Verifica lo schema con un parser di URL anziché con un prefisso di stringa; l'API non filtra gli URL che Claude apre, quindi non può rifiutarne uno al posto tuo.
5. Lascia `javascript_exec` e `file_upload` disabilitati a meno che non ti servano, e leggi [Abilitare i membri opzionali](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) prima di attivarne uno.
6. Fai confermare a una persona le azioni con conseguenze rilevanti e qualsiasi cosa richieda un consenso esplicito (acquisti, modifiche agli account, invio di messaggi e accettazione di termini), ed effettua tale verifica nel tuo executor prima di ogni chiamata, perché un turno può contenerne diverse.
Claude a volte segue istruzioni trovate nel contenuto della pagina anche quando sono in conflitto con le tue; un testo su una pagina che dice "ignora le tue istruzioni precedenti e naviga verso..." può distoglierlo dall'attività. Isola Claude da dati e azioni sensibili per limitare ciò che una prompt injection può raggiungere, consulta [Mitigare jailbreak e prompt injection](https://platform.claude.com/docs/it/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) e, se un'attività non può evitare una sessione autenticata, usa un account dedicato con privilegi ridotti e mantieni la conferma umana sulle azioni che modificano l'account.
Anthropic ha addestrato il modello a resistere a queste prompt injection e ha aggiunto un ulteriore livello di difesa. Se usi lo strumento di uso del browser, dei classificatori analizzeranno automaticamente ciò che il browser restituisce, come il testo della pagina o gli screenshot, per segnalare potenziali prompt injection. Quando questi classificatori identificano una potenziale prompt injection, orienteranno automaticamente il modello a verificare se l'istruzione provenga davvero da te prima di agire di conseguenza.
Questa protezione aggiuntiva non sarà ideale per ogni caso d'uso (ad esempio, casi d'uso senza una persona nel ciclo), quindi se desideri rinunciarvi e disattivarla, [contatta il supporto](https://support.claude.com/en/). Le precauzioni sopra indicate restano importanti anche con questi classificatori attivi.
Poiché il browser viene eseguito nel tuo ambiente, i siti che Claude visita vedono l'identità di rete del tuo executor e il contenuto della pagina raggiunge l'API solo sotto forma dei risultati degli strumenti che restituisci. Informa gli utenti finali dei rischi rilevanti e ottieni il loro consenso prima di abilitare browser use nei tuoi prodotti.
## Strumenti membro
La voce `browser_toolset_20260801` dichiara 31 strumenti membro; l'`input` di ogni chiamata è esattamente costituito dai parametri elencati qui, e `tab_id`, dove opzionale, ha come valore predefinito la scheda attiva. `Target`, `CoordinateTarget` e `RefTarget` sono le forme descritte in [Target e coordinate](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates). Quattro membri (`javascript_exec`, `file_upload`, `read_console` e `read_network`) sono disabilitati per impostazione predefinita e appaiono solo quando li [abiliti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). I limiti di input e le convenzioni di output indicati nella riga di ogni membro sono dichiarati a Claude, non applicati dall'API, quindi valida gli input (incluse le coordinate rispetto al tuo viewport) e applica le convenzioni nel tuo executor.
Solo `screenshot` e `zoom` richiedono un [blocco `image`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools) nel loro risultato, e i quattro membri di gestione delle schede (`new_tab`, `list_tabs`, `switch_tab` e `close_tab`) restituiscono esattamente un blocco `browser_state` (vedi [Risultati della gestione delle schede](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-management-results)). Ogni altro membro restituisce un blocco `text`: una breve conferma come `Clicked element ref_2.` oppure l'output del membro. Qualsiasi risultato diverso da un risultato di gestione delle schede può anche contenere un blocco `image`, in genere uno screenshot scattato dopo l'azione, in modo che Claude veda l'esito senza una chiamata `screenshot` separata; [Azioni batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#batch-actions) mostra dove allegarne uno in un batch. Un `tool_result` membro può contenere solo blocchi di contenuto `text`, `image` e `browser_state`.
### Navigazione e acquisizione
| Membro | Input | Descrizione |
| ------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `navigate` | `url`, `tab_id?` | Carica un URL `http` o `https`, oppure spostati nella cronologia con `"back"`, `"forward"` o `"reload"`. Tratta un URL senza schema come `https://` e rifiuta qualsiasi altro schema con un risultato di errore. Restituisci una breve conferma, più un blocco `browser_state` quando l'URL o il titolo della scheda sono cambiati. |
| `screenshot` | `tab_id?` | Acquisisci il viewport e restituisci un blocco `image`. |
| `zoom` | `region`, `tab_id?` | Restituisci un'`image` ritagliata e ingrandita di `region`, indicata come `[x0, y0, x1, y1]` in pixel del viewport, per un'ispezione più ravvicinata di testo o controlli piccoli. |
### Puntatore
| Membro | Input | Descrizione |
| ----------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `left_click` | `target: Target`, `modifiers?`, `tab_id?` | Clic sinistro su una coordinata o un elemento referenziato. `modifiers` è una combinazione di tasti tenuta premuta durante il clic, ad esempio `"shift"` o `"ctrl+shift"`. |
| `right_click` | `target: Target`, `modifiers?`, `tab_id?` | Clic destro su una coordinata o un elemento. |
| `middle_click` | `target: Target`, `modifiers?`, `tab_id?` | Clic centrale su una coordinata o un elemento. |
| `double_click` | `target: Target`, `modifiers?`, `tab_id?` | Doppio clic sinistro su una coordinata o un elemento. |
| `triple_click` | `target: Target`, `modifiers?`, `tab_id?` | Triplo clic sinistro su una coordinata o un elemento, che in genere seleziona una riga o un paragrafo. |
| `hover` | `target: Target`, `tab_id?` | Sposta il puntatore sopra una coordinata o un elemento senza fare clic. |
| `left_click_drag` | `from: CoordinateTarget`, `target: CoordinateTarget`, `tab_id?` | Premi in `from`, trascina fino a `target` e rilascia. |
| `left_mouse_down` | `target: CoordinateTarget`, `tab_id?` | Premi e tieni premuto il pulsante sinistro su una coordinata; abbinalo a `left_mouse_up` per un trascinamento personalizzato. |
| `left_mouse_up` | `target: CoordinateTarget`, `tab_id?` | Rilascia il pulsante sinistro su una coordinata. |
| `mouse_move` | `target: CoordinateTarget`, `tab_id?` | Sposta il puntatore su una coordinata. |
| `scroll` | `target: CoordinateTarget`, `scroll_direction`, `scroll_amount?`, `tab_id?` | Scorri in una posizione del viewport. `scroll_direction` è `"up"`, `"down"`, `"left"` o `"right"`; `scroll_amount` è in scatti della rotellina, da 1 a 10, predefinito 3. |
| `scroll_to` | `target: RefTarget`, `tab_id?` | Scorri fino a portare in vista un elemento referenziato. |
### Tastiera e temporizzazione
| Membro | Input | Descrizione |
| ---------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | `text`, `tab_id?` | Digita una stringa letterale nel punto di focus corrente. |
| `key` | `text`, `repeat?`, `tab_id?` | Premi un tasto o una combinazione. `text` è un singolo tasto (`"Enter"`), una combinazione unita con `+` (`"ctrl+a"`) o una sequenza separata da spazi (`"Backspace Backspace"`); `repeat` va da 1 a 100, predefinito 1. |
| `hold_key` | `text`, `duration`, `tab_id?` | Tieni premuto un tasto o una combinazione per `duration` secondi, da 0 a 30. |
| `wait` | `duration`, `tab_id?` | Metti in pausa per `duration` secondi, da 0 a 30. |
### Lettura della pagina
| Membro | Input | Descrizione |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `read_page` | `filter?`, `depth?`, `ref?`, `tab_id?` | Restituisci l'albero di accessibilità della pagina come testo con ogni elemento contrassegnato da un riferimento come `[ref_2]`. Con `filter` omesso, restituisci ogni elemento visibile; con `"interactive"`, solo gli elementi interattivi visibili; con `"all"`, anche gli elementi fuori dal viewport. `depth` limita la profondità dell'albero (minimo 1, predefinito 15) e `ref` limita la lettura al sottoalbero di quell'elemento. Limita l'output a 50.000 caratteri e indicalo nel testo; Claude quindi restringe con un `depth` più piccolo o un `ref`. |
| `find` | `query`, `tab_id?` | Cerca elementi corrispondenti a una descrizione in linguaggio naturale come `"search field"` o `"add to cart button"`, e restituisci fino a 20 corrispondenze nello stesso formato contrassegnato di `read_page`. |
| `get_page_text` | `tab_id?` | Restituisci il testo visibile della pagina come testo semplice, dando priorità al contenuto principale dell'articolo; adatto ad articoli, documentazione e altre pagine ricche di testo. |
### Moduli e file
| Membro | Input | Descrizione |
| --------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `form_input` | `target: RefTarget`, `value`, `tab_id?` | Imposta direttamente il valore di un elemento di modulo. `value` è una `string`, un `number` o un `boolean`; usa un `boolean` per le caselle di controllo e il valore o il testo visibile di un'opzione per i select. |
| `file_upload` (disabilitato per impostazione predefinita) | `target: RefTarget`, `paths?`, `document_ids?`, `tab_id?` | Imposta i file su un elemento file-input a partire da `paths` sul filesystem dell'executor, da `document_ids` che la tua applicazione ha predisposto, o da entrambi; almeno uno è obbligatorio. Vedi [Caricare file](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#upload-files). |
### Diagnostica e scripting
| Membro | Input | Descrizione |
| ------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_console` (disabilitato per impostazione predefinita) | `tab_id?` | Restituisci le voci della console della scheda (righe di log, avviso ed errore) accumulate dall'ultima lettura, una riga per voce. Vedi [Leggere l'attività della console e di rete](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#read-console-and-network-activity). |
| `read_network` (disabilitato per impostazione predefinita) | `tab_id?` | Restituisci le richieste di rete della scheda (metodo, URL, stato, tipo MIME, tempi) dall'ultima lettura, una riga per voce. |
| `javascript_exec` (disabilitato per impostazione predefinita) | `text`, `tab_id?` | Esegui `text` come JavaScript nel contesto della pagina e restituisci il valore dell'ultima espressione come testo. Vedi [Abilitare i membri opzionali](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). |
### Gestione delle schede
| Membro | Input | Descrizione |
| ------------ | ----------------------- | ------------------------------------------- |
| `new_tab` | (nessuno) | Apri una scheda e rendila la scheda attiva. |
| `list_tabs` | (nessuno) | Riporta l'inventario delle schede. |
| `switch_tab` | `tab_id` (obbligatorio) | Rendi `tab_id` la scheda attiva. |
| `close_tab` | `tab_id` (obbligatorio) | Chiudi `tab_id`. |
In caso di successo, ciascuno di questi restituisce esattamente un blocco `browser_state` e nessun testo o immagine; vedi [Risultati della gestione delle schede](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-management-results).
## Configurare il toolset
Oltre a `type`, la voce del toolset accetta `configs`, `cache_control` e `allowed_callers`; le regole che questi campi condividono con il toolset computer use sono elencate in [Client toolsets](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets), e questa sezione copre i valori predefiniti specifici del browser. `configs` è un oggetto con chiavi corrispondenti ai nomi dei membri, e il valore di ogni membro accetta due campi:
| Campo | Predefinito | Significato |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `true`, tranne `false` per i quattro [membri opzionali](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) | Se il membro viene offerto a Claude. |
| `defer_loading` | `false` | Se la definizione del toolset è differita per la ricerca degli strumenti. Deve risolversi nello stesso valore su ogni membro abilitato. Con i quattro membri opzionali lasciati disabilitati, differire il toolset significa impostarlo sugli altri 27; vedi [Client toolsets](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets). |
### Abilitare o disabilitare gli strumenti membro
Elenca in `configs` solo i membri che vuoi modificare; ogni membro che ometti mantiene il suo valore predefinito. Ad esempio, un executor che implementa le letture della console ma non il controllo di basso livello del puntatore o la pressione prolungata dei tasti attiva `read_console` e trattiene tre membri:
```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 membro disabilitato scompare dalla definizione che Claude vede; ciò non garantisce che Claude non lo nomini mai, quindi il tuo executor risponde comunque a una tale chiamata con un [risultato di errore](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
### Combinare con altri strumenti
Dichiara lo strumento browser use insieme ai tuoi strumenti e ad altri strumenti forniti da Anthropic nello stesso array `tools`. Uno strumento personalizzato può condividere il nome di un membro (il tuo `navigate`, ad esempio), perché `toolset_name` distingue le chiamate di Claude, ma nessun'altra voce può chiamarsi `browser` e una richiesta può contenere solo una voce di toolset del browser.
Puoi anche dichiararlo insieme allo [strumento computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool), sia il toolset sia una versione precedente dello strumento computer use. I due funzionano in modo indipendente, ciascuno nel proprio sistema di coordinate (pixel del viewport qui, pixel dello screenshot del desktop là), e le chiamate di Claude a membri che condividono un nome, come `screenshot` o `key`, vengono distinte tramite `toolset_name`.
## Abilitare i membri opzionali
Quattro strumenti membro sono disabilitati per impostazione predefinita: `javascript_exec` e `file_upload` perché ampliano ciò che una pagina manipolata potrebbe far fare a Claude, e `read_console` e `read_network` perché non tutti gli stack di automazione del browser possono fornire quei log e perché ampliano la quantità di contenuto controllato dalla pagina che raggiunge Claude. Abilita ciascuno con `configs` (ad esempio, `"configs": {"file_upload": {"enabled": true}}`) solo quando il tuo executor lo implementa e l'attività lo richiede.
### Caricare file
`file_upload` imposta direttamente i file su un elemento ``, il che è più affidabile che pilotare un selettore di file nativo. Il suo `target` è solo un riferimento, perché la chiamata necessita dell'identità dell'elemento, e accetta `paths`, `document_ids` o entrambi:
* `paths` sono percorsi di file sul filesystem dell'executor, per distribuzioni in cui l'executor può leggere direttamente i file della tua applicazione (la stessa condizione in cui popoli il `path` di un download).
* `document_ids` sono identificatori di file che la tua applicazione ha predisposto per il browser, per distribuzioni in cui non può farlo. La tua applicazione definisce il significato degli identificatori; limita la loro risoluzione nello stesso modo in cui limiti `paths`, ai file predisposti per questa attività.
```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 scrive questi percorsi mentre legge pagine non attendibili, quindi un'implementazione senza restrizioni permetterebbe a una pagina malevola di indirizzare il caricamento di qualsiasi file leggibile dall'executor verso un sito controllato dalla pagina. Abilita il membro solo quando il tuo executor risolve ogni percorso (seguendo i symlink e i segmenti `..`) e non accetta nulla al di fuori di una directory di caricamento dedicata e in allowlist che contiene solo file destinati all'attività. Non riutilizzare la directory di download del browser per questo scopo; se lo fai, ogni file che una pagina fa scaricare al browser diventa caricabile.
### Eseguire JavaScript nella pagina
`javascript_exec` esegue l'espressione che Claude scrive nel contesto della pagina e restituisce il valore dell'ultima espressione come testo; Claude scrive un'espressione, non un'istruzione `return`. Il codice viene eseguito con i pieni privilegi della pagina, inclusi i suoi cookie, lo storage e le richieste same-origin. Abilita il membro solo in sessioni che non contengono credenziali, mantieni in vigore la allowlist di domini di [Considerazioni sulla sicurezza](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#security-considerations), tratta il valore restituito come input non attendibile e registra il codice che Claude emette.
### Leggere l'attività della console e di rete
`read_console` restituisce le voci della console della scheda e `read_network` restituisce le sue richieste di rete, ciascuna come testo con una riga per voce accumulata dalla lettura precedente di quella scheda. Una riga della console contiene una voce di log, avviso o errore; una riga di rete contiene il metodo, l'URL, lo stato, il tipo MIME e i tempi. Le voci esistono solo dal momento in cui la tua automazione del browser si è collegata alla scheda, quindi un risultato vuoto non significa che una scheda già aperta non abbia avuto traffico.
Questi membri consentono a Claude di diagnosticare una pagina che si comporta in modo anomalo (una richiesta fallita dietro uno spinner, un errore di script dietro un pulsante inerte) senza screenshot ripetuti. Le voci della console e di rete sono controllate dalla pagina e spesso contengono segreti come token negli URL delle richieste, quindi oscura i valori simili a credenziali che non vuoi nel contesto di Claude e tronca le voci molto lunghe prima di restituirle.
## Traccia le schede con `browser_state`
Claude fa riferimento alle schede tramite `tab_id`, la tua applicazione è la fonte di verità su quali schede esistono, e tu riporti quello stato in un blocco di contenuto `browser_state` che Claude non vede mai direttamente: l'API genera il testo che Claude legge a partire da esso.
```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` è l'inventario completo delle schede aperte dopo la chiamata, non una differenza rispetto allo stato precedente. Può essere vuoto; quando non lo è, esattamente una voce riporta `"active": true`.
* `state_changes` (non mostrato qui) riporta gli effetti collaterali della chiamata: una voce `tab_opened` per ogni scheda aperta dalla chiamata e ancora aperta al suo termine, il cui `tab_id` deve comparire anche in `tabs`, e gli [eventi di download](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#report-downloads). Ometti il campo quando non c'è nulla da riportare; un array vuoto viene rifiutato.
* Invia il blocco solo nei risultati che rispondono a una chiamata a un membro del browser, al massimo una volta per `tool_result`, e mai in un risultato con `is_error: true`. Per indicare che non c'è alcuno stato delle schede da riportare, ometti il blocco.
* L'API converte in testo per Claude `tabs` ed eventuali voci di download in `state_changes`. Le due sezioni successive e [Segnala i download](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#report-downloads) mostrano tale testo.
**Sei tu ad assegnare i valori di `tab_id`.** Qualsiasi stringa stabile funziona, come l'identificatore di pagina della tua libreria di automazione o un tuo contatore, purché non riutilizzi un `tab_id` mentre una scheda con quell'identificatore è ancora elencata come aperta in un risultato precedente. L'API applica questi limiti al blocco:
* Ciascun `tab_id`, `title` e `url` può essere lungo al massimo 4.096 caratteri, `tab_id` deve essere non vuoto, e nessuno può contenere caratteri di controllo (inclusi i ritorni a capo) o separatori di riga o di paragrafo Unicode.
* Un blocco può elencare al massimo 100 schede e 200 cambiamenti di stato.
* Gli stessi limiti si applicano al `tab_id` che Claude passa a `switch_tab` e `close_tab`, perché l'API lo inserisce nel testo del risultato, quindi rispondi a una chiamata il cui `tab_id` li viola con un risultato di errore invece di un blocco `browser_state`.
I titoli e gli URL delle schede provengono dalla pagina e vengono convertiti in testo che Claude legge, quindi costituiscono una superficie di "prompt injection" (iniezione di prompt). L'API riporta gli URL delle schede alla lettera, quindi sanifica gli URL forniti dalla pagina prima di popolare `tabs`. L'API applica l'escape a virgolette doppie e barre rovesciate nei titoli durante la conversione, quindi non applicare l'escape ai titoli in anticipo (un titolo già sottoposto a escape arriva a Claude con un doppio escape); conviene comunque troncare o scartare i titoli sospetti. Anche `url`, `path` ed `error` di una voce di download vengono convertiti in testo che Claude legge, quindi considera anche questi valori non attendibili; l'API li racchiude tra virgolette e applica l'escape come fa con i titoli. I limiti di lunghezza e di caratteri applicati dall'API sono un requisito minimo, non una difesa.
### Risultati della gestione delle schede
Per `new_tab`, `switch_tab`, `close_tab` e `list_tabs`, il `content` di un risultato riuscito è esattamente un blocco `browser_state` senza testo né immagine, e l'API scrive il testo che Claude vede. Il blocco di un risultato `new_tab` deve inoltre contenere esattamente un cambiamento di stato `tab_opened` il cui `tab_id` corrisponde alla voce contrassegnata con `active: true`.
| Membro | Testo che Claude vede |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `switch_tab` | `Switched to tab {tab_id}`, preso da `input.tab_id` della chiamata |
| `close_tab` | `Closed tab {tab_id}`, preso da `input.tab_id` della chiamata |
| `new_tab` | `Created new tab with tab_id: {tab_id}, URL: {url}. It is now the current tab.`, preso dalla voce contrassegnata con `active: true` |
| `list_tabs` | `Available tabs:` seguito da una riga per scheda, oppure `No tabs available` quando `tabs` è vuoto |
Un risultato `list_tabs` il cui blocco elenca due schede con la prima attiva viene reso come segue, con ogni riga rientrata di due spazi e `(current)` aggiunto solo alla scheda attiva:
```text wrap
Available tabs:
• tab_id tab-1: "Documentation" (https://example.com/docs) (current)
• tab_id tab-2: "Pricing" (https://example.com/pricing)
```
Un risultato di errore per uno di questi membri è l'opposto: normale testo di errore in `content`, `is_error: true` e nessun blocco `browser_state`.
Ad esempio, quando Claude chiama `new_tab` (il suo `input` è vuoto), il tuo esecutore apre la scheda, la rende attiva e restituisce l'inventario con una voce `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 vede `Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab.` Riporta l'URL con cui la scheda è stata aperta, come qui, non uno verso cui viene reindirizzata in seguito; i risultati successivi riportano l'URL corrente della scheda in quel momento.
### Contesto delle schede sugli altri risultati
Su ogni altro membro il blocco è facoltativo: invialo quando l'insieme delle schede aperte, la scheda attiva, o il titolo o l'URL di una scheda sono cambiati, oppure quando ci sono `state_changes` da riportare, e includi sempre l'inventario `tabs` completo. Quando un risultato contiene sia testo sia un blocco `browser_state`, l'API aggiunge un piè di pagina `Tab Context` al testo di quel risultato, separato dal tuo testo da una riga vuota, così Claude riceve il nuovo stato senza una chiamata `list_tabs` separata:
```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` indica la scheda su cui è stata eseguita la chiamata, ovvero il suo input `tab_id` quando presente e altrimenti la scheda attiva, e le righe delle schede nel piè di pagina non riportano il marcatore `(current)`. Non aggiungere tu stesso questo testo; invia il blocco strutturato e lascia che l'API lo renda. Il piè di pagina è deduplicato, quindi uno stato delle schede identico non viene reso di nuovo nei risultati successivi e popolare il blocco generosamente non costa nulla.
Tre casi non producono alcun piè di pagina anche quando il blocco è presente:
* Qualsiasi risultato `zoom`.
* Un risultato senza blocco `text` (ad esempio, un risultato `screenshot` contenente solo un'immagine). Per quel risultato non viene generato né memorizzato nulla: il contesto delle schede compare nel successivo risultato che contiene sia testo sia un blocco `browser_state`. Se vuoi che Claude veda una modifica delle schede in quello stesso risultato, includi un breve blocco di testo insieme all'immagine. Fa eccezione un risultato il cui blocco riporta un [evento di download](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#report-downloads): l'API aggiunge le righe del download come blocco di testo e il piè di pagina le segue, come in qualsiasi risultato con testo.
* Un risultato il cui elenco `tabs` è vuoto, relativo a una chiamata senza `tab_id`, perché non c'è alcuna scheda da indicare.
Ad esempio, quando Claude ha cliccato il link "Pricing" (`ref_5`) in precedenza in questa sessione, la pagina lo ha aperto in una nuova scheda che Claude non aveva richiesto, e senza una segnalazione Claude dovrebbe chiamare `list_tabs` per scoprirla. Restituisci la conferma del clic più un blocco i cui `state_changes` indicano la scheda aperta, contrassegnando come attiva la scheda che il tuo esecutore ha lasciato attiva:
```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 vede `Clicked element ref_5.` seguito dal piè di pagina Tab Context mostrato in precedenza. Una scheda aperta durante una chiamata fallita non riceve alcuna voce `tab_opened`, perché i risultati di errore non contengono `browser_state`; compare invece nell'inventario `tabs` del successivo risultato riuscito. In un batch, allega il blocco al risultato della chiamata durante la quale è avvenuto il cambiamento, e assegna a ogni risultato riuscito di gestione delle schede il proprio blocco anche quando un risultato precedente nello stesso turno ha riportato lo stesso stato.
### Riporta i download
Quando un clic o una navigazione avvia il download di un file, riportalo in `state_changes` sul risultato della chiamata durante la quale è avvenuto, correlato tra i risultati tramite un `download_id` che assegni tu. I download vengono eseguiti in modo asincrono e possono estendersi su più risultati, quindi esistono tre tipi di evento:
| `type` | Campi | Quando inviarlo |
| -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `download_started` | `download_id`, `url` | Sul risultato della chiamata durante la quale il download è iniziato. `url` è l'URL finale da cui il file viene servito, dopo i reindirizzamenti. |
| `download_completed` | `download_id`, `url`, `path?`, `size_bytes?` | Sul risultato di qualunque chiamata successiva sia in esecuzione quando il download termina. Includi `path` solo quando un altro strumento nello stesso ambiente (ad esempio, lo [strumento bash](https://platform.claude.com/docs/it/agents-and-tools/tool-use/bash-tool) o `file_upload`) può leggere il file in quella posizione; altrimenti `download_id` è l'unico identificatore del download. |
| `download_failed` | `download_id`, `url`, `error?` | Quando il download fallisce o viene annullato, con il motivo in `error` se il browser ne fornisce uno. |
L'API converte ogni voce in una riga di testo per Claude, nell'ordine in cui compaiono le voci. Aggiunge le righe dopo il testo del risultato, separate da una riga vuota, e prima di un eventuale piè di pagina Tab Context. Le righe compaiono nei risultati di qualsiasi tipo di membro, inclusi `zoom` e i risultati di gestione delle schede. Un risultato senza blocco `text` le riceve in un blocco di testo dedicato. Ogni riga riporta `download_id` e `url`, più `path` e `size_bytes` (per `download_completed`) oppure `error` (per `download_failed`), se li invii. Non è necessario descrivere il download nel tuo testo. L'API racchiude `url`, `path` ed `error` tra virgolette doppie e applica l'escape alle virgolette doppie e alle barre rovesciate al loro interno, quindi non applicare l'escape a questi valori in anticipo.
Ad esempio, un clic su "Download price list (CSV)" (`ref_8`) nella scheda Pricing avvia un download, quindi il risultato del clic contiene una voce `download_started` con `download_id` `"dl-1"` e l'URL del file. Il download termina mentre è in esecuzione una successiva chiamata `screenshot`. Il `content` di quel risultato contiene quindi l'immagine, un blocco di testo come `Screenshot captured.` e questo blocco `browser_state`, che segnala il completamento con lo stesso `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 vede `Screenshot captured.` seguito da una riga vuota e da una riga come questa:
```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.
```
Le segnalazioni di download seguono queste regole:
* Al massimo una voce per `download_id` in un singolo blocco, quindi un download che inizia e termina durante la stessa chiamata riporta solo `download_completed`.
* Non inviare mai `state_changes` su un risultato con `is_error: true`; riporta un evento di download avvenuto durante una chiamata fallita sul successivo risultato riuscito.
* `state_changes` non è un inventario dei download in corso; riporta ogni evento una sola volta.
* Ogni voce contiene solo i campi dichiarati dal suo `type`. `size_bytes` è un intero non negativo, `download_id` è non vuoto, e `download_id`, `url`, `path` ed `error` sono ciascuno lunghi al massimo 4.096 caratteri senza caratteri di controllo né separatori di riga o di paragrafo Unicode. L'`url` proviene dal server remoto e spesso contiene credenziali firmate nella query string dopo i reindirizzamenti, quindi rimuovi i parametri di query che non vuoi nel contesto di Claude e sanificalo prima di riportarlo o di usarlo in un percorso del filesystem.
## Gestisci gli errori
Riporta a Claude una chiamata fallita come un normale risultato di errore: `is_error: true`, contenuto testuale che spiega cosa è andato storto, `toolset_name` ripetuto, e nessun blocco `browser_state`.
### Restituisci errori dal tuo esecutore
Rendi il testo di errore specifico, perché Claude lo legge e si adatta: `Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable.` dà a Claude qualcosa su cui agire, mentre un semplice `Error: navigation failed` no. Altri casi comuni:
```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."
}
```
Quando il `left_click` su `ref_3` di [Azioni in batch](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#batch-actions) fallisce con l'errore di riferimento obsoleto mostrato in precedenza, le chiamate `type` e `key` successive ricevono ciascuna questo risultato:
```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."
}
```
### Errori di richiesta
L'API valida la voce del toolset e ogni blocco `tool_use` e `tool_result` dei membri nella conversazione. Quando uno è malformato, l'API restituisce un `invalid_request_error` prima che Claude venga eseguito. Nella tabella seguente, la colonna di sinistra indica ciò che hai inviato.
| Richiesta | Perché fallisce e cosa fare |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Un'opzione o una combinazione che la voce del toolset non accetta, ad esempio un `name`, `strict: true`, `input_examples`, `defer_loading` sulla voce stessa, una chiave `configs` che non è il nome di un membro, un campo diverso da `enabled` o `defer_loading` nel valore `configs` di un membro ([Configura il toolset](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)), membri abilitati i cui valori `defer_loading` differiscono ([Configura il toolset](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)), un `configs` che non lascia alcun membro abilitato, un chiamante di esecuzione di codice in `allowed_callers`, l'header beta legacy `fine-grained-tool-streaming-2025-05-14` sulla richiesta, un `tool_choice` di tipo `tool` che indica `browser` o un membro, oppure una seconda voce di toolset browser o un altro strumento chiamato `browser` | Questi non sono supportati sui toolset client. Consulta [Toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets) per ogni regola e la relativa alternativa. |
| Un `tool_result` che risponde a una chiamata di un membro senza `"toolset_name": "browser"` o con un valore diverso, oppure `toolset_name` su un risultato la cui chiamata non era una chiamata di un membro | Ripeti `toolset_name` esattamente sui risultati dei membri, e solo su di essi. |
| Un `tool_use` di un membro da un turno precedente senza un `tool_result` corrispondente | Rispondi a ogni chiamata di un membro, incluse quelle che non hai eseguito dopo un fallimento. |
| Un blocco di contenuto diverso da `text`, `image` o `browser_state` in un risultato di un membro | I risultati dei membri accettano solo questi tre tipi di blocco. |
| Un blocco `browser_state` che viola una regola di [Traccia le schede con `browser_state`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), ad esempio uno su un risultato con `is_error: true` o su un risultato che non risponde a una chiamata di un membro del browser, più di uno in un risultato, un `tabs` non vuoto senza esattamente una voce `active: true`, un `tab_id` duplicato, un array `state_changes` vuoto, un `tab_opened` il cui `tab_id` non è in `tabs`, due cambiamenti di stato per un solo `download_id` o un campo di cambiamento di stato non dichiarato dal suo `type` ([Riporta i download](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#report-downloads)), oppure un campo oltre i suoi limiti | Correggi il blocco. "Nulla da riportare" si esprime omettendo il blocco o il campo `state_changes`, mai con un valore vuoto. |
| Un risultato riuscito di `new_tab`, `switch_tab`, `close_tab` o `list_tabs` il cui `content` non è esattamente un blocco `browser_state`, oppure un risultato `new_tab` senza esattamente un `tab_opened` corrispondente alla scheda attiva | L'API rende questi risultati a partire dal blocco e ne ha bisogno esattamente in quella forma; consulta [Risultati della gestione delle schede](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-management-results). |
| Un'`image` in un risultato oltre i [limiti di dimensione delle immagini](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size) del tuo modello, oppure oltre il limite per immagine più restrittivo che si applica quando la richiesta contiene [più di 20 immagini](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits), contando gli screenshot e le immagini `zoom` nei risultati precedenti | L'API non ridimensiona le immagini dei toolset. Ridimensiona gli screenshot prima di restituirli ([Dimensiona gli screenshot per rispettare i limiti delle immagini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)). |
| Un `model` che non supporta `browser_toolset_20260801` | Consulta [Compatibilità](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#compatibility) per i modelli supportati. |
## Limitazioni
* **Disponibilità sulle piattaforme:** L'uso del browser è disponibile sulla Claude API e su [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai).
* **Solo streaming dell'input completo:** Quando usi lo streaming, l'`input` di ogni membro arriva come un unico `input_json_delta` completo ([Toolset client](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference#client-toolsets)).
* **I riferimenti agli elementi sono best-effort:** Le pagine altamente dinamiche (liste virtualizzate, interfacce rese su canvas, pagine che si ri-renderizzano allo scorrimento) potrebbero non esporre riferimenti stabili, e in quei casi Claude ricorre a screenshot e clic per coordinate.
* **`read_console` e `read_network` dipendono dalla tua automazione del browser:** Riportano solo ciò che essa può catturare, e solo dal momento in cui si è collegata a una scheda.
* **Si applicano le limitazioni generali degli agenti:** La "latency" (latenza), l'accuratezza della visione e i rischi di prompt injection si ereditano dal computer use (consulta le [Limitazioni](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#understand-computer-use-limitations) dello strumento computer use), e le sue indicazioni in [Ottimizza le prestazioni del modello con il prompting](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting), [Gestisci la cronologia degli screenshot](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#manage-screenshot-history) e [Segui le best practice di implementazione](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#follow-implementation-best-practices) (ritardi tra le azioni, validazione delle azioni e logging) si applicano anche agli esecutori del browser.
## Prezzi e conservazione dei dati
Il "browser use" (uso del browser) segue i [prezzi standard dell'uso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview#pricing). Quando usi lo strumento browser use:
**Overhead della definizione del toolset:** Dichiarare `browser_toolset_20260801` con i suoi membri predefiniti aggiunge circa 6.600 token di input a una richiesta (circa 6.670 su Claude Sonnet 5 e circa 6.610 sugli altri modelli supportati), che coprono le definizioni degli strumenti membri e il prompt di sistema per l'uso degli strumenti. Abilitare tutti e quattro i membri opzionali aggiunge circa 880 token, mentre disabilitare i membri con `configs` riduce il conteggio. Il conteggio esatto per una richiesta è riportato nel campo `usage` della risposta, e puoi stimarlo in anticipo con l'[endpoint di conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting).
**Consumo aggiuntivo di token:**
* Screenshot e immagini di zoom restituiti nei risultati degli strumenti, fatturati come input di immagini (vedi [Prezzi di Vision](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size))
* Risultati testuali degli strumenti restituiti a Claude, come alberi di accessibilità, testo della pagina e voci di console o di rete
Se usi anche lo strumento computer use, lo strumento bash, lo strumento editor di testo o i tuoi strumenti personalizzati insieme a browser use, tali strumenti hanno i propri costi in token, come documentato nelle rispettive pagine.
La sessione del browser, i download e i file caricati restano nel tuo ambiente; gli screenshot, il testo delle pagine e lo stato delle schede che restituisci fanno parte del contenuto della tua richiesta API e seguono la politica di conservazione standard, oppure il tuo accordo ZDR se ne hai uno. Lo strumento di uso del browser è idoneo per ZDR; consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention) per i periodi di conservazione e l'idoneità delle varie funzionalità.
## Prossimi passi
Parti dal driver di un partner, oppure scrivine uno tuo in Python o TypeScript. L'SDK esegue il ciclo e i controlli che configuri.
Dai a Claude il controllo di un desktop completo quando l'attività esce dal browser; le sue indicazioni di implementazione si applicano anche agli esecutori del browser.
Formatta i blocchi `tool_result`, restituisci immagini ed errori e continua la conversazione.
Esplora i toolset client e tutti gli altri strumenti forniti da Anthropic, con le relative versioni e parametri.