Alat penggunaan komputer

Claude dapat berinteraksi dengan lingkungan komputer melalui alat "computer use" (penggunaan komputer), yang menyediakan kemampuan tangkapan layar serta kendali mouse/keyboard untuk interaksi desktop secara otonom.

Alat penggunaan komputer adalah sebuah client toolset (toolset klien) yang didefinisikan oleh Anthropic: satu entri {"type": "computer_toolset_20260801"} dalam tools memberi Claude 17 alat anggota seperti screenshot, left_click, type, dan zoom, dan aplikasi Anda menjalankan setiap panggilan di lingkungan yang Anda kendalikan. Alat ini saat ini belum tersedia di Claude Managed Agents. Panggilan Claude berupa blok tool_use yang name-nya adalah nama anggota dan yang membawa "toolset_name": "computer", sering kali beberapa per giliran (sebuah aksi batch).

Untuk tugas yang tetap berada di dalam halaman web, alat penggunaan browser lebih cocok: alat anggotanya membaca dan bertindak pada halaman itu sendiri, dan tidak memerlukan lingkungan desktop penuh.

Pertimbangan keamanan

Penggunaan komputer memiliki risiko unik yang berbeda dari fitur API standar. Risiko ini meningkat saat berinteraksi dengan internet.

Dalam beberapa keadaan, Claude akan mengikuti perintah yang ditemukan dalam konten meskipun bertentangan dengan instruksi Anda. Misalnya, instruksi pada halaman web atau yang terkandung dalam gambar dapat mengesampingkan instruksi Anda atau menyebabkan Claude membuat kesalahan. Ambil tindakan pencegahan untuk mengisolasi Claude dari data dan tindakan sensitif guna menghindari risiko terkait prompt injection.

Anthropic telah melatih model untuk menahan prompt injection ini dan telah menambahkan lapisan pertahanan ekstra. Jika Anda menggunakan alat penggunaan komputer, classifier akan berjalan secara otomatis pada prompt Anda untuk menandai potensi kejadian prompt injection. Ketika classifier ini mengidentifikasi potensi prompt injection dalam tangkapan layar, classifier akan secara otomatis mengarahkan model untuk meminta konfirmasi pengguna sebelum melanjutkan ke tindakan berikutnya. Perlindungan ekstra ini tidak akan ideal untuk setiap kasus penggunaan (misalnya, kasus penggunaan tanpa manusia dalam loop), jadi jika Anda ingin memilih keluar dan menonaktifkannya, hubungi dukungan.

Tindakan pencegahan ini tetap penting meskipun lapisan pertahanan classifier sudah ada.

Informasikan risiko yang relevan kepada pengguna akhir dan dapatkan persetujuan mereka sebelum mengaktifkan penggunaan komputer dalam produk Anda sendiri.

Mulai cepat

Tambahkan toolset penggunaan komputer ke array tools dari permintaan Messages API sebagai {"type": "computer_toolset_20260801"}. Permintaan ini tidak memerlukan header beta. Contoh ini juga mendeklarasikan alat editor teks dan alat bash, yang biasanya digunakan Claude bersama penggunaan komputer:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
)
print(response)

Ketika Claude bertindak pada desktop, respons memiliki stop_reason berupa tool_use dan berisi satu atau lebih blok tool_use anggota, masing-masing menyebutkan nama alat anggota dan membawa "toolset_name": "computer". Di tengah tugas ini, setelah Claude melihat tangkapan layar desktop, respons mungkin terlihat seperti ini:

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Aplikasi Anda menjalankan setiap panggilan secara berurutan di lingkungan Anda sendiri, mengembalikan satu blok tool_result per blok tool_use, dan memanggil API lagi; Cara kerja penggunaan komputer menjelaskan loop tersebut, dan bagian selanjutnya dari halaman ini menunjukkan cara mengimplementasikannya.

Cara kerja penggunaan komputer

1. 1

   Berikan Claude alat penggunaan komputer dan prompt pengguna

   • Tambahkan toolset penggunaan komputer (dan secara opsional alat lain) ke array tools dari permintaan API Anda.
   • Sertakan prompt pengguna yang memerlukan interaksi desktop, misalnya, "Simpan gambar kucing ke desktop saya."
2. 2

   Claude merespons dengan panggilan alat anggota

   • Claude menilai apakah bertindak pada desktop dapat membantu menjawab pertanyaan pengguna.
   • Jika ya, Claude merespons dengan satu atau lebih blok tool_use anggota, seperti screenshot, left_click, atau type, masing-masing membawa "toolset_name": "computer". Respons dengan beberapa blok ini adalah sebuah aksi batch.
   • Respons API memiliki stop_reason berupa tool_use, yang menandakan permintaan penggunaan alat.
3. 3

   Jalankan panggilan secara berurutan dan kembalikan hasilnya

   • Iterasi setiap blok tool_use dalam respons, secara berurutan. Untuk masing-masing, lakukan dispatch berdasarkan name anggota bersama toolset_name, dan lakukan tindakan tersebut dengan input blok pada container atau mesin virtual Anda.
   • Lanjutkan percakapan dengan pesan user baru yang berisi satu blok tool_result per blok tool_use, dicocokkan berdasarkan tool_use_id dan masing-masing menyertakan "toolset_name": "computer". Kembalikan gambar untuk screenshot dan zoom; teks singkat seperti OK sudah cukup untuk tindakan lainnya.
   • Jika suatu tindakan gagal, kembalikan is_error: true untuk blok tersebut dan jawab sisa batch seperti yang dijelaskan dalam Aksi batch.
4. 4

   Claude melanjutkan hingga tugas selesai

   • Claude menganalisis hasil alat untuk menentukan apakah diperlukan tindakan lebih lanjut atau tugas telah selesai.
   • Jika Claude menentukan bahwa diperlukan tindakan lebih lanjut, Claude merespons dengan stop_reason tool_use lainnya dan Anda harus kembali ke langkah 3.
   • Jika tidak, Claude mengembalikan respons teks kepada pengguna.

Pengulangan langkah 3 dan 4 tanpa input pengguna disebut sebagai "agent loop" (loop agen), yaitu Claude merespons dengan permintaan penggunaan alat dan aplikasi Anda merespons Claude dengan hasil evaluasi permintaan tersebut.

Aksi batch

Claude dapat merencanakan urutan tindakan singkat, seperti klik, ketik, lalu mengambil tangkapan layar, dan mengembalikannya bersama-sama dalam satu respons. Ini disebut "batch action" (aksi batch); aksi ini menggunakan bentuk respons yang sama dengan penggunaan alat paralel dengan satu perbedaan: Anda menjalankan blok secara berurutan, bukan secara bersamaan.

Respons dengan batch tiga tindakan terlihat seperti ini:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

Kembalikan satu blok tool_result untuk setiap blok tool_use, dicocokkan berdasarkan tool_use_id, semuanya dalam pesan user berikutnya. Setiap hasil untuk alat anggota harus membawa "toolset_name": "computer"; hasil yang menghilangkannya, atau yang menyebutkan toolset berbeda dari blok tool_use-nya, akan ditolak. Hanya hasil screenshot dan zoom yang memerlukan gambar; untuk anggota lainnya, pengakuan teks singkat seperti OK sudah cukup (cursor_position mengembalikan koordinat sebagai teks):

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

Jalankan blok secara berurutan dan berhenti pada kegagalan pertama. Tindakan selanjutnya dalam batch biasanya bergantung pada tindakan sebelumnya: type dalam contoh ini memasukkan teks ke apa pun yang difokuskan oleh klik sebelumnya. Jalankan blok secara berurutan sesuai urutan kemunculannya dalam content, dan jika salah satu gagal, jangan jalankan sisanya. Setiap blok tool_use tetap memerlukan tool_result, jadi jawab batch sebagai berikut:

• Untuk setiap tindakan yang berhasil, kembalikan hasil normalnya.
• Untuk tindakan yang gagal, kembalikan is_error: true dengan deskripsi teks tentang apa yang salah.
• Untuk setiap tindakan selanjutnya dalam batch, kembalikan is_error: true dengan teks persis berikut (alat penggunaan browser menggunakan teks penghentian miliknya sendiri):

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

Claude kemudian melihat tindakan mana yang berhasil, mana yang gagal, dan mana yang dilewati, lalu merencanakan ulang pada giliran berikutnya. Permintaan yang membiarkan blok tool_use mana pun dalam batch tidak terjawab akan ditolak dengan invalid_request_error, sehingga loop agen yang hanya membaca blok pertama akan gagal pada panggilan berikutnya. Jika aplikasi Anda meminta manusia untuk mengonfirmasi tindakan yang berdampak, lakukan pemeriksaan itu sebelum setiap blok dijalankan, karena sebuah batch dapat menyelesaikan tindakan multilangkah dalam satu giliran.

Claude biasanya mengakhiri batch dengan screenshot agar dapat mengamati hasilnya sebelum memutuskan apa yang harus dilakukan selanjutnya. Ketika batch tidak diakhiri dengan tangkapan layar, aplikasi Anda dapat melampirkan tangkapan layar sebagai blok image tambahan pada hasil terakhir dalam batch sehingga Claude selalu melihat keadaan layar saat ini, yang menghemat satu perjalanan bolak-balik dibandingkan menunggu Claude memintanya. Anda juga dapat meminta Claude melalui prompt untuk mengakhiri setiap batch dengan tangkapan layar (lihat Optimalkan kinerja model dengan prompting).

Lingkungan komputasi

Penggunaan komputer memerlukan lingkungan komputasi ter-sandbox tempat Claude dapat berinteraksi dengan aman dengan aplikasi dan web. Lingkungan ini mencakup:

1. Tampilan virtual: Server tampilan X11 virtual (menggunakan Xvfb) yang merender antarmuka desktop yang akan dilihat Claude melalui tangkapan layar dan dikendalikan dengan tindakan mouse/keyboard.

2. Lingkungan desktop: UI ringan dengan window manager (Mutter) dan panel (Tint2) yang berjalan di Linux, yang menyediakan antarmuka grafis yang konsisten untuk berinteraksi dengan Claude.

3. Aplikasi: Aplikasi Linux yang sudah terpasang seperti Firefox, LibreOffice, editor teks, dan pengelola file yang dapat digunakan Claude untuk menyelesaikan tugas.

4. Implementasi alat: Kode integrasi yang menerjemahkan permintaan alat abstrak Claude (seperti "gerakkan mouse" atau "ambil tangkapan layar") menjadi operasi aktual di lingkungan virtual.

5. Loop agen: Program yang menangani komunikasi antara Claude dan lingkungan, mengirimkan tindakan Claude ke lingkungan dan mengembalikan hasilnya (tangkapan layar, output perintah) kembali ke Claude.

Saat Anda menggunakan penggunaan komputer, Claude tidak terhubung langsung ke lingkungan ini. Sebaliknya, aplikasi Anda:

1. Menerima permintaan penggunaan alat dari Claude
2. Menerjemahkannya menjadi tindakan di lingkungan komputasi Anda
3. Menangkap hasilnya (seperti tangkapan layar dan output perintah)
4. Mengembalikan hasil ini ke Claude

Untuk keamanan dan isolasi, implementasi referensi menjalankan semua ini di dalam container Docker dengan pemetaan port yang sesuai untuk melihat dan berinteraksi dengan lingkungan.

Cara mengimplementasikan penggunaan komputer

Meningkatkan versi integrasi computer_20251124 yang sudah ada? Mulailah dengan Migrasi dari computer_20251124; sisa bagian ini berlaku untuk integrasi baru maupun yang dimigrasikan.

Pahami loop agen

Inti dari penggunaan komputer adalah "loop agen": sebuah siklus di mana Claude meminta tindakan alat, aplikasi Anda menjalankannya, dan mengembalikan hasilnya ke Claude. Loop ini menggunakan client yang Anda buat di Mulai cepat, array tools yang hanya mendeklarasikan toolset penggunaan komputer, dan helper pemrosesan panggilan alat di bawah Implementasikan alat penggunaan komputer. Jika Anda juga mendeklarasikan alat lain, seperti alat bash dan editor teks dari Mulai cepat, lakukan dispatch blok tool_use mereka dalam proses yang sama; helper hanya menjawab panggilan anggota penggunaan komputer, dan loop memperlakukan giliran tanpa panggilan yang terjawab sebagai selesai. Berikut contoh yang disederhanakan:

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # Tambahkan respons Claude ke riwayat percakapan
        messages.append({"role": "assistant", "content": response.content})

        # Jalankan aksi yang diminta Claude, secara berurutan, dan kumpulkan hasilnya
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # Kirim semua hasil kembali ke Claude dalam satu pesan user
        messages.append({"role": "user", "content": tool_results})

    return messages

Loop berlanjut hingga Claude merespons tanpa meminta alat apa pun (tugas selesai) atau batas iterasi maksimum tercapai. Pengaman ini mencegah potensi loop tak terbatas yang dapat mengakibatkan biaya API yang tidak terduga.

Optimalkan kinerja model dengan prompting

1. Tentukan tugas yang sederhana dan terdefinisi dengan baik serta berikan instruksi eksplisit untuk setiap langkah.
2. Claude terkadang mengasumsikan hasil dari tindakannya tanpa secara eksplisit memeriksa hasilnya. Untuk mencegah hal ini, Anda dapat memberi prompt kepada Claude dengan After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
3. Beberapa elemen UI (seperti dropdown dan scrollbar) mungkin sulit dimanipulasi oleh Claude menggunakan gerakan mouse. Jika Anda mengalami hal ini, coba beri prompt kepada model untuk menggunakan pintasan keyboard.
4. Untuk tugas atau interaksi UI yang berulang, sertakan contoh tangkapan layar dan panggilan alat dari hasil yang berhasil dalam prompt Anda.
5. Jika Anda memerlukan model untuk login, berikan nama pengguna dan kata sandi dalam prompt Anda di dalam tag XML seperti <robot_credentials>. Menggunakan penggunaan komputer dalam aplikasi yang memerlukan login meningkatkan risiko hasil buruk akibat prompt injection. Tinjau Mitigasi jailbreak dan prompt injection sebelum memberikan kredensial login kepada model.
6. Saat menyusun array content dari giliran pengguna, tempatkan teks instruksi sebelum gambar tangkapan layar. Memberikan deskripsi target sebelum gambar diproses meningkatkan akurasi klik.
7. Claude menggunakan tindakan zoom untuk memeriksa suatu wilayah pada resolusi penuh ketika ditanya tentang teks kecil atau elemen UI tertentu yang tidak terbaca pada resolusi default tangkapan layar, seperti nama file di sidebar, judul tab, teks status-bar, nomor baris, atau label tombol. Jika Claude tidak melakukan zoom saat Anda mengharapkannya, tanyakan tentang wilayah atau elemen tertentu, bukan layar secara keseluruhan.
8. Jika Anda ingin setiap aksi batch diakhiri dengan tangkapan layar, nyatakan hal itu dalam prompt sistem, misalnya, End each group of actions with a screenshot so you can verify the result before continuing.

Prompt sistem

Saat Anda menyertakan alat penggunaan komputer dalam permintaan, API menghasilkan "system prompt" (prompt sistem) khusus penggunaan komputer. Prompt ini mirip dengan prompt sistem penggunaan alat tetapi dimulai dengan:

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

Seperti pada penggunaan alat biasa, parameter system yang diberikan pengguna tetap dihormati dan digunakan dalam penyusunan prompt sistem gabungan.

Tindakan yang tersedia

Setiap tindakan adalah alat anggota dari toolset penggunaan komputer: Claude menyebutkan nama anggota dalam blok tool_use yang membawa "toolset_name": "computer", dan input blok hanya berisi parameter anggota tersebut, tanpa field action. Toolset ini memiliki 17 alat anggota:

Perhatikan hal-hal berikut saat mengimplementasikan anggota:

• Koordinat dalam piksel tangkapan layar. Setiap nilai coordinate, start_coordinate, dan region, serta posisi yang dilaporkan cursor_position, berada dalam ruang piksel tangkapan layar tampilan penuh yang Anda kembalikan, dengan titik asal di kiri atas. Gambar zoom tidak mengubah hal ini: setelah zoom, Claude tetap menyatakan koordinat dalam ruang tangkapan layar penuh, tidak pernah relatif terhadap gambar yang di-zoom. Jika Anda memperkecil tangkapan layar sebelum mengembalikannya, skalakan kembali koordinat Claude sebelum menerapkannya ke tampilan sebenarnya (lihat Sesuaikan ukuran tangkapan layar agar sesuai batas gambar).
• Semua anggota diaktifkan secara default, termasuk zoom. Jika lingkungan Anda tidak dapat menghasilkan gambar zoom, tahan anggota tersebut dengan configs (lihat Parameter alat) daripada membiarkannya aktif dan mengembalikan error. Jika Claude memanggil anggota yang Anda tahan atau tidak Anda implementasikan, kembalikan tool_result dengan is_error: true untuk blok tersebut.
• Lakukan dispatch berdasarkan pasangan (toolset_name, name). toolset_name adalah yang menandai sebuah blok sebagai tindakan komputer: alat kustom dalam permintaan yang sama dapat memiliki nama yang sama dengan anggota, dan versi toolset yang lebih baru dapat menambahkan anggota (lihat Toolset klien).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

Parameter alat

Entri toolset dalam array tools menerima empat parameter; aturan yang dimilikinya bersama toolset penggunaan browser tercantum di bawah Toolset klien.

Misalnya, entri ini menahan zoom untuk lingkungan yang tidak mengimplementasikannya dan menetapkan breakpoint cache pada definisi toolset:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

Jika loop agen Anda hanya dapat menjalankan satu tindakan per perjalanan bolak-balik, setel disable_parallel_tool_use ke true dalam tool_choice; Claude kemudian mengembalikan paling banyak satu blok tool_use anggota per giliran (lihat Nonaktifkan penggunaan alat paralel).

Entri ini menolak parameter berikut dari versi alat sebelumnya, dan permintaan yang menyertakan salah satunya mengembalikan invalid_request_error:

• name: nama anggota ditetapkan oleh versi toolset.
• display_width_px, display_height_px, dan display_number: koordinat selalu berada dalam ruang piksel tangkapan layar yang Anda kembalikan.
• enable_zoom: zoom adalah alat anggota yang Anda kendalikan melalui configs.

Entri ini juga tidak dapat dideklarasikan dalam permintaan yang sama dengan entri computer_20251124 atau alat lain bernama computer. Untuk strict, input_examples, penempatan defer_loading, tool_choice, streaming, dan pembatasan pemanggil, lihat Toolset klien.

Menggabungkan dengan thinking

Untuk menggabungkan penggunaan komputer dengan thinking, lihat Thinking.

Memperkaya penggunaan komputer dengan alat lain

Untuk menambahkan alat lain bersama penggunaan komputer, sertakan alat tersebut dalam array tools yang sama. Bagian Mulai cepat menunjukkan pola ini dengan alat bash dan alat editor teks. Anda dapat menambahkan definisi alat kustom Anda sendiri dengan cara yang sama.

Untuk tugas yang tetap berada di dalam halaman web, Anda juga dapat mendeklarasikan alat penggunaan browser dalam permintaan yang sama: kedua toolset bekerja secara independen, masing-masing dalam kerangka koordinatnya sendiri, dan panggilan ke anggota yang memiliki nama sama, seperti screenshot atau key, dibedakan berdasarkan toolset_name.

Bangun lingkungan penggunaan komputer kustom

Implementasi referensi dimaksudkan untuk membantu Anda memulai penggunaan komputer. Implementasi ini mencakup semua komponen yang diperlukan agar Claude dapat menggunakan komputer. Namun, Anda dapat membangun lingkungan Anda sendiri untuk penggunaan komputer sesuai kebutuhan Anda. Anda akan memerlukan:

• Lingkungan tervirtualisasi atau dalam container yang cocok untuk penggunaan komputer dengan Claude
• Implementasi tindakan-tindakan alat penggunaan komputer
• Loop agen yang berinteraksi dengan Claude API dan menjalankan hasil tool_use menggunakan implementasi alat Anda
• API atau UI yang memungkinkan input pengguna untuk memulai loop agen

Implementasikan alat penggunaan komputer

Alat penggunaan komputer diimplementasikan sebagai alat tanpa skema. Saat menggunakan alat ini, Anda tidak perlu menyediakan skema input seperti pada alat lain; skema sudah tertanam dalam model Claude dan tidak dapat dimodifikasi.

1. 1

   Siapkan lingkungan komputasi Anda

   Buat tampilan virtual atau hubungkan ke tampilan yang sudah ada yang akan berinteraksi dengan Claude. Ini biasanya melibatkan penyiapan Xvfb (X Virtual Framebuffer) atau teknologi serupa.

2. 2

   Implementasikan handler tindakan

   Buat fungsi untuk menangani setiap jenis tindakan yang mungkin diminta Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Data gambar placeholder; executor sungguhan menangkap layar dan mengembalikan byte PNG
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   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 click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       if name == "screenshot":
           return capture_screenshot()
       elif name == "left_click":
           # coordinate bersifat opsional; tanpanya, klik di posisi kursor saat ini
           return click(tool_input.get("coordinate"))
       elif name == "type":
           return type_text(tool_input["text"])
       # Tangani aksi lain sesuai kebutuhan
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Proses panggilan alat Claude

   Ekstrak dan jalankan panggilan alat dari respons Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer 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 computer yang dideklarasikan; arahkan alat lain ke sini jika Anda menambahkannya
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # Sebuah string, atau daftar blok konten seperti gambar screenshot
                   result["content"] = handle_computer_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

4. 4

   Implementasikan loop agen

   Bungkus dua langkah sebelumnya dalam sebuah loop yang mengirimkan hasilnya kembali dan mengulang hingga Claude tidak mengembalikan panggilan alat anggota; Pahami loop agen menunjukkan loop ini dalam setiap bahasa.

Tangani error

Laporkan tindakan yang gagal kepada Claude sebagai tool_result dengan is_error: true dan deskripsi singkat, serta sertakan "toolset_name": "computer" seperti pada hasil anggota lainnya. Jika tindakan yang gagal merupakan bagian dari aksi batch, jawab blok yang tersisa dalam batch dengan teks penghentian yang ditunjukkan di sana alih-alih menjalankannya.

Misalnya, ketika pengambilan tangkapan layar gagal:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

Gunakan bentuk yang sama untuk koordinat di luar batas tampilan dan untuk tindakan yang gagal dijalankan, dengan pesan yang menyatakan apa yang salah.

Sesuaikan ukuran tangkapan layar agar sesuai batas gambar

Tangkapan layar dan gambar zoom yang Anda kembalikan ke toolset penggunaan komputer harus sudah muat dalam batas ukuran gambar model Anda: toolset tidak menerima dimensi tampilan dan API tidak memperkecil untuk Anda, sehingga gambar tool_result yang terlalu besar ditolak dengan error validasi. Karena Claude mengembalikan koordinat dalam ruang piksel gambar yang dilihatnya, simpan faktor skala yang Anda gunakan agar Anda dapat memetakan koordinat tersebut kembali ke layar Anda.

Jika layar Anda lebih besar dari batas, ubah ukuran setiap tangkapan layar sebelum mengembalikannya dan skalakan koordinat yang dikembalikan Claude kembali ke ruang layar asli. Karena toolset tidak menerima dimensi tampilan, pengubahan ukuran dan penskalaan koordinat dalam kode aplikasi Anda adalah semua yang Anda perlukan:

import math

screen_width, screen_height = 1512, 982


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# Saat mengambil tangkapan layar
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Ubah ukuran gambar ke dimensi yang diskalakan sebelum mengirimnya ke Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# Saat menangani koordinat dari Claude, skalakan kembali ke ukuran semula
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Saat Anda memilih resolusi tampilan dan mengembalikan tangkapan layar:

• Untuk tugas desktop umum, gunakan 1024x768 atau 1280x720; untuk aplikasi web, gunakan 1280x800 atau 1366x768.
• Hindari resolusi di atas 1920x1080 untuk mencegah masalah kinerja.
• Enkode tangkapan layar sebagai PNG atau JPEG base64, dan pertimbangkan untuk mengompresi tangkapan layar besar guna meningkatkan kinerja.
• Sertakan metadata yang relevan seperti timestamp atau status tampilan.
• Jika Anda menggunakan resolusi lebih tinggi, pastikan koordinat diskalakan secara akurat.

Mengelola riwayat tangkapan layar

Loop agen yang panjang mengakumulasi tangkapan layar dengan cepat (kira-kira 1.000–1.800 token input masing-masing). Batas permintaan API juga berlaku. Begitu satu permintaan membawa lebih dari 20 gambar, setiap gambar di dalamnya dikenai batas per sisi yang lebih ketat. Loop yang menyimpan riwayat tangkapan layarnya mencapai jumlah tersebut dalam beberapa puluh giliran, jadi ubah ukuran setiap tangkapan layar sehingga tidak ada sisi yang melebihi 2000 px atau pangkas tangkapan layar lama agar tetap 20 atau kurang dalam permintaan.

Agar caching prompt tetap efektif sambil membatasi konteks:

• Tempatkan satu breakpoint cache_control setelah prompt sistem dan definisi alat, dan hingga tiga lagi pada blok tool_result terakhir dari masing-masing giliran terbaru, dengan memajukannya setiap giliran. Dalam aksi batch, penanda pada beberapa blok bertindak sebagai satu breakpoint tetapi masing-masing tetap dihitung terhadap batas empat, jadi gunakan satu per giliran.
• Pangkas tangkapan layar lama secara batch, bukan satu per giliran. Membuang satu tangkapan layar setiap giliran mengubah prefiks setiap giliran dan membatalkan cache. Default yang wajar adalah menyimpan tiga tangkapan layar terakhir dan memangkas setiap 25 giliran, sehingga prefiks tetap identik byte demi byte di antara peristiwa pemangkasan; jika tangkapan layar Anda melebihi 2000 px pada salah satu sisi, pilih interval yang menjaga setiap permintaan pada 20 gambar atau kurang.
• Pada Claude Fable 5.1, hindari pemangkasan di sisi klien: menghapus tangkapan layar sebelumnya membatalkan setiap blok thinking berikutnya dalam setiap permintaan yang masih membawa giliran tersebut. Sebagai gantinya, ubah ukuran tangkapan layar menjadi 2000 px atau kurang per sisi, dan gunakan pembersihan hasil alat di sisi server untuk membuang yang lama dari konteks. Jika Anda harus memangkas, pertahankan pengaturan prefix_mismatch_behavior: "drop_block" sejak saat itu; setelah setiap pemangkasan, Claude melanjutkan tanpa thinking yang dihasilkan sejak tangkapan layar yang dipangkas, pada permintaan tersebut dan setiap permintaan berikutnya.

Mendiagnosis masalah klik

Jika klik meleset dari targetnya, penyebabnya biasanya salah satu dari berikut ini:

Ikuti praktik terbaik implementasi

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

Migrasi dari computer_20251124

Peningkatan dari computer_20251124 ke toolset bersifat opsional: model yang tercantum untuk computer_20251124 di bawah Versi alat sebelumnya tetap menerimanya dengan header beta-nya, sehingga integrasi yang ada tetap berfungsi sampai Anda mengubahnya. Untuk meningkatkan, lakukan perubahan berikut secara bersamaan:

1. Hapus header beta. Buang anthropic-beta: computer-use-2025-11-24 dari permintaan Anda. Di SDK, hapus parameter betas dan panggil Messages API melalui klien standar alih-alih namespace beta.
2. Ubah entri tools. Atur type ke computer_toolset_20260801 dan hapus name, display_width_px, display_height_px, display_number, dan enable_zoom. Toolset menolak masing-masing field ini.
3. Pilih apakah zoom tetap diaktifkan. Zoom diaktifkan secara default pada toolset, sedangkan enable_zoom default-nya false. Jika lingkungan Anda tidak mengimplementasikan zoom, tambahkan "configs": {"zoom": {"enabled": false}} untuk mempertahankan perilaku sebelumnya; jika tidak, implementasikan (lihat Aksi yang tersedia).
4. Tangani setiap blok dalam satu giliran. Perbarui loop agen Anda untuk mengiterasi setiap blok tool_use dalam respons alih-alih hanya membaca yang pertama, dan untuk melakukan dispatch berdasarkan name blok bersama dengan toolset_name alih-alih berdasarkan input.action. Input anggota tidak lagi berisi field action; field lainnya tidak berubah.
5. Jalankan blok secara berurutan dan gunakan teks penghentian. Jalankan blok secara berurutan, berhenti pada kegagalan pertama, dan jawab blok yang tersisa dengan Not executed: an earlier computer action in this turn failed. seperti dijelaskan dalam Aksi batch. Jika loop Anda belum dapat menjalankan batch, Parameter alat menjelaskan cara membatasi Claude ke satu aksi per giliran.
6. Gemakan toolset_name pada hasil. Tambahkan "toolset_name": "computer" ke setiap tool_result yang menjawab panggilan anggota. Hasil hanya boleh berisi konten text dan image.
7. Dukung repeat pada key. Anggota key menerima hitungan repeat opsional dari 1 hingga 100. Handler yang mengabaikan field yang tidak dikenali akan menekan tombol sekali, jadi pastikan handler key Anda menghormati repeat.
8. Ubah ukuran tangkapan layar sendiri. Toolset menolak tangkapan layar atau gambar zoom yang melebihi batas gambar model alih-alih menurunkan skalanya. Ubah ukuran sebelum mengembalikan gambar dan tetap skalakan koordinat seperti dijelaskan dalam Menyesuaikan ukuran tangkapan layar agar sesuai batas gambar.
9. Hapus opsi yang tidak didukung. Pindahkan defer_loading apa pun dari entri ke dalam configs, dengan nilai yang sama pada setiap anggota yang diaktifkan. Opsi lain yang tidak didukung pada entri toolset tercantum di bawah Toolset klien.

Ini adalah entri tools sebelum perubahan, dikirim dengan header anthropic-beta: computer-use-2025-11-24:

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

Ini adalah entri tools setelah perubahan, dikirim tanpa header beta. Objek configs menjaga zoom tetap nonaktif agar sesuai dengan entri sebelumnya, yang tidak mengatur enable_zoom; hilangkan configs sepenuhnya untuk menerima default dan membiarkan Claude melakukan zoom:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

Pasangan berikut menunjukkan blok tool_use sebelum dan sesudah perubahan. Nama aksi berpindah dari input.action ke name, dan blok mendapatkan toolset_name:

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

Versi alat sebelumnya

Dua versi sebelumnya dari alat computer use tetap tersedia dalam beta untuk integrasi yang ada, untuk model yang tidak mendukung toolset, dan pada platform tempat toolset saat ini belum tersedia. Masing-masing memerlukan header beta-nya pada setiap permintaan, dan parameternya didokumentasikan dalam referensi Messages API beta. Di SDK, teruskan header melalui parameter betas dan gunakan namespace beta; hanya alat computer use yang memerlukan header tersebut, bukan alat bash atau editor teks dalam permintaan yang sama.

Keterbatasan

1. Latensi: Latensi computer use saat ini untuk interaksi manusia-AI mungkin terlalu lambat dibandingkan dengan aksi komputer biasa yang diarahkan manusia. Fokuslah pada kasus penggunaan di mana kecepatan tidak kritis (misalnya, pengumpulan informasi latar belakang, pengujian perangkat lunak otomatis) di lingkungan tepercaya.
2. Akurasi dan keandalan computer vision: Claude mungkin membuat kesalahan atau berhalusinasi saat mengeluarkan koordinat spesifik ketika menghasilkan aksi. Output thinking yang diringkas Claude dapat membantu Anda memahami penalaran model dan mengidentifikasi potensi masalah; atur display: "summarized" pada konfigurasi thinking, karena model yang mendukung toolset menghilangkan teks thinking secara default.
3. Akurasi dan keandalan pemilihan alat: Claude mungkin membuat kesalahan atau berhalusinasi saat memilih alat ketika menghasilkan aksi atau mengambil aksi tak terduga untuk menyelesaikan masalah. Selain itu, keandalan mungkin lebih rendah saat berinteraksi dengan aplikasi khusus atau beberapa aplikasi sekaligus. Berikan prompt kepada model dengan hati-hati saat meminta tugas yang kompleks.
4. Keandalan scrolling: Aksi scroll mendukung kontrol arah (atas, bawah, kiri, kanan) dan jumlah yang ditentukan. Pada aplikasi di mana scrolling tidak berpengaruh, alternatif keyboard seperti Page Down dapat membantu.
5. Interaksi spreadsheet: Gunakan aksi kontrol mouse yang terperinci (left_mouse_down, left_mouse_up) dan kombinasi tombol modifier untuk memilih sel individual. Operasi spreadsheet yang kompleks mungkin masih memerlukan beberapa percobaan.
6. Pembuatan akun dan pembuatan konten di platform sosial dan komunikasi: Meskipun Claude mengunjungi situs web, kemampuannya untuk membuat akun, menghasilkan dan membagikan konten, atau terlibat dalam peniruan manusia di situs web dan platform media sosial terbatas.
7. Kerentanan: Jailbreak dan injeksi prompt dapat memengaruhi computer use sebagaimana dapat memengaruhi sistem AI frontier apa pun, termasuk melalui instruksi yang disematkan dalam halaman web atau gambar; terapkan tindakan pencegahan dalam Pertimbangan keamanan.
8. Aksi yang tidak pantas atau ilegal: Berdasarkan Ketentuan Layanan Anthropic, Anda tidak boleh menggunakan computer use untuk melanggar hukum apa pun atau Kebijakan Penggunaan yang Dapat Diterima.

Selalu tinjau dan verifikasi dengan cermat aksi dan log computer use Claude. Jangan gunakan Claude untuk tugas yang memerlukan presisi sempurna atau informasi pengguna yang sensitif tanpa pengawasan manusia.

Retensi data

Computer use adalah alat sisi klien. Semua tangkapan layar, aksi mouse, input keyboard, dan file apa pun yang terlibat dalam sesi ditangkap dan disimpan di lingkungan Anda, bukan oleh Anthropic. Anthropic memproses gambar tangkapan layar dan permintaan aksi secara real time sebagai bagian dari panggilan API. Retensi untuk permintaan API tersebut diatur oleh API dan retensi data.

Karena aplikasi Anda mengontrol di mana dan bagaimana data computer use disimpan, computer use memenuhi syarat ZDR. Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Harga

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

Overhead definisi toolset: Mendeklarasikan computer_toolset_20260801 dengan anggota defaultnya menambahkan sekitar 4.500 token input ke sebuah permintaan (sekitar 4.520 pada Claude Fable 5, Claude Mythos 5, Claude Opus 5, dan Claude Opus 4.8, serta sekitar 4.590 pada Claude Sonnet 5), yang mencakup definisi alat anggota dan prompt sistem penggunaan alat. Menonaktifkan zoom dengan configs menghapus sekitar 410 dari token tersebut. Jumlah pasti untuk sebuah permintaan dilaporkan dalam usage respons, dan Anda dapat memperkirakannya terlebih dahulu dengan endpoint penghitungan token.

Versi alat sebelumnya: Angka-angka berikut berlaku untuk versi alat computer_20251124 dan computer_20250124, bukan untuk computer_toolset_20260801:

• Overhead prompt sistem: 466–499 token ditambahkan ke prompt sistem
• Definisi alat: sekitar 735 token input per definisi alat (diukur dengan computer_20250124)

Konsumsi token tambahan:

• Gambar tangkapan layar dan zoom yang dikembalikan dalam hasil alat, ditagih sebagai input gambar (lihat Harga Vision)
• Hasil eksekusi alat yang dikembalikan ke Claude

Langkah selanjutnya

Compatibility