Tool penggunaan komputer

Claude dapat berinteraksi dengan lingkungan komputer melalui tool penggunaan komputer, yang menyediakan kemampuan screenshot dan kontrol mouse/keyboard untuk interaksi desktop otonom.

​

Gambaran Umum

Penggunaan komputer adalah fitur beta yang memungkinkan Claude berinteraksi dengan lingkungan desktop. Tool ini menyediakan:

• Tangkapan screenshot: Melihat apa yang sedang ditampilkan di layar
• Kontrol mouse: Klik, seret, dan gerakkan kursor
• Input keyboard: Ketik teks dan gunakan pintasan keyboard
• Otomasi desktop: Berinteraksi dengan aplikasi atau antarmuka apa pun

Meskipun penggunaan komputer dapat ditingkatkan dengan tool lain seperti bash dan text editor untuk alur kerja otomasi yang lebih komprehensif, penggunaan komputer secara khusus merujuk pada kemampuan tool penggunaan komputer untuk melihat dan mengontrol lingkungan desktop.

​

Kompatibilitas model

Penggunaan komputer tersedia untuk model Claude berikut:

​

Pertimbangan keamanan

​

Mulai cepat

Berikut cara memulai dengan penggunaan komputer:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",  # atau model kompatibel lainnya
    max_tokens=1024,
    tools=[
        {
          "type": "computer_20250124",
          "name": "computer",
          "display_width_px": 1024,
          "display_height_px": 768,
          "display_number": 1,
        },
        {
          "type": "text_editor_20250124",
          "name": "str_replace_editor"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
    ],
    messages=[{"role": "user", "content": "Simpan gambar kucing ke desktop saya."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

​

Cara kerja penggunaan komputer

Kami merujuk pada pengulangan langkah 3 dan 4 tanpa input pengguna sebagai “loop agen” - yaitu, Claude merespons dengan permintaan penggunaan tool dan aplikasi Anda merespons Claude dengan hasil evaluasi permintaan tersebut.

​

Lingkungan komputasi

Penggunaan komputer memerlukan lingkungan komputasi yang terisolasi di mana Claude dapat berinteraksi dengan aman dengan aplikasi dan web. Lingkungan ini mencakup:

1. Display virtual: Server display virtual X11 (menggunakan Xvfb) yang merender antarmuka desktop yang akan dilihat Claude melalui screenshot dan dikontrol 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 terinstal seperti Firefox, LibreOffice, text editor, dan file manager yang dapat digunakan Claude untuk menyelesaikan tugas.

4. Implementasi tool: Kode integrasi yang menerjemahkan permintaan tool abstrak Claude (seperti “gerakkan mouse” atau “ambil screenshot”) menjadi operasi aktual di lingkungan virtual.

5. Loop agen: Program yang menangani komunikasi antara Claude dan lingkungan, mengirim tindakan Claude ke lingkungan dan mengembalikan hasil (screenshot, output perintah) kembali ke Claude.

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

1. Menerima permintaan penggunaan tool Claude
2. Menerjemahkannya menjadi tindakan di lingkungan komputasi Anda
3. Menangkap hasil (screenshot, output perintah, dll.)
4. Mengembalikan hasil ini ke Claude

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

​

Cara mengimplementasikan penggunaan komputer

​

Mulai dengan implementasi referensi kami

Kami telah membangun implementasi referensi yang mencakup semua yang Anda butuhkan untuk memulai dengan cepat dengan penggunaan komputer:

• Lingkungan terkontainerisasi yang cocok untuk penggunaan komputer dengan Claude
• Implementasi tool penggunaan komputer
• Loop agen yang berinteraksi dengan API Anthropic dan mengeksekusi tool penggunaan komputer
• Antarmuka web untuk berinteraksi dengan kontainer, loop agen, dan tool.

​

Memahami loop multi-agen

Inti dari penggunaan komputer adalah “loop agen” - siklus di mana Claude meminta tindakan tool, aplikasi Anda mengeksekusinya, dan mengembalikan hasil ke Claude. Berikut contoh yang disederhanakan:

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Tambahkan batas iterasi untuk mencegah loop tak terbatas
):
    """
    Loop agen sederhana untuk interaksi penggunaan komputer Claude.

    Fungsi ini menangani bolak-balik antara:
    1. Mengirim pesan pengguna ke Claude
    2. Claude meminta untuk menggunakan tool
    3. Aplikasi Anda mengeksekusi tool tersebut
    4. Mengirim hasil tool kembali ke Claude
    """
    # Siapkan tool dan parameter API
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Konfigurasi tool - Anda harus sudah menginisialisasi ini di tempat lain
    tools = [
        {"type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"}
    ]

    # Loop agen utama (dengan batas iterasi untuk mencegah biaya API yang tidak terkendali)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Siapkan parameter thinking opsional (untuk Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Panggil API Claude
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking
        )

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

        # Periksa apakah Claude menggunakan tool apa pun
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # Dalam aplikasi nyata, Anda akan mengeksekusi tool di sini
                # Misalnya: result = run_tool(block.name, block.input)
                result = {"result": "Tool berhasil dieksekusi"}

                # Format hasil untuk Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Jika tidak ada tool yang digunakan, Claude selesai - kembalikan pesan akhir
        if not tool_results:
            return messages

        # Tambahkan hasil tool ke pesan untuk iterasi berikutnya dengan Claude
        messages.append({"role": "user", "content": tool_results})

Loop berlanjut sampai Claude merespons tanpa meminta tool apa pun (penyelesaian tugas) atau batas iterasi maksimum tercapai. Pengamanan ini mencegah kemungkinan loop tak terbatas yang dapat menghasilkan biaya API yang tidak terduga.

Kami merekomendasikan untuk mencoba implementasi referensi sebelum membaca sisa dokumentasi ini.

​

Optimalkan performa model dengan prompting

Berikut beberapa tips tentang cara mendapatkan output berkualitas terbaik:

1. Tentukan tugas yang sederhana dan terdefinisi dengan baik dan berikan instruksi eksplisit untuk setiap langkah.
2. Claude terkadang mengasumsikan hasil tindakannya tanpa secara eksplisit memeriksa hasilnya. Untuk mencegah ini, Anda dapat meminta Claude dengan Setelah setiap langkah, ambil screenshot dan evaluasi dengan hati-hati apakah Anda telah mencapai hasil yang benar. Tunjukkan pemikiran Anda secara eksplisit: "Saya telah mengevaluasi langkah X..." Jika tidak benar, coba lagi. Hanya ketika Anda mengonfirmasi langkah telah dieksekusi dengan benar, Anda harus melanjutkan ke langkah berikutnya.
3. Beberapa elemen UI (seperti dropdown dan scrollbar) mungkin sulit untuk dimanipulasi Claude menggunakan gerakan mouse. Jika Anda mengalami ini, coba minta model untuk menggunakan pintasan keyboard.
4. Untuk tugas yang dapat diulang atau interaksi UI, sertakan contoh screenshot dan panggilan tool dari hasil yang berhasil dalam prompt Anda.
5. Jika Anda perlu model untuk login, berikan username dan password dalam prompt Anda di dalam tag xml seperti <robot_credentials>. Menggunakan penggunaan komputer dalam aplikasi yang memerlukan login meningkatkan risiko hasil buruk sebagai akibat dari injeksi prompt. Silakan tinjau panduan kami tentang mitigasi injeksi prompt sebelum memberikan model kredensial login.

​

Prompt sistem

Ketika salah satu tool yang didefinisikan Anthropic diminta melalui API Anthropic, prompt sistem khusus penggunaan komputer dihasilkan. Ini mirip dengan prompt sistem penggunaan tool tetapi dimulai dengan:

Anda memiliki akses ke serangkaian fungsi yang dapat Anda gunakan untuk menjawab pertanyaan pengguna. Ini termasuk akses ke lingkungan komputasi yang terisolasi. Anda TIDAK saat ini memiliki kemampuan untuk memeriksa file atau berinteraksi dengan sumber daya eksternal, kecuali dengan memanggil fungsi di bawah ini.

Seperti dengan penggunaan tool biasa, field system_prompt yang disediakan pengguna masih dihormati dan digunakan dalam konstruksi prompt sistem gabungan.

​

Tindakan yang tersedia

Tool penggunaan komputer mendukung tindakan ini:

Tindakan dasar (semua versi)

• screenshot - Tangkap display saat ini
• left_click - Klik pada koordinat [x, y]
• type - Ketik string teks
• key - Tekan tombol atau kombinasi tombol (misalnya, “ctrl+s”)
• mouse_move - Gerakkan kursor ke koordinat

Tindakan yang ditingkatkan (computer_20250124) Tersedia di Claude 4 dan Claude Sonnet 3.7:

• scroll - Scroll ke arah mana pun dengan kontrol jumlah
• left_click_drag - Klik dan seret antara koordinat
• right_click, middle_click - Tombol mouse tambahan
• double_click, triple_click - Klik ganda
• left_mouse_down, left_mouse_up - Kontrol klik yang halus
• hold_key - Tahan tombol sambil melakukan tindakan lain
• wait - Jeda antara tindakan

​

Parameter tool

​

Aktifkan kemampuan thinking di Claude 4 dan Claude Sonnet 3.7

Claude Sonnet 3.7 memperkenalkan kemampuan “thinking” baru yang memungkinkan Anda melihat proses penalaran model saat bekerja melalui tugas kompleks. Fitur ini membantu Anda memahami bagaimana Claude mendekati masalah dan dapat sangat berharga untuk debugging atau tujuan pendidikan.

Untuk mengaktifkan thinking, tambahkan parameter thinking ke permintaan API Anda:

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

Parameter budget_tokens menentukan berapa banyak token yang dapat digunakan Claude untuk thinking. Ini dikurangi dari anggaran max_tokens keseluruhan Anda.

Ketika thinking diaktifkan, Claude akan mengembalikan proses penalarannya sebagai bagian dari respons, yang dapat membantu Anda:

1. Memahami proses pengambilan keputusan model
2. Mengidentifikasi masalah atau kesalahpahaman potensial
3. Belajar dari pendekatan Claude terhadap pemecahan masalah
4. Mendapatkan lebih banyak visibilitas ke dalam operasi multi-langkah yang kompleks

Berikut contoh seperti apa output thinking mungkin terlihat:

[Thinking]
Saya perlu menyimpan gambar kucing ke desktop. Mari saya bagi ini menjadi langkah-langkah:

1. Pertama, saya akan mengambil screenshot untuk melihat apa yang ada di desktop
2. Kemudian saya akan mencari browser web untuk mencari gambar kucing
3. Setelah menemukan gambar yang cocok, saya perlu menyimpannya ke desktop

Mari saya mulai dengan mengambil screenshot untuk melihat apa yang tersedia...

​

Menambah penggunaan komputer dengan tool lain

Tool penggunaan komputer dapat dikombinasikan dengan tool lain untuk membuat alur kerja otomasi yang lebih kuat. Ini sangat berguna ketika Anda perlu:

• Mengeksekusi perintah sistem (tool bash)
• Mengedit file konfigurasi atau skrip (tool text editor)
• Mengintegrasikan dengan API atau layanan kustom (tool kustom)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-01-24" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Dapatkan cuaca saat ini di lokasi tertentu",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Kota dan negara bagian, misalnya San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Unit suhu, baik 'celsius' atau 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Cari penerbangan dari San Francisco ke tempat dengan cuaca yang lebih hangat."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Bangun lingkungan penggunaan komputer kustom

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

• Lingkungan yang divirtualisasi atau dikontainerisasi yang cocok untuk penggunaan komputer dengan Claude
• Implementasi setidaknya satu dari tool penggunaan komputer yang didefinisikan Anthropic
• Loop agen yang berinteraksi dengan API Anthropic dan mengeksekusi hasil tool_use menggunakan implementasi tool Anda
• API atau UI yang memungkinkan input pengguna untuk memulai loop agen

​

Implementasikan tool penggunaan komputer

Tool penggunaan komputer diimplementasikan sebagai tool tanpa skema. Ketika menggunakan tool ini, Anda tidak perlu menyediakan skema input seperti dengan tool lain; skema dibangun ke dalam model Claude dan tidak dapat dimodifikasi.

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... tangani tindakan lain

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # Kembalikan hasil ke Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

while True:
    response = client.beta.messages.create(...)
    
    # Periksa apakah Claude menggunakan tool apa pun
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # Tidak ada lagi penggunaan tool, tugas selesai
        break
        
    # Lanjutkan percakapan dengan hasil tool
    messages.append({"role": "user", "content": tool_results})

​

Tangani error

Ketika mengimplementasikan tool penggunaan komputer, berbagai error dapat terjadi. Berikut cara menanganinya:

​

Ikuti praktik terbaik implementasi

​

Memahami keterbatasan penggunaan komputer

Fungsionalitas penggunaan komputer dalam beta. Meskipun kemampuan Claude canggih, pengembang harus menyadari keterbatasannya:

1. Latensi: latensi penggunaan komputer saat ini untuk interaksi manusia-AI mungkin terlalu lambat dibandingkan dengan tindakan komputer yang diarahkan manusia biasa. Kami merekomendasikan untuk fokus pada kasus penggunaan di mana kecepatan tidak kritis (misalnya, pengumpulan informasi latar belakang, pengujian perangkat lunak otomatis) di lingkungan terpercaya.
2. Akurasi dan keandalan computer vision: Claude dapat membuat kesalahan atau berhalusinasi ketika mengeluarkan koordinat spesifik sambil menghasilkan tindakan. Claude Sonnet 3.7 memperkenalkan kemampuan thinking yang dapat membantu Anda memahami penalaran model dan mengidentifikasi masalah potensial.
3. Akurasi dan keandalan pemilihan tool: Claude dapat membuat kesalahan atau berhalusinasi ketika memilih tool sambil menghasilkan tindakan atau mengambil tindakan tak terduga untuk memecahkan masalah. Selain itu, keandalan mungkin lebih rendah ketika berinteraksi dengan aplikasi khusus atau beberapa aplikasi sekaligus. Kami merekomendasikan agar pengguna meminta model dengan hati-hati ketika meminta tugas kompleks.
4. Keandalan scrolling: Meskipun Claude Sonnet 3.5 (baru) memiliki keterbatasan dengan scrolling, Claude Sonnet 3.7 memperkenalkan tindakan scroll khusus dengan kontrol arah yang meningkatkan keandalan. Model sekarang dapat secara eksplisit scroll ke arah mana pun (atas/bawah/kiri/kanan) dengan jumlah yang ditentukan.
5. Interaksi spreadsheet: Klik mouse untuk interaksi spreadsheet telah meningkat di Claude Sonnet 3.7 dengan penambahan tindakan kontrol mouse yang lebih presisi seperti left_mouse_down, left_mouse_up, dan dukungan tombol modifier baru. Pemilihan sel dapat lebih andal dengan menggunakan kontrol halus ini dan menggabungkan tombol modifier dengan klik.
6. Pembuatan akun dan pembuatan konten di platform sosial dan komunikasi: Meskipun Claude akan mengunjungi situs web, kami membatasi kemampuannya untuk membuat akun atau menghasilkan dan berbagi konten atau terlibat dalam peniruan manusia di situs web media sosial dan platform. Kami mungkin memperbarui kemampuan ini di masa depan.
7. Kerentanan: Kerentanan seperti jailbreaking atau injeksi prompt dapat bertahan di sistem AI frontier, termasuk API penggunaan komputer beta. Dalam beberapa keadaan, Claude akan mengikuti perintah yang ditemukan dalam konten, terkadang bahkan bertentangan dengan instruksi pengguna. Misalnya, instruksi Claude di halaman web atau yang terkandung dalam gambar dapat menggantikan instruksi atau menyebabkan Claude membuat kesalahan. Kami merekomendasikan: a. Membatasi penggunaan komputer ke lingkungan terpercaya seperti mesin virtual atau kontainer dengan hak istimewa minimal b. Menghindari memberikan akses penggunaan komputer ke akun atau data sensitif tanpa pengawasan ketat c. Menginformasikan pengguna akhir tentang risiko yang relevan dan mendapatkan persetujuan mereka sebelum mengaktifkan atau meminta izin yang diperlukan untuk fitur penggunaan komputer dalam aplikasi Anda
8. Tindakan yang tidak pantas atau ilegal: Sesuai persyaratan layanan Anthropic, Anda tidak boleh menggunakan penggunaan komputer untuk melanggar hukum apa pun atau Kebijakan Penggunaan yang Dapat Diterima kami.

Selalu tinjau dan verifikasi tindakan dan log penggunaan komputer Claude dengan hati-hati. Jangan gunakan Claude untuk tugas yang memerlukan presisi sempurna atau informasi pengguna sensitif tanpa pengawasan manusia.

​

Harga

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Additional token consumption:

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

​

Langkah selanjutnya