Alat computer use

Claude dapat berinteraksi dengan lingkungan desktop melalui alat computer use, yang menyediakan kemampuan screenshot dan kontrol mouse/keyboard untuk interaksi desktop otonom. Di WebArena, sebuah benchmark untuk navigasi web otonom di seluruh situs web nyata, Claude mencapai hasil terdepan di antara sistem single-agent, menunjukkan kemampuan kuat untuk menyelesaikan tugas browser multi-langkah dari awal hingga akhir.

Ikhtisar

Computer use adalah fitur beta yang memungkinkan Claude berinteraksi dengan lingkungan desktop. Alat ini menyediakan:

• Penangkapan screenshot: Lihat apa yang saat ini ditampilkan di layar
• Kontrol mouse: Klik, seret, dan pindahkan kursor
• Input keyboard: Ketik teks dan gunakan pintasan keyboard
• Otomasi desktop: Berinteraksi dengan aplikasi atau antarmuka apa pun

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

Untuk dukungan model, lihat Referensi alat.

Pertimbangan keamanan

Computer use adalah fitur beta dengan risiko unik yang berbeda dari fitur API standar. Risiko ini meningkat ketika berinteraksi dengan internet.

Dalam beberapa keadaan, Claude akan mengikuti perintah yang ditemukan dalam konten bahkan jika bertentangan dengan instruksi pengguna. Misalnya, instruksi Claude di halaman web atau yang terdapat dalam gambar dapat mengganti instruksi atau menyebabkan Claude membuat kesalahan. Ambil tindakan pencegahan untuk mengisolasi Claude dari data dan tindakan sensitif untuk menghindari risiko terkait injeksi prompt.

Model telah dilatih untuk menahan injeksi prompt ini, dan lapisan pertahanan tambahan telah ditambahkan. Jika Anda menggunakan alat computer use, pengklasifikasi akan secara otomatis berjalan pada prompt Anda untuk menandai kemungkinan contoh injeksi prompt. Ketika pengklasifikasi ini mengidentifikasi kemungkinan injeksi prompt dalam screenshot, 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.

Beri tahu pengguna akhir tentang risiko yang relevan dan dapatkan persetujuan mereka sebelum mengaktifkan computer use di produk Anda sendiri.

Mulai cepat

Berikut cara memulai dengan computer use:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",  # or another compatible model
    max_tokens=1024,
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
            "display_number": 1,
        },
        {"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."}],
    betas=["computer-use-2025-11-24"],
)
print(response)

Cara kerja computer use

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

Lingkungan komputasi

Computer use memerlukan lingkungan komputasi bersandal di mana Claude dapat dengan aman berinteraksi 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 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 Claude berinteraksi.

3. Aplikasi: Aplikasi Linux yang sudah diinstal sebelumnya 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 "pindahkan mouse" atau "ambil screenshot") menjadi operasi aktual di lingkungan virtual.

5. Agent loop: 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 computer use, 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 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 computer use

Mulai dengan implementasi referensi

Implementasi referensi tersedia yang mencakup semua yang Anda butuhkan untuk memulai dengan cepat dengan computer use:

• Lingkungan terkontainerisasi yang cocok untuk computer use dengan Claude
• Implementasi alat computer use
• Agent loop yang berinteraksi dengan Claude API dan menjalankan alat computer use
• Antarmuka web untuk berinteraksi dengan kontainer, agent loop, dan alat.

Memahami agentic loop

Inti dari computer use adalah "agent loop" - siklus di mana Claude meminta tindakan alat, aplikasi Anda menjalankannya, dan mengembalikan hasil ke Claude. Berikut adalah 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"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # 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": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "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 sampai Claude merespons tanpa meminta alat apa pun (penyelesaian tugas) atau batas iterasi maksimum tercapai. Perlindungan ini mencegah kemungkinan loop tak terbatas yang dapat menghasilkan biaya API yang tidak terduga.

Coba implementasi referensi sebelum membaca sisa dokumentasi ini.

Optimalkan kinerja model dengan prompting

Berikut adalah beberapa tips tentang cara mendapatkan output berkualitas terbaik:

1. Tentukan tugas sederhana yang terdefinisi dengan baik dan berikan instruksi eksplisit untuk setiap langkah.
2. Claude kadang-kadang mengasumsikan hasil tindakannya tanpa secara eksplisit memeriksa hasilnya. Untuk mencegah ini, Anda dapat memberi prompt 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 untuk Claude manipulasi menggunakan gerakan mouse. Jika Anda mengalami ini, coba beri prompt model untuk menggunakan pintasan keyboard.
4. Untuk tugas yang dapat diulang atau interaksi UI, sertakan contoh screenshot dan panggilan alat hasil yang berhasil dalam prompt Anda.
5. Jika Anda perlu model untuk login, berikan nama pengguna dan kata sandi dalam prompt Anda di dalam tag xml seperti <robot_credentials>. Menggunakan computer use dalam aplikasi yang memerlukan login meningkatkan risiko hasil buruk sebagai akibat dari injeksi prompt. Tinjau panduan tentang mitigasi injeksi prompt sebelum memberikan model kredensial login.

System prompts

Ketika salah satu alat skema Anthropic diminta melalui Claude API, system prompt khusus computer use dihasilkan. Ini mirip dengan tool use system prompt 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 dengan tool use reguler, field system_prompt yang disediakan pengguna tetap dihormati dan digunakan dalam konstruksi system prompt gabungan.

Tindakan yang tersedia

Alat computer use mendukung tindakan-tindakan ini:

Tindakan dasar (semua versi)

• screenshot - Tangkap tampilan saat ini
• left_click - Klik pada koordinat [x, y]
• type - Ketik string teks
• key - Tekan tombol atau kombinasi tombol (misalnya, "ctrl+s")
• mouse_move - Pindahkan 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 terperinci
• hold_key - Tahan tombol untuk durasi tertentu (dalam detik)
• wait - Jeda antara tindakan

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

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

Parameter alat

Menggabungkan dengan extended thinking

Untuk menggabungkan computer use dengan extended thinking, lihat Extended thinking.

Menambah computer use dengan alat lain

Untuk menambahkan alat lain bersama computer use, sertakan mereka dalam array tools yang sama. Mulai cepat di atas menunjukkan pola ini dengan alat bash dan alat editor teks. Anda dapat menambahkan definisi alat kustom Anda sendiri dengan cara yang sama.

Bangun lingkungan penggunaan komputer khusus

Implementasi referensi dirancang untuk membantu Anda memulai dengan 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 terkontainerisasi yang sesuai untuk penggunaan komputer dengan Claude
• Implementasi setidaknya satu dari alat penggunaan komputer skema Anthropic
• 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 memberikan skema input seperti alat lainnya; skema dibangun ke dalam model Claude dan tidak dapat dimodifikasi.

Tangani kesalahan

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

Tangani penskalaan koordinat untuk resolusi lebih tinggi

API membatasi gambar hingga maksimal 1568 piksel di tepi terpanjang dan sekitar 1,15 megapiksel total (lihat pengubahan ukuran gambar untuk detail). Misalnya, layar 1512x982 dikecilkan menjadi sekitar 1330x864. Claude menganalisis gambar yang lebih kecil ini dan mengembalikan koordinat dalam ruang itu, tetapi alat Anda menjalankan klik dalam ruang layar asli.

Ini dapat menyebabkan koordinat klik Claude melewatkan target mereka kecuali Anda menangani transformasi koordinat.

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

import math


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)


# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

Ikuti praktik terbaik implementasi

Pahami keterbatasan penggunaan komputer

Fungsionalitas penggunaan komputer masih dalam beta. Meskipun kemampuan Claude terdepan, 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. Fokus pada kasus penggunaan di mana kecepatan tidak penting (misalnya, pengumpulan informasi latar belakang, pengujian perangkat lunak otomatis) di lingkungan terpercaya.
2. Akurasi dan keandalan visi komputer: Claude mungkin membuat kesalahan atau berhalusinasi saat menampilkan koordinat spesifik sambil menghasilkan tindakan. Claude Sonnet 3.7 memperkenalkan kemampuan pemikiran yang dapat membantu Anda memahami penalaran model dan mengidentifikasi masalah potensial.
3. Akurasi dan keandalan pemilihan alat: Claude mungkin membuat kesalahan atau berhalusinasi saat memilih alat sambil menghasilkan tindakan atau mengambil tindakan yang tidak terduga untuk menyelesaikan masalah. Selain itu, keandalan mungkin lebih rendah saat berinteraksi dengan aplikasi niche atau beberapa aplikasi sekaligus. Minta model dengan hati-hati saat meminta tugas kompleks.
4. Keandalan pengguliran: Claude Sonnet 3.7 memperkenalkan tindakan pengguliran khusus dengan kontrol arah yang meningkatkan keandalan. Model sekarang dapat secara eksplisit menggulir ke arah mana pun (atas/bawah/kiri/kanan) dengan jumlah yang ditentukan.
5. Interaksi spreadsheet: Klik mouse untuk interaksi spreadsheet telah ditingkatkan di Claude Sonnet 3.7 dengan penambahan tindakan kontrol mouse yang lebih presisi seperti left_mouse_down, left_mouse_up, dan dukungan tombol pengubah baru. Pemilihan sel dapat lebih andal dengan menggunakan kontrol butir halus ini dan menggabungkan tombol pengubah dengan klik.
6. Pembuatan akun dan pembuatan konten di platform media sosial dan komunikasi: Meskipun Claude akan mengunjungi situs web, kemampuan Claude untuk membuat akun atau menghasilkan dan berbagi konten atau sebaliknya terlibat dalam penyamaran manusia di seluruh situs web dan platform media sosial terbatas. Kemampuan ini mungkin diperbarui di masa depan.
7. Kerentanan: Kerentanan seperti jailbreaking atau injeksi prompt mungkin tetap ada di seluruh sistem AI frontier, termasuk API penggunaan komputer beta. Dalam beberapa keadaan, Claude akan mengikuti perintah yang ditemukan dalam konten, kadang-kadang bahkan bertentangan dengan instruksi pengguna. Misalnya, instruksi Claude di halaman web atau yang terdapat dalam gambar mungkin menggantikan instruksi atau menyebabkan Claude membuat kesalahan. Pertimbangkan hal berikut: a. Membatasi penggunaan komputer ke lingkungan terpercaya seperti mesin virtual atau kontainer dengan hak istimewa minimal b. Menghindari pemberian akses penggunaan komputer ke akun sensitif atau data 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 di aplikasi Anda
8. Tindakan yang tidak pantas atau ilegal: Sesuai dengan syarat layanan Anthropic, Anda tidak boleh menggunakan penggunaan komputer untuk melanggar hukum apa pun atau Kebijakan Penggunaan yang Dapat Diterima.

Selalu tinjau dan verifikasi dengan hati-hati tindakan penggunaan komputer Claude dan log. 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, tindakan 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 tindakan 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 berikutnya