Alat penggunaan browser

"Browser use tool" (alat penggunaan browser) memungkinkan Claude menavigasi, membaca, dan berinteraksi dengan halaman web di browser yang dijalankan oleh aplikasi Anda. Alat ini bekerja dengan halaman baik melalui strukturnya (pohon aksesibilitas, elemen, formulir, dan tab) maupun melalui piksel (tangkapan layar dan koordinat viewport), sedangkan alat penggunaan komputer bekerja dengan seluruh desktop hanya melalui tangkapan layar dan koordinat. Ini adalah client toolset (kumpulan alat klien) yang didefinisikan Anthropic: satu entri browser_toolset_20260801 dalam array tools Anda memberi Claude 27 alat anggota secara default, seperti navigate, read_page, left_click, dan screenshot, ditambah empat lagi (javascript_exec, file_upload, read_console, dan read_network) ketika Anda mengaktifkannya. Aplikasi Anda menjalankan setiap panggilan terhadap otomatisasi browsernya sendiri; tidak ada yang berjalan di sisi Anthropic. Alat ini saat ini tidak tersedia di Claude Managed Agents. Halaman ini menggunakan istilah "aplikasi Anda" untuk loop agen yang memanggil Messages API dan "eksekutor Anda" untuk bagian darinya yang mengendalikan browser dan menghasilkan hasil alat.

Pilih penggunaan browser daripada penggunaan komputer ketika tugas tetap berada di dalam halaman web: Claude dapat membaca struktur halaman, bertindak pada elemen berdasarkan referensi selain berdasarkan koordinat, mengatur nilai formulir secara langsung, dan bekerja lintas tab, dan Anda tidak perlu menjalankan desktop. Jika Claude hanya perlu membaca halaman yang dapat Anda tunjukkan, atau menemukan sumber di web, alat web fetch dan alat web search lebih ringan lagi, karena keduanya adalah server tools (alat server) yang dijalankan API untuk Anda tanpa browser yang perlu dioperasikan. Pilih penggunaan browser sebagai gantinya ketika halaman membangun kontennya dengan JavaScript atau tugasnya berarti bertindak pada halaman, bukan hanya membacanya.

Dengan penggunaan browser, Claude membaca dan bertindak pada halaman web langsung, sehingga semua yang disediakan halaman adalah input yang tidak tepercaya dan tindakan yang diambil Claude dapat memiliki efek nyata. Lihat Pertimbangan keamanan sebelum Anda melakukan deployment.

Mulai cepat

Alat penggunaan browser tersedia di Claude API dan Google Cloud: tambahkan satu entri bertipe browser_toolset_20260801, tanpa name, ke array tools dari permintaan 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)

Respons pertama Claude berakhir dengan stop_reason: "tool_use" dan membawa satu atau lebih blok tool_use anggota, masing-masing menyebutkan alat anggota di name dan membawa "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
}

Eksekutor Anda menjalankan navigate, lalu read_page, dan aplikasi Anda mengembalikan satu tool_result per blok dalam permintaan berikutnya, dengan menggemakan toolset_name pada masing-masing. Hasil navigate melaporkan tab yang dimuatnya dalam blok browser_state; hasil read_page adalah teks di mana setiap elemen membawa referensi:

{
  "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 kini memegang referensi yang dapat ditindaklanjutinya, sehingga giliran berikutnya dapat mengklik ref_2 untuk membuka halaman memulai, tanpa perlu menemukan tautan tersebut dalam tangkapan layar terlebih dahulu.

Cara kerja penggunaan browser

Penggunaan browser berjalan sebagai loop agen: Claude mengembalikan panggilan alat anggota, eksekutor Anda menjalankannya terhadap browser, dan Anda mengembalikan hasilnya hingga Claude menjawab dalam teks.

1. 1

   Berikan Claude alat penggunaan browser dan prompt pengguna

   • Tambahkan entri browser_toolset_20260801, dan secara opsional alat lain, ke permintaan API Anda.
   • Sertakan prompt pengguna yang memerlukan pekerjaan dengan halaman web, misalnya, "Buka example.com/docs dan beri tahu saya cara memulai."
2. 2

   Claude merespons dengan panggilan alat anggota

   • Claude mengembalikan satu atau lebih blok tool_use dalam satu giliran asisten; beberapa blok dalam satu giliran membentuk tindakan batch, misalnya, left_click, lalu type, lalu key.
   • name setiap blok adalah nama anggota, masing-masing membawa "toolset_name": "browser", dan input hanya berisi parameter anggota tersebut, tanpa field action. stop_reason respons adalah tool_use.
3. 3

   Jalankan panggilan secara berurutan dan kembalikan hasilnya

   • Iterasi setiap blok tool_use dalam response.content (jangan berasumsi hanya ada satu) dan jalankan secara berurutan, sesuai urutan kemunculannya, karena panggilan selanjutnya biasanya bergantung pada panggilan sebelumnya.
   • Kembalikan satu tool_result per blok dalam pesan user baru, dicocokkan berdasarkan tool_use_id, dan gemakan "toolset_name": "browser" pada masing-masing. Setiap panggilan harus dijawab atau permintaan berikutnya akan ditolak.
   • Jika sebuah panggilan gagal, kembalikan is_error: true dengan deskripsi teks untuk blok tersebut, lalu terapkan aturan penghentian di Tindakan batch pada setiap blok selanjutnya dalam giliran tersebut.
4. 4

   Claude melanjutkan hingga tugas selesai

   • Claude membaca hasilnya (teks halaman, pohon aksesibilitas, tangkapan layar, status tab) dan, jika membutuhkan lebih banyak, mengembalikan panggilan anggota lebih lanjut, yang membawa Anda kembali ke langkah 3.
   • Jika tidak, Claude mengembalikan respons teks kepada pengguna.

Berikut kerangka langkah panggilan alat dari loop tersebut dalam dua bagian. Pertama, handler anggota stub menggantikan otomatisasi browser Anda. Lima anggota (navigate, read_page, left_click, type, dan screenshot) mengembalikan teks, atau untuk screenshot blok gambar, yang menjadi konten hasil, dan dispatcher memunculkan error untuk anggota apa pun yang tidak diimplementasikannya.

# Data gambar placeholder; eksekutor nyata menangkap viewport dan mengembalikan 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):
    # Target adalah referensi elemen dari read_page atau find, atau koordinat 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 menjawab dengan blok gambar, bukan teks: kembalikan daftar konten hasil
    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()
    # Tangani aksi lain sesuai kebutuhan
    raise ValueError(f"Unknown or unimplemented member: {name}")

Bagian kedua menjalankan batch secara berurutan, mengirim setiap blok ke handler tersebut, menggemakan toolset_name pada setiap hasil, dan menerapkan aturan penghentian dari Tindakan batch, mengubah error handler menjadi hasil error. Loop sampling yang memanggilnya adalah yang ditunjukkan di Memahami loop agen, dengan toolset browser di 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:
        # Hanya toolset browser yang dideklarasikan; arahkan alat lain ke sini jika Anda menambahkannya
        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:
                # String atau daftar blok konten; eksekutor nyata juga menambahkan
                # blok browser_state ke hasil navigasi dan pengelolaan tab
                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

Kirim setiap blok berdasarkan pasangan (toolset_name, name) dan bukan hanya name, karena alat kustom dalam permintaan yang sama mungkin memiliki nama yang sama dengan anggota; Client toolsets menjelaskan bagian-bagian kontrak ini yang dimiliki bersama oleh kedua toolset. Jika Claude menyebutkan anggota yang tidak diimplementasikan eksekutor Anda, atau yang Anda nonaktifkan, jawab blok tersebut dengan hasil error alih-alih mengabaikannya.

Ketika Anda melakukan streaming respons, input setiap anggota tiba sebagai satu input_json_delta lengkap, bukan sebagai fragmen, jadi tunggu hingga giliran selesai sebelum menjalankan batch.

Tindakan batch

Giliran dengan beberapa panggilan anggota adalah tindakan batch: jalankan panggilan sesuai urutan kemunculannya, berhenti pada kegagalan pertama, dan jawab setiap panggilan selanjutnya dengan is_error: true dan teks persis Not executed: an earlier action in this turn failed. Batch menggunakan bentuk respons yang sama dengan penggunaan alat paralel; perbedaannya adalah Anda menjalankan blok secara berurutan, bukan secara bersamaan. Di sini Claude mengklik kotak pencarian yang ditemukannya sebelumnya, mengetik kueri, dan menekan Enter dalam satu giliran:

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

Aplikasi Anda mengembalikan tiga blok tool_result dalam satu pesan user, masing-masing membawa toolset_name dan pengakuan teks singkat seperti Clicked element ref_3. Menekan Enter memuat halaman hasil, sehingga hasil key juga membawa blok browser_state dengan URL tab yang diperbarui (Konteks tab pada hasil lain). Jika klik tersebut gagal, hasilnya akan membawa teks error Anda dan dua hasil lainnya akan membawa teks penghentian, seperti ditunjukkan di Mengembalikan error dari eksekutor Anda.

Anda tidak perlu mengembalikan tangkapan layar setelah setiap panggilan. Claude biasanya mengakhiri batch dengan panggilan observasi (screenshot, read_page, atau get_page_text), dan aplikasi Anda juga dapat melampirkan observasinya sendiri, seperti tangkapan layar baru atau pohon aksesibilitas, sebagai blok konten tambahan pada hasil terakhir dalam batch untuk menghemat satu perjalanan bolak-balik. Karena hasil manajemen tab harus berupa tepat satu blok browser_state, lampirkan pada hasil terakhir yang bukan panggilan manajemen tab.

Jika eksekutor Anda hanya dapat menjalankan satu panggilan per perjalanan bolak-balik, atur disable_parallel_tool_use ke true di tool_choice dan Claude mengembalikan paling banyak satu panggilan anggota per giliran, dengan biaya lebih banyak perjalanan bolak-balik (Menonaktifkan penggunaan alat paralel). Sisa kontrak di Tindakan batch untuk alat penggunaan komputer tetap berlaku, termasuk satu tool_result untuk setiap tool_use dalam pesan user berikutnya, kecuali dua hal: teks penghentian dan apa yang dimuat content dari hasil yang berhasil. Konten hasil mengikuti Alat anggota di halaman ini: hasil new_tab, switch_tab, close_tab, atau list_tabs adalah tepat satu blok browser_state tanpa teks atau gambar (Hasil manajemen tab), dan hasil anggota lainnya dapat menambahkan blok browser_state ke teks atau gambarnya (Konteks tab pada hasil lain). Di mana breakpoint cache di dalam batch berlaku dijelaskan di baris cache_control pada Parameter alat alat penggunaan komputer.

Target dan koordinat

Alat anggota yang bertindak pada suatu lokasi menerima objek target, yang berupa koordinat piksel viewport atau referensi ke elemen yang dikembalikan read_page atau find. Tabel Alat anggota menulis Target untuk parameter yang menerima salah satu bentuk.

Koordinat adalah piksel viewport, ruang piksel dari screenshot viewport penuh dengan titik asal di kiri atas halaman yang dirender; tidak ada desktop atau bingkai jendela di sekelilingnya. Toolset tidak mendeklarasikan dimensi tampilan dan Claude menyimpulkan ukuran viewport dari tangkapan layar yang Anda kembalikan, jadi pertahankan satu ukuran yang konsisten. zoom tidak mengubah bingkai, sehingga region-nya dan koordinat apa pun yang dikeluarkan Claude setelah melihat gambar yang diperbesar tetap merupakan piksel viewport penuh.

Tangkapan layar harus sesuai dengan batas gambar. API tidak memperkecil gambar toolset: tangkapan layar atau gambar zoom yang melebihi batas ukuran gambar model Anda, atau melebihi batas per gambar yang lebih ketat yang berlaku setelah permintaan memuat lebih dari 20 gambar, akan ditolak. Ubah ukurannya sebelum mengembalikan, dan skalakan kembali koordinat Claude dengan kebalikan faktor Anda sebelum mengirimkannya (Mengatur ukuran tangkapan layar agar sesuai batas gambar).

Referensi elemen berasal dari read_page dan find. Setiap elemen dalam outputnya membawa tag seperti [ref_2], seperti pada hasil Mulai cepat:

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

Claude mengirim kembali referensi sebagai target {"type": "ref", "ref": "ref_2"} pada panggilan klik, hover, scroll_to, form_input, atau file_upload berikutnya, atau sebagai parameter ref pada read_page untuk membaca subpohon. Eksekutor Anda menetapkan referensi, menyimpan pemetaan dari masing-masing ke node yang mendasarinya (ID node aksesibilitas, selector tersimpan, atau yang setara), dan bertindak pada node tersebut ketika referensi dikembalikan.

Referensi dibatasi pada tab yang menghasilkannya dan tetap valid hingga tab tersebut bernavigasi atau DOM-nya berubah secara material. API tidak dapat mendeteksi referensi yang kedaluwarsa atau tidak dikenal, jadi ketika Claude mengirim referensi yang tidak lagi dikenali eksekutor Anda, kembalikan hasil error seperti Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references. Claude kemudian membaca halaman lagi. Jangan menomori ulang referensi yang sudah Anda berikan untuk sebuah tab hingga tab tersebut bernavigasi, karena itu secara diam-diam membatalkan referensi yang masih dipegang Claude.

Claude menggunakan kedua gaya penargetan dan beralih di antaranya berdasarkan apa yang diekspos halaman; prompt Anda dan apa yang dikembalikan eksekutor Anda mengarahkan pilihan tersebut:

• Utamakan referensi ketika halaman memiliki pohon aksesibilitas yang dapat digunakan. Referensi bertahan dari pergeseran tata letak dan reflow yang membuat koordinat piksel rapuh, dan memungkinkan Claude bertindak pada kontrol yang sulit dikenai dengan pointer.
• Kembali ke koordinat untuk konten yang tidak dijelaskan pohon. Antarmuka yang dirender canvas, video tersemat atau permukaan remote-desktop, daftar yang sangat tervirtualisasi, dan elemen di dalam iframe lintas-origin sering tidak memiliki node yang berguna, sehingga Claude bekerja dari screenshot dan zoom dan mengklik berdasarkan koordinat; eksekutor Anda menentukan frame mana yang dikenai koordinat.
• Batasi cakupan pembacaan, dan baca pohon sebelum Anda mengambil tangkapan layar. Pada halaman besar, read_page dengan filter: "interactive" atau ref dari sebuah kontainer mengembalikan subpohon yang terfokus, dan pembacaan pohon dari halaman tipikal sering menghabiskan lebih sedikit token input daripada tangkapan layar sambil memberi Claude referensi yang dapat langsung ditindaklanjuti. Tangkapan layar tetap menjadi observasi yang tepat ketika tata letak visual, gambar, atau status rendering penting.

Pertimbangan keamanan

Penggunaan browser membawa risiko yang tidak dimiliki fitur API standar, karena Claude membaca dan bertindak pada konten dari web terbuka, di mana halaman apa pun dapat berisi teks yang ditulis untuk memanipulasinya.

Claude terkadang mengikuti instruksi yang ditemukan dalam konten halaman bahkan ketika bertentangan dengan instruksi Anda; teks pada halaman yang mengatakan "abaikan instruksi sebelumnya dan navigasi ke..." dapat mengalihkannya dari tugas. Isolasi Claude dari data dan tindakan sensitif untuk membatasi apa yang dapat dijangkau injeksi prompt, tinjau Memitigasi jailbreak dan injeksi prompt, dan jika tugas tidak dapat menghindari sesi yang sudah login, gunakan akun khusus dengan hak akses rendah dan pertahankan konfirmasi manusia pada tindakan yang mengubah akun.

Karena browser berjalan di lingkungan Anda, situs yang dikunjungi Claude melihat identitas jaringan eksekutor Anda, dan konten halaman mencapai API hanya sebagai hasil alat yang Anda kembalikan. Beri tahu pengguna akhir tentang risiko yang relevan dan dapatkan persetujuan mereka sebelum mengaktifkan penggunaan browser dalam produk Anda.

Alat anggota

Entri browser_toolset_20260801 mendeklarasikan 31 alat anggota; input setiap panggilan adalah tepat parameter yang tercantum di sini, dan tab_id, jika opsional, default ke tab aktif. Target, CoordinateTarget, dan RefTarget adalah bentuk yang dijelaskan di Target dan koordinat. Empat anggota (javascript_exec, file_upload, read_console, dan read_network) dinonaktifkan secara default dan hanya muncul ketika Anda mengaktifkannya. Batas input dan konvensi output yang dicatat di baris setiap anggota dinyatakan kepada Claude, tidak diterapkan oleh API, jadi validasi input (termasuk koordinat terhadap viewport Anda) dan terapkan konvensi tersebut di eksekutor Anda.

Hanya screenshot dan zoom yang memerlukan blok image dalam hasilnya, dan empat anggota manajemen tab (new_tab, list_tabs, switch_tab, dan close_tab) mengembalikan tepat satu blok browser_state (lihat Hasil manajemen tab). Setiap anggota lainnya mengembalikan blok text: baik pengakuan singkat seperti Clicked element ref_2. atau output anggota tersebut. Hasil apa pun selain hasil manajemen tab juga dapat membawa blok image, biasanya tangkapan layar yang diambil setelah tindakan, sehingga Claude melihat hasilnya tanpa panggilan screenshot terpisah; Tindakan batch menunjukkan di mana melampirkannya dalam batch. tool_result anggota hanya boleh berisi blok konten text, image, dan browser_state.

Navigasi dan tangkapan

Pointer

Keyboard dan pengaturan waktu

Pembacaan halaman

Formulir dan file

Diagnostik dan scripting

Manajemen tab

Jika berhasil, masing-masing mengembalikan tepat satu blok browser_state dan tanpa teks atau gambar; lihat Hasil manajemen tab.

Mengonfigurasi toolset

Selain type, entri toolset menerima configs, cache_control, dan allowed_callers; aturan yang dimiliki bersama field ini dengan toolset penggunaan komputer tercantum di Client toolsets, dan bagian ini membahas default khusus browser. configs adalah objek dengan kunci nama anggota, dan nilai setiap anggota menerima dua field:

Mengaktifkan atau menonaktifkan alat anggota

Cantumkan hanya anggota yang ingin Anda ubah di configs; setiap anggota yang Anda hilangkan mempertahankan defaultnya. Misalnya, eksekutor yang mengimplementasikan pembacaan konsol tetapi tidak kontrol pointer tingkat rendah atau penahanan tombol mengaktifkan read_console dan menahan tiga anggota:

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

Anggota yang dinonaktifkan menghilang dari definisi yang dilihat Claude; itu tidak menjamin Claude tidak pernah menyebutkannya, jadi eksekutor Anda tetap menjawab panggilan seperti itu dengan hasil error.

Menggabungkan dengan alat lain

Deklarasikan alat penggunaan browser bersama alat Anda sendiri dan alat lain yang disediakan Anthropic dalam array tools yang sama. Alat kustom boleh memiliki nama yang sama dengan anggota (navigate Anda sendiri, misalnya), karena toolset_name membedakan panggilan Claude, tetapi tidak ada entri lain yang boleh bernama browser, dan permintaan hanya boleh berisi satu entri toolset browser.

Anda juga dapat mendeklarasikannya bersama alat penggunaan komputer, baik toolset maupun versi alat penggunaan komputer sebelumnya. Keduanya bekerja secara independen, masing-masing dalam bingkai koordinatnya sendiri (piksel viewport di sini, piksel tangkapan layar desktop di sana), dan panggilan Claude ke anggota yang memiliki nama sama, seperti screenshot atau key, dibedakan oleh toolset_name.

Mengaktifkan anggota opsional

Empat alat anggota dinonaktifkan secara default: javascript_exec dan file_upload karena memperluas apa yang dapat dibuat halaman yang dimanipulasi agar dilakukan Claude, dan read_console dan read_network karena tidak setiap stack otomatisasi browser dapat menyediakan log tersebut dan keduanya memperluas konten yang dikendalikan halaman yang mencapai Claude. Aktifkan masing-masing dengan configs (misalnya, "configs": {"file_upload": {"enabled": true}}) hanya ketika eksekutor Anda mengimplementasikannya dan tugas membutuhkannya.

Mengunggah file

file_upload mengatur file pada elemen <input type="file"> secara langsung, yang lebih andal daripada mengendalikan pemilih file native. target-nya hanya berupa referensi, karena panggilan membutuhkan identitas elemen, dan menerima paths, document_ids, atau keduanya:

• paths adalah path file di sistem file eksekutor, untuk deployment di mana eksekutor dapat membaca file aplikasi Anda secara langsung (kondisi yang sama di mana Anda mengisi path unduhan).
• document_ids adalah pengenal untuk file yang telah disiapkan aplikasi Anda untuk browser, untuk deployment di mana eksekutor tidak dapat melakukannya. Aplikasi Anda mendefinisikan arti pengenal tersebut; batasi resolusinya seperti Anda membatasi paths, ke file yang disiapkan untuk tugas ini.

{
  "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 menulis path ini saat membaca halaman yang tidak tepercaya, sehingga implementasi tanpa batasan akan memungkinkan halaman berbahaya mengarahkan pengunggahan file apa pun yang dapat dibaca eksekutor ke situs yang dikendalikan halaman tersebut. Aktifkan anggota ini hanya ketika eksekutor Anda me-resolve setiap path (mengikuti symlink dan segmen ..) dan tidak menerima apa pun di luar direktori unggahan khusus yang masuk allowlist dan hanya berisi file yang dimaksudkan untuk tugas. Jangan gunakan ulang direktori unduhan browser untuk ini; jika Anda melakukannya, setiap file yang menyebabkan browser mengunduh oleh halaman menjadi dapat diunggah.

Menjalankan JavaScript di halaman

javascript_exec menjalankan ekspresi yang ditulis Claude dalam konteks halaman dan mengembalikan nilai ekspresi terakhir sebagai teks; Claude menulis ekspresi, bukan pernyataan return. Kode berjalan dengan hak akses penuh halaman, termasuk cookie, storage, dan permintaan same-origin-nya. Aktifkan anggota ini hanya dalam sesi yang tidak menyimpan kredensial, pertahankan allowlist domain dari Pertimbangan keamanan tetap berlaku, perlakukan nilai yang dikembalikan sebagai input yang tidak tepercaya, dan catat kode yang dikeluarkan Claude.

Membaca aktivitas konsol dan jaringan

read_console mengembalikan entri konsol tab dan read_network mengembalikan permintaan jaringannya, masing-masing sebagai teks dengan satu baris per entri yang terakumulasi sejak pembacaan sebelumnya dari tab tersebut. Baris konsol membawa entri log, peringatan, atau error; baris jaringan membawa metode, URL, status, tipe MIME, dan waktu. Entri hanya ada sejak saat otomatisasi browser Anda terhubung ke tab, sehingga hasil kosong tidak berarti tab yang sudah terbuka tidak memiliki lalu lintas.

Anggota ini memungkinkan Claude mendiagnosis halaman yang bermasalah (permintaan gagal di balik spinner, error skrip di balik tombol yang tidak berfungsi) tanpa tangkapan layar berulang. Entri konsol dan jaringan dikendalikan halaman dan sering berisi rahasia seperti token dalam URL permintaan, jadi sensor nilai yang menyerupai kredensial yang tidak Anda inginkan dalam konteks Claude dan potong entri yang sangat panjang sebelum mengembalikannya.

Melacak tab dengan browser_state

Claude merujuk tab berdasarkan tab_id, aplikasi Anda adalah sumber kebenaran mengenai tab mana yang ada, dan Anda melaporkan status tersebut dalam blok konten browser_state yang tidak pernah dilihat Claude secara langsung: API merender teks yang dibaca Claude darinya.

{
  "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 adalah inventaris lengkap tab yang terbuka setelah panggilan, bukan delta. Nilainya boleh kosong; setiap kali tidak kosong, tepat satu entri membawa "active": true.
• state_changes (tidak ditampilkan di sini) melaporkan efek samping dari panggilan: satu entri tab_opened untuk setiap tab yang dibuka oleh panggilan dan masih terbuka saat panggilan selesai, yang tab_id-nya juga harus muncul di tabs, serta peristiwa unduhan. Hilangkan field ini ketika tidak ada yang perlu dilaporkan; array kosong akan ditolak.
• Kirim blok ini hanya pada hasil yang menjawab panggilan anggota browser, paling banyak sekali per tool_result, dan jangan pernah pada hasil dengan is_error: true. Anda menyatakan "tidak ada status tab untuk dilaporkan" dengan menghilangkan blok tersebut.
• API merender tabs menjadi teks untuk Claude seperti yang dijelaskan dua bagian berikutnya; entri unduhan dalam state_changes divalidasi tetapi tidak dirender.

Anda yang menetapkan nilai tab_id. String stabil apa pun dapat digunakan, seperti pengidentifikasi halaman dari pustaka otomasi Anda atau penghitung Anda sendiri, selama Anda tidak menggunakan ulang tab_id saat tab dengan pengidentifikasi tersebut masih tercantum sebagai terbuka dalam hasil sebelumnya. API memberlakukan batasan berikut pada blok ini:

• Setiap tab_id, title, dan url boleh paling banyak 4.096 karakter, tab_id tidak boleh kosong, dan tidak satu pun boleh berisi karakter kontrol (termasuk baris baru) atau pemisah baris atau paragraf Unicode.
• Satu blok boleh mencantumkan paling banyak 100 tab dan 200 perubahan status.
• Batasan yang sama berlaku untuk tab_id yang diteruskan Claude ke switch_tab dan close_tab, karena API merendernya ke dalam teks hasil, jadi jawab panggilan yang tab_id-nya melanggar batasan tersebut dengan hasil error alih-alih blok browser_state.

Hasil manajemen tab

Untuk new_tab, switch_tab, close_tab, dan list_tabs, content dari hasil yang berhasil adalah tepat satu blok browser_state tanpa teks atau gambar, dan API menulis teks yang dilihat Claude. Blok pada hasil new_tab juga harus membawa tepat satu perubahan status tab_opened yang tab_id-nya cocok dengan entri yang ditandai active: true.

Hasil list_tabs yang bloknya mencantumkan dua tab dengan tab pertama aktif dirender sebagai berikut, dengan setiap baris diindentasi dua spasi dan (current) ditambahkan hanya pada tab aktif:

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

Hasil error untuk salah satu anggota ini adalah kebalikannya: teks error biasa dalam content, is_error: true, dan tanpa blok browser_state.

Sebagai contoh, ketika Claude memanggil new_tab (input-nya kosong), eksekutor Anda membuka tab, menjadikannya aktif, dan mengembalikan inventaris dengan satu entri 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 melihat Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab. Laporkan URL tempat tab dibuka, seperti di sini, bukan URL tujuan pengalihan setelahnya; hasil-hasil berikutnya melaporkan URL tab yang berlaku saat itu.

Konteks tab pada hasil lainnya

Pada setiap anggota lainnya, blok ini bersifat opsional: kirimkan ketika kumpulan tab yang terbuka, tab aktif, atau judul maupun URL suatu tab berubah, atau ketika ada state_changes untuk dilaporkan, dan selalu sertakan inventaris tabs lengkap. Ketika sebuah hasil membawa teks dan blok browser_state sekaligus, API menambahkan footer Tab Context pada teks hasil tersebut, dipisahkan dari teks Anda oleh satu baris kosong, sehingga Claude menerima status baru tanpa panggilan list_tabs terpisah:

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 menyebutkan tab tempat panggilan dijalankan, yaitu input tab_id-nya jika ada dan jika tidak, tab aktif, dan baris-baris tab pada footer tidak membawa penanda (current). Jangan menambahkan teks ini sendiri; kirim blok terstruktur dan biarkan API merendernya. Footer ini dideduplikasi, sehingga status tab yang identik tidak dirender lagi pada hasil berikutnya dan mengisi blok secara bebas tidak menimbulkan biaya apa pun.

Tiga kasus tidak merender footer meskipun blok ada:

• Hasil zoom apa pun.
• Hasil tanpa blok text (misalnya hasil screenshot yang hanya berisi gambar). Tidak ada yang dirender atau diingat untuk hasil tersebut; konteks tab muncul pada hasil berikutnya yang membawa teks dan blok browser_state sekaligus, jadi sertakan blok teks singkat bersama gambar ketika Anda ingin Claude melihat perubahan tab pada hasil yang sama.
• Hasil yang daftar tabs-nya kosong pada panggilan yang tidak membawa tab_id, karena tidak ada tab untuk disebutkan.

Sebagai contoh, ketika Claude mengklik tautan "Pricing" (ref_5) sebelumnya dalam sesi ini, halaman membukanya di tab baru yang tidak diminta Claude, dan tanpa laporan Claude harus memanggil list_tabs untuk menemukannya. Kembalikan konfirmasi klik ditambah blok yang state_changes-nya menyebutkan tab yang dibuka, dengan menandai tab mana pun yang dibiarkan aktif oleh eksekutor Anda:

{
  "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 melihat Clicked element ref_5. diikuti footer Tab Context yang ditampilkan sebelumnya. Tab yang dibuka selama panggilan yang gagal tidak mendapatkan entri tab_opened, karena hasil error tidak membawa browser_state; tab tersebut muncul dalam inventaris tabs pada hasil berhasil berikutnya. Dalam sebuah batch, lampirkan blok pada hasil dari panggilan tempat perubahan terjadi, dan berikan setiap hasil manajemen tab yang berhasil bloknya sendiri meskipun hasil sebelumnya dalam giliran yang sama telah melaporkan status yang sama.

Melaporkan unduhan

Ketika klik atau navigasi memulai unduhan file, laporkan dalam state_changes pada hasil dari panggilan tempat unduhan terjadi, dikorelasikan antarhasil dengan download_id yang Anda tetapkan. Unduhan berjalan secara asinkron dan dapat mencakup beberapa hasil, sehingga ada tiga jenis peristiwa:

API memvalidasi entri-entri ini tetapi tidak merendernya menjadi teks yang dilihat Claude, jadi ketika Claude perlu bertindak atas file tersebut, sebutkan juga nama file atau path dalam blok text pada hasil yang sama.

Sebagai contoh, klik pada "Download price list (CSV)" (ref_8) di tab Pricing memulai unduhan, sehingga hasil klik membawa entri download_started dengan download_id "dl-1" dan URL file. Unduhan selesai saat panggilan screenshot berikutnya sedang berjalan, sehingga content hasil tersebut berisi gambar, blok teks seperti Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes)., dan blok browser_state ini yang melaporkan penyelesaian di bawah download_id yang sama:

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

Laporan unduhan mengikuti aturan berikut:

• Paling banyak satu entri per download_id dalam satu blok, sehingga unduhan yang dimulai dan selesai selama panggilan yang sama hanya melaporkan download_completed.
• Jangan pernah mengirim state_changes pada hasil is_error: true; laporkan peristiwa unduhan yang terjadi selama panggilan yang gagal pada hasil berhasil berikutnya.
• state_changes bukan inventaris unduhan yang sedang berlangsung; laporkan setiap peristiwa sekali.
• Setiap entri hanya membawa field yang dideklarasikan oleh type-nya. size_bytes adalah bilangan bulat non-negatif, download_id tidak boleh kosong, dan download_id, url, path, serta error masing-masing paling banyak 4.096 karakter tanpa karakter kontrol atau pemisah baris atau paragraf Unicode. url berasal dari server jarak jauh dan sering membawa kredensial query-string bertanda tangan setelah pengalihan, jadi hapus parameter query yang tidak Anda inginkan dalam konteks Claude dan sanitasi sebelum melaporkannya atau menggunakannya dalam path sistem file.

Menangani error

Laporkan panggilan yang gagal kepada Claude sebagai hasil error biasa: is_error: true, konten teks yang menjelaskan apa yang salah, toolset_name digemakan kembali, dan tanpa blok browser_state.

Mengembalikan error dari eksekutor Anda

Buat teks error spesifik, karena Claude membacanya dan beradaptasi: Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable. memberi Claude sesuatu untuk ditindaklanjuti, sedangkan Error: navigation failed saja tidak. Kasus umum lainnya:

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

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

{
  "type": "tool_result",
  "tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: javascript_exec is not enabled in this environment."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Not executed: an earlier action in this turn failed."
}

Error permintaan

API memvalidasi entri toolset dan setiap blok tool_use dan tool_result anggota dalam percakapan. Ketika salah satunya salah bentuk, API mengembalikan invalid_request_error sebelum Claude berjalan. Dalam tabel berikut, kolom kiri menyebutkan apa yang Anda kirim.

Keterbatasan

• Ketersediaan platform: Browser use tersedia di Claude API dan Google Cloud.
• Hanya streaming input utuh: Ketika Anda melakukan streaming, input setiap anggota tiba sebagai satu input_json_delta lengkap (Toolset klien).
• Referensi elemen bersifat best-effort: Halaman yang sangat dinamis (daftar tervirtualisasi, antarmuka yang dirender dengan canvas, halaman yang merender ulang saat digulir) mungkin tidak mengekspos referensi yang stabil, dan Claude beralih ke screenshot dan klik koordinat di sana.
• read_console dan read_network bergantung pada otomasi browser Anda: Keduanya hanya melaporkan apa yang dapat ditangkapnya, dan hanya sejak saat otomasi tersebut terhubung ke sebuah tab.
• Keterbatasan agen umum berlaku: Latensi, akurasi vision, dan risiko prompt injection terbawa dari computer use (lihat Keterbatasan alat computer use), dan panduannya di bawah Mengoptimalkan kinerja model dengan prompting, Mengelola riwayat screenshot, dan Mengikuti praktik terbaik implementasi (penundaan aksi, validasi aksi, dan logging) juga berlaku untuk eksekutor browser.

Harga dan retensi data

Penggunaan browser mengikuti harga penggunaan alat standar. Saat menggunakan alat penggunaan browser:

Overhead definisi toolset: Mendeklarasikan browser_toolset_20260801 dengan anggota defaultnya menambahkan sekitar 6.600 token input ke sebuah permintaan (sekitar 6.610 pada Claude Fable 5, Claude Mythos 5, Claude Opus 5, dan Claude Opus 4.8, serta sekitar 6.670 pada Claude Sonnet 5), yang mencakup definisi alat anggota dan prompt sistem penggunaan alat. Mengaktifkan keempat anggota opsional menambahkan sekitar 880 token, dan menonaktifkan anggota dengan configs mengurangi jumlahnya. Jumlah pasti untuk sebuah permintaan dilaporkan dalam usage respons, dan Anda dapat memperkirakannya terlebih dahulu dengan endpoint penghitungan token.

Konsumsi token tambahan:

• Gambar tangkapan layar dan zoom yang dikembalikan dalam hasil alat, ditagih sebagai input gambar (lihat Harga Vision)
• Hasil alat berupa teks yang dikembalikan ke Claude, seperti pohon aksesibilitas, teks halaman, dan entri konsol atau jaringan

Sesi browser, unduhan, dan file yang diunggah tetap berada di lingkungan Anda; screenshot, teks halaman, dan status tab yang Anda kembalikan merupakan bagian dari konten permintaan API Anda dan mengikuti kebijakan retensi standar, atau pengaturan ZDR Anda jika Anda memilikinya. Alat browser use memenuhi syarat ZDR; lihat API dan retensi data untuk periode retensi dan kelayakan di seluruh fitur.

Langkah selanjutnya

Compatibility