Alat penggunaan komputer

Claude dapat berinteraksi dengan lingkungan komputer melalui alat penggunaan komputer, yang menyediakan kemampuan tangkapan layar dan kontrol mouse/keyboard untuk interaksi desktop otonom. Di WebArena, sebuah tolok ukur untuk navigasi web otonom di berbagai situs web nyata, Claude mencapai hasil terdepan di antara sistem agen tunggal, menunjukkan kemampuan yang kuat untuk menyelesaikan tugas browser multi-langkah dari awal hingga akhir.

Ikhtisar

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

• Pengambilan tangkapan layar: Melihat apa yang sedang ditampilkan di layar
• Kontrol mouse: Klik, seret, dan gerakkan kursor
• Input keyboard: Mengetik teks dan menggunakan pintasan keyboard
• Otomasi desktop: Berinteraksi dengan aplikasi atau antarmuka apa pun

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

Kompatibilitas model

Penggunaan komputer tersedia untuk model Claude berikut:

Pertimbangan keamanan

Penggunaan komputer adalah fitur beta dengan 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 pengguna. Misalnya, instruksi Claude di halaman web atau yang terdapat dalam gambar dapat mengesampingkan instruksi atau menyebabkan Claude membuat kesalahan. Ambil tindakan pencegahan untuk mengisolasi Claude dari data dan tindakan sensitif guna menghindari risiko terkait injeksi prompt.

Model telah dilatih untuk menolak injeksi prompt ini, dan lapisan pertahanan tambahan telah ditambahkan. Jika Anda menggunakan alat penggunaan komputer, pengklasifikasi akan secara otomatis berjalan pada prompt Anda untuk menandai potensi contoh injeksi prompt. Ketika pengklasifikasi ini mengidentifikasi potensi injeksi prompt dalam tangkapan layar, mereka akan secara otomatis mengarahkan model untuk meminta konfirmasi pengguna sebelum melanjutkan dengan tindakan berikutnya. Perlindungan tambahan ini tidak akan ideal untuk setiap kasus penggunaan (misalnya, kasus penggunaan tanpa manusia dalam loop), jadi jika Anda ingin memilih keluar dan mematikannya, silakan hubungi dukungan.

Tindakan pencegahan ini tetap penting bahkan dengan lapisan pertahanan pengklasifikasi yang ada.

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

Mulai cepat

Berikut cara memulai dengan penggunaan komputer:

Cara kerja penggunaan komputer

Pengulangan langkah 3 dan 4 tanpa input pengguna disebut sebagai "loop agen" (yaitu, Claude merespons dengan permintaan penggunaan alat 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. Tampilan virtual: Server tampilan X11 virtual (menggunakan Xvfb) yang merender antarmuka desktop yang akan dilihat Claude melalui tangkapan layar dan dikontrol dengan tindakan mouse/keyboard.

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

3. Aplikasi: Aplikasi Linux yang sudah terinstal seperti Firefox, LibreOffice, editor teks, dan manajer 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 Claude
2. Menerjemahkannya menjadi tindakan di lingkungan komputasi Anda
3. Menangkap hasilnya (tangkapan layar, 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

Implementasi referensi tersedia yang mencakup semua yang Anda butuhkan untuk memulai dengan cepat menggunakan penggunaan komputer:

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

Memahami loop multi-agen

Inti dari penggunaan komputer adalah "loop agen" - siklus di mana Claude meminta tindakan alat, aplikasi Anda mengeksekusinya, dan mengembalikan hasilnya 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,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # Configure tools - you should already have these initialized elsewhere
    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"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

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

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

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

Coba 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 serta 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 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 bagi Claude untuk dimanipulasi 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 tangkapan layar dan panggilan alat dari hasil yang berhasil dalam prompt Anda.
5. Jika Anda perlu model untuk masuk, 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 yang buruk akibat injeksi prompt. Tinjau panduan tentang mitigasi injeksi prompt sebelum memberikan kredensial login kepada model.

System prompt

Ketika salah satu alat yang didefinisikan oleh Anthropic diminta melalui API Claude, system prompt khusus penggunaan komputer dibuat. Ini mirip dengan system prompt 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 halnya penggunaan alat biasa, bidang system_prompt yang disediakan pengguna tetap dihormati dan digunakan dalam konstruksi system prompt gabungan.

Tindakan yang tersedia

Alat penggunaan komputer mendukung tindakan-tindakan berikut:

Tindakan dasar (semua versi)

• screenshot - Mengambil tampilan saat ini
• left_click - Klik pada koordinat [x, y]
• type - Mengetik string teks
• key - Menekan tombol atau kombinasi tombol (misalnya, "ctrl+s")
• mouse_move - Memindahkan kursor ke koordinat

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

• scroll - Gulir 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 - Beberapa klik
• left_mouse_down, left_mouse_up - Kontrol klik yang lebih halus
• hold_key - Tahan tombol selama durasi tertentu (dalam detik)
• wait - Jeda antara tindakan

Tindakan yang ditingkatkan (computer_20251124) Tersedia di Claude Opus 4.6 dan Claude Opus 4.5:

• Semua tindakan dari computer_20250124
• zoom - Melihat wilayah layar tertentu pada resolusi penuh. Memerlukan enable_zoom: true dalam definisi alat. Mengambil parameter region dengan koordinat [x1, y1, x2, y2] yang mendefinisikan sudut kiri atas dan kanan bawah area yang akan diperiksa.

Parameter alat

Aktifkan kemampuan berpikir di model Claude 4 dan Claude Sonnet 3.7

Claude Sonnet 3.7 memperkenalkan kemampuan "berpikir" baru yang memungkinkan Anda melihat proses penalaran model saat mengerjakan tugas-tugas kompleks. Fitur ini membantu Anda memahami bagaimana Claude mendekati suatu masalah dan dapat sangat berharga untuk tujuan debugging atau pendidikan.

Untuk mengaktifkan berpikir, 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 berpikir. Ini dikurangi dari anggaran max_tokens keseluruhan Anda.

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

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

Berikut contoh tampilan output berpikir:

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

Menggabungkan penggunaan komputer dengan alat lain

Alat penggunaan komputer dapat dikombinasikan dengan alat lain untuk membuat alur kerja otomatisasi yang lebih canggih. Ini sangat berguna ketika Anda perlu:

• Menjalankan perintah sistem (alat bash)
• Mengedit file konfigurasi atau skrip (alat editor teks)
• Mengintegrasikan dengan API atau layanan kustom (alat kustom)

Membangun lingkungan penggunaan komputer kustom

Implementasi referensi dimaksudkan untuk membantu Anda memulai penggunaan komputer. 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 virtual atau terkontainer yang sesuai untuk penggunaan komputer dengan Claude
• Implementasi setidaknya satu alat penggunaan komputer yang didefinisikan oleh Anthropic
• Loop agen yang berinteraksi dengan API Claude dan menjalankan hasil tool_use menggunakan implementasi alat Anda
• API atau UI yang memungkinkan input pengguna untuk memulai loop agen

Mengimplementasikan alat penggunaan komputer

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

Menangani kesalahan

Saat mengimplementasikan alat penggunaan komputer, berbagai kesalahan mungkin terjadi. Berikut cara menanganinya:

Menangani penskalaan koordinat untuk resolusi lebih tinggi

API membatasi gambar hingga maksimum 1568 piksel pada sisi terpanjang dan sekitar 1,15 megapiksel total (lihat pengubahan ukuran gambar untuk detailnya). Misalnya, layar 1512x982 disampling turun menjadi sekitar 1330x864. Claude menganalisis gambar yang lebih kecil ini dan mengembalikan koordinat dalam ruang tersebut, tetapi alat Anda menjalankan klik di ruang layar asli.

Hal ini dapat menyebabkan koordinat klik Claude meleset dari targetnya kecuali Anda menangani transformasi koordinat.

Untuk memperbaikinya, ubah ukuran tangkapan layar sendiri dan skalakan kembali koordinat Claude:

Ikuti praktik terbaik implementasi

Memahami keterbatasan penggunaan komputer

Fungsionalitas penggunaan komputer masih dalam tahap beta. Meskipun kemampuan Claude mutakhir, 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 secara langsung. Fokus pada kasus penggunaan di mana kecepatan tidak kritis (misalnya, pengumpulan informasi latar belakang, pengujian perangkat lunak otomatis) di lingkungan tepercaya.
2. Akurasi dan keandalan visi komputer: Claude mungkin membuat kesalahan atau berhalusinasi saat mengeluarkan koordinat spesifik saat menghasilkan aksi. Claude Sonnet 3.7 memperkenalkan kemampuan berpikir yang dapat membantu Anda memahami penalaran model dan mengidentifikasi potensi masalah.
3. Akurasi dan keandalan pemilihan alat: Claude mungkin membuat kesalahan atau berhalusinasi saat memilih alat saat menghasilkan aksi atau mengambil tindakan tak terduga untuk memecahkan masalah. Selain itu, keandalan mungkin lebih rendah saat berinteraksi dengan aplikasi khusus atau beberapa aplikasi sekaligus. Beri prompt model dengan hati-hati saat meminta tugas kompleks.
4. Keandalan pengguliran: Claude Sonnet 3.7 memperkenalkan aksi gulir khusus dengan kontrol arah yang meningkatkan keandalan. Model sekarang dapat secara eksplisit menggulir ke arah mana pun (atas/bawah/kiri/kanan) sebesar jumlah yang ditentukan.
5. Interaksi spreadsheet: Klik mouse untuk interaksi spreadsheet telah ditingkatkan di Claude Sonnet 3.7 dengan penambahan aksi 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 berbutir halus ini dan menggabungkan tombol modifier dengan klik.

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

Retensi data

Penggunaan komputer 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 tetapi tidak menyimpannya setelah respons dikembalikan.

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

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