Alat eksekusi kode

Claude dapat menganalisis data, membuat visualisasi, melakukan perhitungan kompleks, menjalankan perintah sistem, membuat dan mengedit file, serta memproses file yang diunggah secara langsung dalam percakapan API. Alat eksekusi kode memungkinkan Claude menjalankan perintah Bash dan memanipulasi file, termasuk menulis kode, dalam lingkungan sandbox yang aman.

Eksekusi kode gratis ketika digunakan bersama web search atau web fetch. Ketika web_search_20260209 atau web_fetch_20260209 disertakan dalam permintaan Anda, tidak ada biaya tambahan untuk pemanggilan alat eksekusi kode di luar biaya token input dan output standar. Biaya eksekusi kode standar berlaku ketika alat-alat tersebut tidak disertakan.

Eksekusi kode adalah primitif inti untuk membangun agen berkinerja tinggi. Fitur ini memungkinkan pemfilteran dinamis pada alat web search dan web fetch, sehingga Claude dapat memproses hasil sebelum mencapai "context window" (jendela konteks), meningkatkan akurasi sekaligus mengurangi konsumsi token.



Kompatibilitas model

Alat eksekusi kode tersedia pada model-model berikut:



Ketersediaan platform

Eksekusi kode tersedia di:

• Claude API (Anthropic)
• Claude Platform on AWS
• Microsoft Foundry

Eksekusi kode saat ini tidak tersedia di Amazon Bedrock atau Vertex AI.



Mulai cepat

Berikut adalah contoh sederhana yang meminta Claude melakukan perhitungan:



Cara kerja eksekusi kode

Ketika Anda menambahkan alat eksekusi kode ke permintaan API Anda:

1. Claude mengevaluasi apakah eksekusi kode akan membantu menjawab pertanyaan Anda
2. Alat ini secara otomatis memberikan Claude kemampuan berikut:
   • Perintah Bash: Menjalankan perintah shell untuk operasi sistem dan manajemen paket
   • Operasi file: Membuat, melihat, dan mengedit file secara langsung, termasuk menulis kode
3. Claude dapat menggunakan kombinasi apa pun dari kemampuan ini dalam satu permintaan
4. Semua operasi berjalan dalam lingkungan sandbox yang aman
5. Claude memberikan hasil beserta grafik, perhitungan, atau analisis yang dihasilkan



Kapan Claude menjalankan kode

Claude menjalankan kode ketika permintaan mendapat manfaat dari komputasi atau penanganan file:

• Matematika non-trivial (angka besar, banyak langkah, hasil yang sensitif terhadap presisi)
• Analisis data, parsing file, atau visualisasi
• Eksekusi algoritma atau simulasi
• Permintaan eksplisit untuk "menjalankan", "menghitung", atau "mengeksekusi"

Claude menjawab langsung tanpa menjalankan kode untuk:

• Aritmetika sederhana dan fakta matematika yang sudah umum diketahui
• Permintaan faktual, percakapan, atau kreatif
• Konversi satuan atau terjemahan sederhana

Jika Anda ingin Claude menjalankan kode untuk permintaan yang berada di batas antara keduanya, minta secara eksplisit (misalnya, "jalankan kode untuk memverifikasi ini").



Menggunakan eksekusi kode dengan alat eksekusi lainnya

Ketika Anda menyediakan eksekusi kode bersama dengan alat yang disediakan klien yang juga menjalankan kode (seperti alat bash atau REPL kustom), Claude beroperasi dalam lingkungan multi-komputer. Alat eksekusi kode berjalan di kontainer sandbox milik Anthropic, sementara alat yang disediakan klien Anda berjalan di lingkungan terpisah yang Anda kendalikan. Claude terkadang dapat membingungkan lingkungan-lingkungan ini, mencoba menggunakan alat yang salah atau mengasumsikan state dibagikan di antara keduanya.

Untuk menghindari hal ini, tambahkan instruksi ke prompt sistem Anda yang memperjelas perbedaannya:

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

Hal ini sangat penting ketika menggabungkan eksekusi kode dengan web search atau web fetch, yang mengaktifkan eksekusi kode secara otomatis. Jika aplikasi Anda sudah menyediakan alat shell sisi klien, eksekusi kode otomatis menciptakan lingkungan eksekusi kedua yang perlu dibedakan oleh Claude.



Cara menggunakan alat ini



Unggah dan analisis file Anda sendiri

Untuk menganalisis file data Anda sendiri (seperti CSV, Excel, atau gambar), unggah file tersebut melalui Files API dan referensikan dalam permintaan Anda:

Lingkungan Python dapat memproses berbagai jenis file yang diunggah melalui Files API, termasuk:

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• Gambar (JPEG, PNG, GIF, WebP)
• File teks (.txt, .md, .py, dan lainnya)



Unggah dan analisis file

1. Unggah file Anda menggunakan Files API
2. Referensikan file dalam pesan Anda menggunakan blok konten container_upload
3. Sertakan alat eksekusi kode dalam permintaan API Anda



Mengambil file yang dihasilkan

Ketika Claude membuat file selama eksekusi kode, Anda dapat mengambil file-file ini menggunakan Files API:



Definisi alat

Alat eksekusi kode tidak memerlukan parameter tambahan:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Ketika alat ini disediakan, Claude secara otomatis mendapatkan akses ke dua sub-alat:

• bash_code_execution: Menjalankan perintah shell
• text_editor_code_execution: Melihat, membuat, dan mengedit file, termasuk menulis kode



Format respons

Alat eksekusi kode dapat mengembalikan dua jenis hasil tergantung pada operasinya:



Respons perintah Bash

{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": {
    "command": "ls -la | head -5"
  }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
    "stderr": "",
    "return_code": 0
  }
}



Respons operasi file

Melihat file:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "text_editor_code_execution",
  "input": {
    "command": "view",
    "path": "config.json"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 4
  }
}

Membuat file:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "text_editor_code_execution",
  "input": {
    "command": "create",
    "path": "new_file.txt",
    "file_text": "Hello, World!"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_result",
    "is_file_update": false
  }
}

Mengedit file (str_replace):

{
  "type": "server_tool_use",
  "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "name": "text_editor_code_execution",
  "input": {
    "command": "str_replace",
    "path": "config.json",
    "old_str": "\"debug\": true",
    "new_str": "\"debug\": false"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Hasil

Semua hasil eksekusi mencakup:

• stdout: Output dari eksekusi yang berhasil
• stderr: Pesan error jika eksekusi gagal
• return_code: 0 untuk berhasil, bukan nol untuk gagal

Field tambahan untuk operasi file:

• View: file_type, content, numLines, startLine, totalLines
• Create: is_file_update (apakah file sudah ada sebelumnya)
• Edit: oldStart, oldLines, newStart, newLines, lines (format diff)



Error

Setiap jenis alat dapat mengembalikan error tertentu:

Error umum (semua alat):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Kode error berdasarkan jenis alat:



Stop reason pause_turn

Respons dapat menyertakan stop reason pause_turn, yang menunjukkan bahwa API menjeda giliran yang berjalan lama. Anda dapat memberikan respons tersebut apa adanya dalam permintaan berikutnya agar Claude melanjutkan gilirannya, atau memodifikasi konten jika Anda ingin menginterupsi percakapan.



Kontainer

Alat eksekusi kode berjalan dalam lingkungan terkontainerisasi yang aman, dirancang khusus untuk eksekusi kode, dengan fokus lebih tinggi pada Python.



Lingkungan runtime

• Versi Python: 3.11.12
• Sistem operasi: Kontainer berbasis Linux
• Arsitektur: x86_64 (AMD64)



Batas sumber daya

• Memori: 5GiB RAM
• Ruang disk: 5GiB penyimpanan workspace
• CPU: 1 CPU



Jaringan dan keamanan

• Akses internet: Sepenuhnya dinonaktifkan demi keamanan
• Koneksi eksternal: Tidak ada permintaan jaringan keluar yang diizinkan
• Isolasi sandbox: Isolasi penuh dari sistem host dan kontainer lainnya
• Akses file: Terbatas hanya pada direktori workspace
• Cakupan workspace: Seperti Files, kontainer dicakup ke workspace dari kunci API
• Kedaluwarsa: Kontainer kedaluwarsa 30 hari setelah dibuat



Library yang sudah terinstal

Lingkungan Python sandbox mencakup library yang umum digunakan berikut:

• Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualisasi: matplotlib, seaborn
• Pemrosesan File: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Matematika & Komputasi: sympy, mpmath
• Utilitas: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite



Penggunaan ulang kontainer

Anda dapat menggunakan kembali kontainer yang sudah ada di beberapa permintaan API dengan memberikan ID kontainer dari respons sebelumnya. Ini memungkinkan Anda mempertahankan file yang dibuat di antara permintaan.



Contoh



Streaming

Dengan streaming diaktifkan, Anda akan menerima event eksekusi kode saat terjadi:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}}

// Code execution streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// Pause while code executes

// Execution results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}



Permintaan batch

Anda dapat menyertakan alat eksekusi kode dalam Messages Batches API. Pemanggilan alat eksekusi kode melalui Messages Batches API dikenakan harga yang sama dengan permintaan Messages API reguler.



Penggunaan dan harga

Code execution gratis jika digunakan bersama web search atau web fetch. Ketika web_search_20260209 atau web_fetch_20260209 disertakan dalam permintaan API Anda, tidak ada biaya tambahan untuk panggilan alat code execution selain biaya token input dan output standar.

Ketika digunakan tanpa alat-alat tersebut, code execution ditagih berdasarkan waktu eksekusi, yang dilacak secara terpisah dari penggunaan token:

• Waktu eksekusi memiliki minimum 5 menit
• Setiap organisasi menerima 1.550 jam gratis penggunaan per bulan
• Penggunaan tambahan di luar 1.550 jam ditagih sebesar $0,05 per jam, per kontainer
• Jika file disertakan dalam permintaan, waktu eksekusi tetap ditagih meskipun alat tidak dipanggil, karena file dimuat terlebih dahulu ke dalam kontainer

Penggunaan code execution dilacak dalam respons:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



Upgrade ke versi alat terbaru

Dengan melakukan upgrade ke code-execution-2025-08-25, Anda mendapatkan akses ke kemampuan manipulasi file dan Bash, termasuk kode dalam berbagai bahasa. Tidak ada perbedaan harga.



Apa yang berubah



Kompatibilitas mundur

• Semua eksekusi kode Python yang ada terus berfungsi persis seperti sebelumnya
• Tidak ada perubahan yang diperlukan pada alur kerja yang hanya menggunakan Python



Langkah-langkah upgrade

Untuk melakukan upgrade, perbarui tipe alat dalam permintaan API Anda:

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

Tinjau penanganan respons (jika mem-parsing respons secara programatik):

• Blok sebelumnya untuk respons eksekusi Python tidak akan lagi dikirim
• Sebagai gantinya, tipe respons baru untuk Bash dan operasi file akan dikirim (lihat bagian Format Respons)



Pemanggilan alat secara programatik

Untuk menjalankan alat di dalam kontainer eksekusi kode, lihat Pemanggilan alat secara programatik.



Retensi data

Eksekusi kode berjalan dalam kontainer sandbox sisi server. Data kontainer, termasuk artefak eksekusi, file yang diunggah, dan output, disimpan hingga 30 hari. Retensi ini berlaku untuk semua data yang diproses dalam lingkungan kontainer. File yang dibuat oleh eksekusi kode di Files API (dapat diambil melalui client.beta.files.download()) tetap ada hingga dihapus secara eksplisit.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.



Menggunakan eksekusi kode dengan Agent Skills

Alat eksekusi kode memungkinkan Claude menggunakan Agent Skills. Skills adalah kemampuan modular yang terdiri dari instruksi, skrip, dan sumber daya yang memperluas fungsionalitas Claude.

Pelajari lebih lanjut di Agent Skills dan Menggunakan Agent Skills dengan API.