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 (web_search_20260209, web_fetch_20260209, atau yang lebih baru). Ketika salah satu alat tersebut ada dalam permintaan Anda, tidak ada biaya tambahan untuk eksekusi kode dalam permintaan tersebut di luar biaya token standar. Ini mencakup eksekusi kode di balik pemfilteran dinamis maupun kode apa pun yang dijalankan Claude secara langsung. Harga eksekusi kode standar berlaku ketika alat-alat tersebut tidak disertakan.
Eksekusi kode juga mendukung pemfilteran dinamis pada alat web search dan web fetch: Claude memfilter hasil di dalam lingkungan eksekusi kode sebelum hasil tersebut mencapai jendela konteks. Ketika pemfilteran dinamis berjalan, API menyediakan eksekusi kode yang dibutuhkan untuk permintaan tersebut secara otomatis, sehingga Anda tidak perlu menambahkan alat eksekusi kode ke permintaan Anda untuk itu.
Alat eksekusi kode tersedia pada model-model berikut:
| Model | Versi alat |
|---|---|
| Claude Opus 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Fable 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Mythos 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Sonnet 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.8 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.7 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.6 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Sonnet 4.6 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Sonnet 4.5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Haiku 4.5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
Setiap versi alat dibangun di atas versi sebelumnya:
code_execution_20250825 mendukung perintah Bash dan operasi file.code_execution_20260120 menambahkan persistensi state REPL dan pemanggilan alat secara terprogram dari dalam sandbox. Claude Haiku 4.5 menerima tipe alat code_execution_20260120 dan code_execution_20260521, tetapi pemanggilan alat secara terprogram dan persistensi state REPL yang bergantung padanya tidak tersedia di sana, sehingga versi yang lebih baru berperilaku seperti code_execution_20250825 pada model tersebut.code_execution_20260521 adalah runtime yang sama dengan code_execution_20260120. Perbedaannya adalah deskripsi alat memberi tahu Claude tentang batas waktu wall-clock 90 detik pada setiap sel Python dalam pemanggilan alat secara terprogram, sehingga Claude dapat mengatur anggaran untuk sel yang berjalan lama. Sel yang melebihi batas tersebut mengembalikan hasil eksekusi kode normal dengan return_code bukan nol dan pesan status detection_timeout dalam outputnya. Ini terpisah dari kode error execution_time_exceeded, yang dikembalikan API ketika seluruh pemanggilan alat melebihi waktu eksekusi maksimum.Ketiga versi alat tersebut tersedia secara umum dan tidak memerlukan header anthropic-beta. Header beta eksekusi kode lama tetap valid sebagai opt-in.
Contoh-contoh di halaman ini menggunakan code_execution_20250825, yang mencakup operasi Bash dan file yang didemonstrasikan dan berperilaku sama pada setiap model dalam tabel; gunakan code_execution_20260120 atau yang lebih baru ketika Anda membutuhkan pemanggilan alat secara terprogram atau persistensi state REPL. Alat web search dan web fetch terkini (web_search_20260209, web_fetch_20260209, dan yang lebih baru) memerlukan code_execution_20260120 atau yang lebih baru sebagai versi eksekusi kodenya.
Eksekusi kode tersedia di:
Eksekusi kode saat ini tidak tersedia di Amazon Bedrock atau Google Cloud.
Berikut adalah contoh yang meminta Claude melakukan perhitungan:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.to_json())Respons menyelingi blok server_tool_use (perintah yang dijalankan Claude) dengan blok hasil alatnya, diikuti oleh teks Claude. Level teratas juga menyertakan objek container yang id-nya dapat Anda gunakan kembali di seluruh permintaan. Lihat Format respons untuk bentuk bloknya.
Ketika Anda menambahkan alat eksekusi kode ke permintaan API Anda:
tool_result sendiri. Satu pengecualian adalah ketika Claude memanggil salah satu alat klien Anda bersamaan dengan eksekusi kode: API mengembalikan panggilan eksekusi kode tanpa hasilnya. Hasilnya tiba dalam respons berikutnya, setelah Anda mengirim kembali blok tool_result untuk alat klien AndaKontainer memiliki Python yang sudah terinstal. Claude menulis Python dengan sub-alat operasi file dan menjalankannya dengan perintah Bash. Dengan code_execution_20260120 atau yang lebih baru dan pemanggilan alat secara terprogram, state interpreter Python (seperti binding variabel) juga bertahan di seluruh permintaan yang menggunakan kembali kontainer tersebut.
Claude menjalankan kode ketika permintaan mendapat manfaat dari komputasi atau penanganan file:
Claude menjawab langsung tanpa menjalankan kode untuk:
Jika Anda ingin Claude menjalankan kode untuk permintaan yang berada di batas, minta secara eksplisit (misalnya, "jalankan kode untuk memverifikasi ini").
Untuk menganalisis file data Anda sendiri (seperti CSV, Excel, atau gambar), unggah melalui Files API dan referensikan dalam permintaan Anda:
Lingkungan Python dapat memproses berbagai tipe file yang diunggah melalui Files API, termasuk:
container_uploadclient = anthropic.Anthropic()
# Unggah file
file_object = client.beta.files.upload(file=Path("data.csv"))
# Gunakan file_id dengan eksekusi kode
response = client.beta.messages.create(
model="claude-opus-5",
betas=["files-api-2025-04-14"],
max_tokens=4096,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Analyze this CSV data"},
{"type": "container_upload", "file_id": file_object.id},
],
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.to_json())Ketika Claude membuat file selama eksekusi kode, ID setiap file yang dibuat muncul dalam hasil alat eksekusi kode, dan Anda dapat mengunduhnya dengan Files API:
client = Anthropic()
# Minta eksekusi kode yang membuat file
response = client.beta.messages.create(
model="claude-opus-5",
betas=["files-api-2025-04-14"],
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Create a matplotlib visualization and save it as output.png",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Ekstrak ID file dari respons
def extract_file_ids(response: BetaMessage) -> list[str]:
file_ids: list[str] = []
for item in response.content:
if item.type == "bash_code_execution_tool_result":
content_item = item.content
if content_item.type == "bash_code_execution_result":
for output_block in content_item.content:
file_ids.append(output_block.file_id)
return file_ids
# Unduh file yang dibuat
for file_id in extract_file_ids(response):
file_metadata = client.beta.files.retrieve_metadata(file_id)
file_content = client.beta.files.download(file_id)
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")Alat eksekusi kode tidak memerlukan parameter tambahan:
{
"type": "code_execution_20250825",
"name": "code_execution"
}Kedua field bersifat tetap: type memilih versi alat, dan name harus code_execution.
Ketika Anda menyediakan alat ini, Claude secara otomatis mendapatkan akses ke dua sub-alat:
bash_code_execution: Menjalankan perintah shelltext_editor_code_execution: Melihat, membuat, dan mengedit file, termasuk menulis kodeKetika Claude menjalankan kode, respons juga menyertakan objek container di level teratas dengan id kontainer dan timestamp expires_at. Teruskan kembali ID tersebut dalam parameter permintaan container di level teratas untuk terus menggunakan kontainer yang sama. Lihat Penggunaan kembali kontainer.
Alat eksekusi kode dapat mengembalikan dua jenis hasil tergantung pada operasinya:
{
"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,
"content": []
}
}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_view_result",
"file_type": "text",
"content": "{\n \"setting\": \"value\",\n \"debug\": true\n}",
"num_lines": 4,
"start_line": 1,
"total_lines": 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_create_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_str_replace_result",
"old_start": 3,
"old_lines": 1,
"new_start": 3,
"new_lines": 1,
"lines": ["- \"debug\": true", "+ \"debug\": false"]
}
}Hasil perintah Bash (bash_code_execution_result) mencakup:
stdout: Output dari eksekusi yang berhasilstderr: Pesan error jika eksekusi gagalreturn_code: 0 untuk berhasil, bukan nol untuk gagalcontent: Daftar dengan satu entri untuk setiap file yang dibuat oleh perintah. Setiap entri membawa file_id untuk mengambil file dengan Files APIHasil operasi file memiliki field-nya sendiri:
text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_linestext_editor_code_execution_create_result): is_file_update (apakah file sudah ada sebelumnya)text_editor_code_execution_str_replace_result): old_start, old_lines, new_start, new_lines, lines (format diff)Setiap tipe 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 tipe alat:
| Alat | Kode error | Deskripsi |
|---|---|---|
| Semua alat | unavailable | Alat sementara tidak tersedia |
| Semua alat | execution_time_exceeded | Pemanggilan alat melebihi waktu eksekusi maksimum |
| Semua alat | invalid_tool_input | Parameter yang diberikan ke alat tidak valid |
| Semua alat | too_many_requests | Batas laju terlampaui untuk penggunaan alat |
| bash | output_file_too_large | Output perintah melebihi ukuran maksimum |
| text_editor | file_not_found | File tidak ada (untuk operasi view/edit) |
Kontainer yang kedaluwarsa tidak dapat digunakan kembali: permintaan yang mereferensikannya mengembalikan error alih-alih memulihkannya. Kirim permintaan lagi tanpa parameter container untuk mendapatkan kontainer baru.
pause_turnRespons mungkin 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.
Alat eksekusi kode berjalan dalam lingkungan terkontainerisasi yang aman yang dirancang khusus untuk eksekusi kode, dengan fokus lebih tinggi pada Python.
execution_time_exceeded. Dengan pemanggilan alat secara terprogram, setiap sel REPL juga memiliki batas waktu wall-clock 90 detikLingkungan Python sandbox menyertakan pustaka yang umum digunakan berikut:
Kontainer juga menyertakan alat command-line seperti unzip, unrar, 7zip, bc, rg (ripgrep), fd, dan sqlite.
Kontainer tidak memiliki akses internet, sehingga Claude tidak dapat mengunduh atau menginstal paket tambahan saat runtime: hanya pustaka yang sudah terinstal yang tersedia.
Anda dapat menggunakan kembali kontainer yang ada di beberapa permintaan API dengan memberikan ID kontainer dari respons sebelumnya.
Ini memungkinkan Anda mempertahankan file yang dibuat di antara permintaan. Dengan code_execution_20260120 atau yang lebih baru dan pemanggilan alat secara terprogram, state interpreter Python juga bertahan.
Kontainer kedaluwarsa 30 hari setelah pembuatan. Setelah sekitar 5 menit tidak aktif, kontainer di-checkpoint, dan mengirim permintaan dengan ID-nya dalam jendela 30 hari akan memulihkannya. Timestamp expires_at dalam objek container respons adalah nilai bergulir yang lebih pendek dan tidak melaporkan batas 30 hari. Kontainer yang telah kedaluwarsa tidak dapat digunakan kembali. Kirim permintaan lagi tanpa parameter container untuk mendapatkan kontainer baru.
client = anthropic.Anthropic()
# Permintaan pertama: buat file dengan angka acak di kontainer baru
response1 = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Write a file with a random number and save it to '/tmp/number.txt'",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Permintaan kedua: kirim kembali ID kontainer agar Claude menggunakan kontainer yang sama
response2 = client.messages.create(
container=response1.container.id,
model="claude-opus-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Read the number from '/tmp/number.txt' and calculate its square",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response2.to_json())Ketika Anda menyediakan eksekusi kode bersama alat yang disediakan klien yang juga menjalankan kode (seperti alat Bash atau REPL kustom), Claude beroperasi dalam lingkungan multikomputer. Alat eksekusi kode berjalan dalam kontainer sandbox 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 stateIni 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.
Ketika Claude memanggil salah satu alat klien Anda bersamaan dengan eksekusi kode, API mengembalikan panggilan eksekusi kode tanpa hasilnya. Hasilnya tiba dalam respons berikutnya, setelah Anda mengirim kembali blok tool_result untuk alat klien Anda.
Dengan streaming diaktifkan ("stream": true), Anda akan menerima event eksekusi kode saat terjadi. Input sub-alat di-stream sebagai event input_json_delta, dan setiap blok hasil tiba utuh dalam satu event content_block_start:
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}
// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}
// Pause while the command runs
// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": " A B C\n0 1 2 3\n1 4 5 6", "stderr": "", "return_code": 0, "content": []}}}Anda dapat menyertakan alat eksekusi kode dalam Messages Batches API. Panggilan alat eksekusi kode melalui Messages Batches API dihargai sama dengan panggilan dalam permintaan Messages API reguler.
Eksekusi kode gratis saat digunakan dengan web search atau web fetch. Ketika web_search_20260209 (atau yang lebih baru) atau web_fetch_20260209 (atau yang lebih baru) disertakan dalam permintaan API Anda, tidak ada biaya tambahan untuk pemanggilan alat eksekusi kode di luar biaya token input dan output standar.
Saat digunakan tanpa alat-alat tersebut, eksekusi kode ditagih berdasarkan waktu eksekusi, yang dilacak secara terpisah dari penggunaan token:
Penggunaan eksekusi kode dilacak dalam respons:
{
"usage": {
"input_tokens": 105,
"output_tokens": 239,
"server_tool_use": {
"code_execution_requests": 1
}
}
}Versi alat terbaru adalah code_execution_20260521. Untuk berpindah di antara tiga versi terkini, perbarui string type dalam permintaan Anda: ketiganya mengembalikan blok respons yang didokumentasikan dalam Format respons. Lihat Kompatibilitas model untuk mengetahui apa yang ditambahkan setiap versi dan model mana yang mendukungnya.
Bagian selanjutnya dari bagian ini membahas migrasi dari code_execution_20250522 lama yang hanya mendukung Python ke versi alat terkini.
| Komponen | Lama | Terkini |
|---|---|---|
| Header beta | code-execution-2025-05-22 | Tidak diperlukan |
| Tipe alat | code_execution_20250522 | code_execution_20250825 atau yang lebih baru |
| Kemampuan | Hanya Python | Perintah Bash, operasi file |
| Tipe respons | code_execution_result | bash_code_execution_result, text_editor_code_execution_*_result |
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 terprogram):
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 dengan client.beta.files.download()) bertahan hingga dihapus secara eksplisit.
Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.
Pasangkan model eksekutor yang lebih cepat dengan model advisor berkecerdasan lebih tinggi yang memberikan panduan strategis di tengah proses generasi.
Panggil alat Anda sendiri dari kode yang berjalan di dalam kontainer eksekusi kode.
Unggah file untuk analisis dan unduh file yang dibuat oleh eksekusi kode.
Pelajari cara menggunakan Agent Skills untuk memperluas kemampuan Claude melalui API.
Was this page helpful?