Alat penggunaan komputer

​

Ikhtisar

• Tangkapan layar: 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

​

Kompatibilitas model

​

Pertimbangan keamanan

​

Mulai cepat

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # 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

​

Lingkungan komputasi

1. Tampilan virtual: Server tampilan X11 virtual (menggunakan Xvfb) yang merender antarmuka desktop yang akan Claude lihat melalui tangkapan layar dan kontrol dengan tindakan mouse/keyboard.
2. Lingkungan desktop: UI ringan dengan pengelola 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 pengelola file yang dapat Claude gunakan untuk menyelesaikan tugas.
4. Implementasi alat: Kode integrasi yang menerjemahkan permintaan alat abstrak Claude (seperti “pindahkan mouse” atau “ambil tangkapan layar”) 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 (tangkapan layar, keluaran perintah) kembali ke Claude.

1. Menerima permintaan penggunaan alat Claude
2. Menerjemahkannya menjadi tindakan di lingkungan komputasi Anda
3. Menangkap hasil (tangkapan layar, keluaran perintah, dll.)
4. Mengembalikan hasil ini ke Claude

​

Cara mengimplementasikan penggunaan komputer

​

Mulai dengan implementasi referensi kami

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

​

Memahami loop multi-agen

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 alat
    3. Aplikasi Anda menjalankan 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 pemikiran 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 alat apa pun
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # Dalam aplikasi nyata, Anda akan menjalankan 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})

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

​

Optimalkan kinerja model dengan prompting

1. Tentukan tugas sederhana dan 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 tangkapan layar dan hati-hati evaluasi 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 mengkonfirmasi langkah telah dijalankan 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 tangkapan layar contoh dan panggilan alat 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 buruk karena injeksi prompt. Silakan tinjau panduan kami tentang mitigasi injeksi prompt sebelum memberikan model kredensial login.

​

Prompt sistem

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.

​

Tindakan yang tersedia

• 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

• 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

// Ambil tangkapan layar
{
  "action": "screenshot"
}

// Klik pada posisi
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// Ketik teks
{
  "action": "type",
  "text": "Halo, dunia!"
}

// Gulir ke bawah (Claude 4/3.7)
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

​

Parameter alat

​

Aktifkan kemampuan pemikiran di model Claude 4 dan Claude Sonnet 3.7

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

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

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

1. Pertama, saya akan mengambil tangkapan layar 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 tangkapan layar untuk melihat apa yang tersedia...

​

Augmentasi penggunaan komputer dengan alat lain

• Menjalankan perintah sistem (alat bash)
• Mengedit file konfigurasi atau skrip (alat editor teks)
• Mengintegrasikan dengan API kustom atau layanan (alat 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-sonnet-4-5",
    "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": "Satuan suhu, baik 'celsius' atau 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Temukan penerbangan dari San Francisco ke tempat dengan cuaca lebih hangat."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

Bangun lingkungan penggunaan komputer kustom

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

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 alat apa pun
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # Tidak ada penggunaan alat lagi, tugas selesai
        break
        
    # Lanjutkan percakapan dengan hasil alat
    messages.append({"role": "user", "content": tool_results})

​

Tangani kesalahan

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Kesalahan: Gagal menangkap layar. Tampilan mungkin terkunci atau tidak tersedia.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Kesalahan: Koordinat (1200, 900) berada di luar batas tampilan (1024x768).",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Kesalahan: Gagal melakukan tindakan klik. Aplikasi mungkin tidak responsif.",
      "is_error": true
    }
  ]
}

​

Ikuti praktik terbaik implementasi

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Biarkan UI diperbarui

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Koordinat di luar batas"
    return True, None

import logging

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

​

Pahami keterbatasan penggunaan komputer

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 dapat membuat kesalahan atau berhalusinasi saat mengeluarkan koordinat spesifik sambil menghasilkan tindakan. Claude Sonnet 3.7 memperkenalkan kemampuan pemikiran yang dapat membantu Anda memahami penalaran model dan mengidentifikasi potensi masalah.
3. Akurasi dan keandalan pemilihan alat: Claude dapat 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 memberi prompt 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 terperinci 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, kami membatasi kemampuannya untuk membuat akun atau membuat dan berbagi konten atau sebaliknya terlibat dalam peniruan manusia di seluruh situs web dan platform media sosial. Kami dapat memperbarui kemampuan ini di masa depan.
7. Kerentanan: Kerentanan seperti jailbreaking atau injeksi prompt dapat bertahan 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 dapat mengganti 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 pemberian akses penggunaan komputer ke akun sensitif atau data tanpa pengawasan ketat c. Menginformasikan pengguna akhir tentang risiko yang relevan dan memperoleh 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 Kami yang Dapat Diterima.

​

Harga

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

​

Langkah berikutnya