Strumento browser use

Lo strumento "browser use" (uso del browser) consente a Claude di navigare, leggere e interagire con le pagine web in un browser eseguito dalla tua applicazione. Lavora con la pagina sia attraverso la sua struttura (l'"accessibility tree" (albero di accessibilità), gli elementi, i moduli e le schede) sia attraverso i pixel (screenshot e coordinate del viewport), mentre lo strumento computer use lavora con un intero desktop solo tramite screenshot e coordinate. È un "client toolset" (toolset client) definito da Anthropic: una singola voce browser_toolset_20260801 nel tuo array tools fornisce a Claude 27 "member tools" (strumenti membro) per impostazione predefinita, come navigate, read_page, left_click e screenshot, più altri quattro (javascript_exec, file_upload, read_console e read_network) quando li abiliti. La tua applicazione esegue ogni chiamata con la propria automazione del browser; nulla viene eseguito sul lato di Anthropic. Non è attualmente disponibile in Claude Managed Agents. Questa pagina usa "la tua applicazione" per indicare il ciclo dell'agente che chiama la Messages API e "il tuo executor" (esecutore) per la parte di essa che pilota il browser e produce i risultati degli strumenti.

Scegli browser use rispetto a computer use quando l'attività rimane all'interno delle pagine web: Claude può leggere la struttura di una pagina, agire su un elemento tramite riferimento oltre che tramite coordinata, impostare direttamente i valori dei moduli e lavorare su più schede, e non hai bisogno di eseguire un desktop. Se Claude deve solo leggere pagine che puoi indicargli, o trovare fonti sul web, lo strumento web fetch e lo strumento web search sono ancora più leggeri, perché sono "server tools" (strumenti server) che l'API esegue per te senza alcun browser da gestire. Scegli invece browser use quando le pagine costruiscono il loro contenuto con JavaScript o quando l'attività implica agire sulla pagina anziché solo leggerla.

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 prima di distribuire in produzione.



Avvio rapido

Lo strumento browser use è disponibile sulla Claude API senza header beta: aggiungi una voce di tipo browser_toolset_20260801, senza name, all'array tools di una richiesta alla Messages API.

client = anthropic.Anthropic()

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

La 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":

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

Il tuo executor esegue navigate, poi read_page, e 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:

{
  "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

Browser use viene eseguito come un ciclo dell'agente: Claude restituisce chiamate a strumenti membro, il tuo executor le esegue sul browser e tu restituisci i risultati finché Claude non risponde con del testo.

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.

# 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}")

La seconda parte esegue un batch in ordine, smista ogni blocco a quegli handler, ripete toolset_name su ogni risultato e applica la regola di arresto di Azioni batch, 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, con il toolset browser in tools.

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


def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
    """
    Run the browser actions in Claude's response in order and answer each
    one. After the first failure the rest are skipped, because Claude planned
    them assuming the earlier actions succeeded.
    """
    tool_results: list[ToolResultBlockParam] = []
    failed = False
    for block in response.content:
        # È 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

Smista ogni blocco in base alla coppia (toolset_name, name) anziché solo in base a name, perché uno strumento personalizzato nella stessa richiesta potrebbe condividere il nome di un membro; Toolset client descrive le parti di questo contratto condivise da entrambi i toolset. 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 anziché scartarlo.

Quando usi lo streaming della risposta, l'input di ogni membro arriva come un unico input_json_delta completo anziché come frammenti, quindi attendi che il turno termini prima di eseguire il batch.



Azioni batch

Un turno con più chiamate membro è un'azione batch: esegui le chiamate nell'ordine in cui compaiono, 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; 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:

{
  "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 sugli altri risultati). 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.

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 una 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 membro per turno, al costo di più round trip (Disabilitare l'uso parallelo degli strumenti). Il resto del contratto descritto in Azioni batch per lo strumento computer use 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 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), e il risultato di qualsiasi altro membro può aggiungere un blocco browser_state al proprio testo o immagine (Contesto della scheda sugli altri risultati). Dove hanno effetto i breakpoint della cache all'interno di un batch è descritto nella riga cache_control dei Parametri dello strumento 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 indicano Target per un parametro che accetta entrambe le forme.

Le coordinate sono pixel del viewport, lo spazio di pixel di uno screenshot dell'intero viewport 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 coerente. 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 dell'intero viewport.

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 del tuo modello, o il limite per immagine più restrittivo che si applica quando una richiesta contiene più di 20 immagini, viene rifiutato. Ridimensiona prima di restituire e riporta le coordinate di Claude alla scala originale moltiplicandole per l'inverso del tuo fattore prima di smistarle (Dimensionare gli screenshot per rispettare i limiti delle immagini).

I riferimenti agli elementi provengono da read_page e find. Ogni elemento nel loro output porta un'etichetta come [ref_2], come nel risultato dell'Avvio rapido:

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

Claude ripassa 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. Le interfacce renderizzate su canvas, i video incorporati o le superfici di desktop remoto, le liste fortemente virtualizzate e gli 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à standard dell'API non hanno, perché Claude legge e agisce su contenuti del web aperto, dove qualsiasi pagina può contenere testo scritto per manipolarlo.

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 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.

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. Quattro membri (javascript_exec, file_upload, read_console e read_network) sono disabilitati per impostazione predefinita e compaiono solo quando li abiliti. I limiti di input e le convenzioni di output indicati nella riga di ogni membro sono comunicati a Claude, non applicati dall'API, quindi convalida gli input (incluse le coordinate rispetto al tuo viewport) e applica le convenzioni nel tuo executor.

Solo screenshot e zoom richiedono un blocco image 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). 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 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



Puntatore



Tastiera e temporizzazione



Lettura della pagina



Moduli e file



Diagnostica e scripting



Gestione delle schede

In caso di successo, ciascuno di questi restituisce esattamente un blocco browser_state e nessun testo o immagine; vedi Risultati della gestione delle schede.



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 Toolset client, 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:



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:

{
  "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.



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 una sola voce di toolset browser.

Puoi anche dichiararlo insieme allo strumento computer use, 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 <input type="file">, 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 le 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 le 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à.

{
  "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 consentirebbe a una pagina malevola di dirigere il caricamento di qualsiasi file che l'executor può leggere 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 inserita in allowlist che contenga 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 l'allowlist di domini di Considerazioni sulla sicurezza, 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.

{
  "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 un delta. 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 che è ancora aperta quando questa termina, il cui tab_id deve comparire anche in tabs, e gli eventi di download. Ometti il campo quando non c'è nulla da riportare; un array vuoto viene rifiutato.
• Invia il blocco solo sui risultati che rispondono a una chiamata a un membro del browser, al massimo una volta per tool_result, e mai su un risultato con is_error: true. Esprimi "nessuno stato delle schede da riportare" omettendo il blocco.
• L'API genera tabs come testo per Claude come descritto nelle due sezioni successive; le voci di download in state_changes vengono validate ma non generate come 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 genera 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.



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 active: true.

Un risultato list_tabs il cui blocco elenca due schede con la prima attiva viene generato come segue, con ogni riga rientrata di due spazi e (current) aggiunto solo alla scheda attiva:

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'inverso: testo di errore ordinario 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:

{
  "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:

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, che è il suo input tab_id quando presente e altrimenti la scheda attiva, e le righe delle schede nel piè di pagina non riportano alcun indicatore (current). Non aggiungere tu stesso questo testo; invia il blocco strutturato e lascia che l'API lo generi. Il piè di pagina viene deduplicato, quindi uno stato delle schede identico non viene generato di nuovo sui risultati successivi e popolare il blocco generosamente non costa nulla.

Tre casi non generano alcun piè di pagina anche quando il blocco è presente:

• Qualsiasi risultato zoom.
• Un risultato senza blocco text (un risultato screenshot con sola immagine, ad esempio). Nulla viene generato o ricordato per quel risultato; il contesto delle schede compare sul risultato successivo che contiene sia testo sia un blocco browser_state, quindi includi un breve blocco di testo accanto all'immagine quando vuoi che Claude veda un cambiamento di scheda su quello stesso risultato.
• Un risultato la cui lista tabs è vuota su una chiamata che non conteneva alcun tab_id, perché non c'è alcuna scheda da indicare.

Ad esempio, quando Claude ha fatto clic sul 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 un report Claude dovrebbe chiamare list_tabs per scoprirla. Restituisci la conferma del clic più un blocco i cui state_changes indicano la scheda aperta, contrassegnando la scheda che il tuo esecutore ha lasciato attiva:

{
  "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:

L'API valida queste voci ma non le genera come testo che Claude vede, quindi quando Claude deve agire sul file, menziona anche il nome del file o il path nel blocco text dello stesso risultato.

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, quindi il content di quel risultato contiene l'immagine, un blocco di testo come Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes)., e questo blocco browser_state che riporta il completamento con lo stesso download_id:

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

I report dei 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 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 risultato di errore ordinario: is_error: true, contenuto testuale che spiega cosa è andato storto, toolset_name ripetuto e nessun blocco browser_state.



Restituisci errori dal tuo esecutore

Rendi specifico il testo dell'errore, 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:



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.



Limitazioni

• Disponibilità della piattaforma: l'uso del browser è disponibile solo sulla Claude API.
• Solo streaming dell'input completo: quando usi lo streaming, l'input di ogni membro arriva come un unico input_json_delta completo (Toolset client).
• I riferimenti agli elementi sono best-effort: le pagine altamente dinamiche (liste virtualizzate, interfacce renderizzate su canvas, pagine che si ri-renderizzano allo scorrimento) potrebbero non esporre riferimenti stabili, e in quei casi Claude ripiega su 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 trasferiscono dall'uso del computer (consulta le Limitazioni dello strumento di uso del computer), e le sue indicazioni in Ottimizza le prestazioni del modello con il prompting, Gestisci la cronologia degli screenshot e Segui le best practice di implementazione (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 per l'uso degli strumenti. 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.610 su Claude Fable 5, Claude Mythos 5, Claude Opus 5 e Claude Opus 4.8, e circa 6.670 su Claude Sonnet 5), 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.

Consumo aggiuntivo di token:

• Immagini di screenshot e zoom restituite nei risultati degli strumenti, fatturate come input di immagini (vedi Prezzi di Vision)
• Risultati testuali degli strumenti restituiti a Claude, come alberi di accessibilità, testo della pagina e voci della console o di rete

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 per i periodi di conservazione e l'idoneità delle varie funzionalità.



Passaggi successivi