Alat computer use

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

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 mengontrol lingkungan desktop.

Kompatibilitas model

Computer use tersedia untuk model Claude berikut:

Pertimbangan keamanan

Mulai cepat

Berikut cara memulai dengan computer use:

Cara kerja computer use

Kami menyebut pengulangan langkah 3 dan 4 tanpa input pengguna 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 Claude lihat melalui screenshot dan kontrol 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 untuk Claude berinteraksi.

3. Aplikasi: Aplikasi Linux yang telah diinstal sebelumnya seperti Firefox, LibreOffice, editor teks, dan manajer file yang dapat Claude gunakan 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 kami

Kami telah membangun implementasi referensi 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 mengeksekusi alat computer use
• Antarmuka web untuk berinteraksi dengan kontainer, agent loop, dan alat.

Memahami multi-agent loop

Inti dari computer use adalah "agent loop" - siklus di mana Claude meminta tindakan alat, aplikasi Anda mengeksekusinya, 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,  # Tambahkan batas iterasi untuk mencegah loop tak terbatas
):
    """
    Loop agen sederhana untuk interaksi computer use Claude.

    Fungsi ini menangani bolak-balik antara:
    1. Mengirim pesan pengguna ke Claude
    2. Claude meminta untuk menggunakan alat
    3. Aplikasi Anda mengeksekusi alat tersebut
    4. Mengirim hasil alat kembali ke Claude
    """
    # Atur alat 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 alat - Anda seharusnya 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 melonjak)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Atur parameter thinking opsional (untuk Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Panggil Claude API
        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 alat apa pun
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # Dalam aplikasi nyata, Anda akan mengeksekusi alat di sini
                # Misalnya: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

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

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

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

Loop berlanjut hingga Claude merespons tanpa meminta alat apa pun (penyelesaian tugas) atau batas iterasi maksimal tercapai. Perlindungan ini mencegah loop tak terbatas potensial yang dapat menghasilkan biaya API yang tidak terduga.

Kami merekomendasikan untuk mencoba implementasi referensi terlebih dahulu 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 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 bagi Claude untuk dimanipulasi 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 karena injeksi prompt. Silakan tinjau panduan kami tentang mitigasi injeksi prompt sebelum memberikan model kredensial login.

System prompts

Ketika salah satu alat yang ditentukan Anthropic diminta melalui Claude API, system prompt khusus computer use dihasilkan. Ini mirip dengan tool use system prompt tetapi dimulai dengan:

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

Seperti dengan tool use reguler, bidang system_prompt yang disediakan pengguna masih dihormati dan digunakan dalam konstruksi system prompt gabungan.

Tindakan yang tersedia

Alat computer use mendukung tindakan berikut:

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 sambil melakukan tindakan lain
• wait - Jeda antara tindakan

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

• Semua tindakan dari computer_20250124
• zoom - Lihat wilayah layar tertentu dengan 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

Aktifkan kemampuan thinking di model Claude 4 dan Claude Sonnet 3.7

Claude Sonnet 3.7 memperkenalkan kemampuan "thinking" baru yang memungkinkan Anda melihat proses penalaran model saat menyelesaikan 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 Claude gunakan untuk thinking. Ini dikurangkan 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 potensial atau kesalahpahaman
3. Belajar dari pendekatan Claude terhadap pemecahan masalah
4. Dapatkan lebih banyak visibilitas ke dalam operasi multi-langkah yang kompleks

Berikut adalah contoh dari apa yang mungkin terlihat seperti output thinking:

[Thinking]
Saya perlu menyimpan gambar kucing ke desktop. Mari saya uraikan 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...

Augmentasi computer use dengan alat lain

Alat computer use dapat dikombinasikan dengan alat lain untuk membuat alur kerja otomasi yang lebih kuat. Ini sangat berguna ketika Anda perlu:

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

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 cocok untuk penggunaan komputer dengan Claude
• Implementasi setidaknya satu dari alat penggunaan komputer yang ditentukan 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

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 yang lebih tinggi

API membatasi gambar hingga maksimal 1568 piksel pada tepi terpanjang dan sekitar 1,15 megapiksel total (lihat pengubahan ukuran gambar untuk detail). Misalnya, layar 1512x982 dikurangi sampel 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:

Ikuti praktik terbaik implementasi

Pahami keterbatasan penggunaan komputer

Fungsionalitas penggunaan komputer masih dalam versi 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. Kami merekomendasikan 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 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. Kami merekomendasikan agar pengguna dengan hati-hati memberi prompt pada model saat meminta tugas yang 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.

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