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 yang lebih baru) atau web_fetch_20260209 (atau yang lebih baru) disertakan dalam permintaan Anda, tidak ada biaya tambahan untuk panggilan alat eksekusi kode di luar biaya token input dan output standar. Biaya eksekusi kode standar berlaku ketika alat-alat ini tidak disertakan.

Eksekusi kode adalah primitif inti untuk membangun agen berkinerja tinggi. Ini memungkinkan pemfilteran dinamis pada alat web search dan web fetch, sehingga Claude dapat memproses hasil sebelum mencapai 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 (memerlukan deployment Hosted on Anthropic)

Eksekusi kode saat ini tidak tersedia di Amazon Bedrock atau Google Cloud.



Mulai cepat

Berikut adalah contoh sederhana yang meminta Claude melakukan perhitungan:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "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)



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 dikenal luas
• Permintaan faktual, percakapan, atau kreatif
• Konversi unit atau terjemahan sederhana

Jika Anda ingin Claude menjalankan kode untuk permintaan yang berada di batas, 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 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

client = anthropic.Anthropic()

# Unggah file
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Gunakan file_id dengan eksekusi kode
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)



Mengambil file yang dihasilkan

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

# Inisialisasi klien
client = Anthropic()

# Minta eksekusi kode yang membuat file
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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):
    file_ids = []
    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":
                # list bertipe konkret: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.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}")



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 kesalahan 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)



Kesalahan

Setiap jenis alat dapat mengembalikan kesalahan tertentu:

Kesalahan 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 kesalahan 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: Penyimpanan workspace 5GiB
• CPU: 1 CPU



Jaringan dan keamanan

• Akses internet: Dinonaktifkan sepenuhnya 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 pembuatan



Pustaka yang sudah terpasang

Lingkungan Python sandbox mencakup pustaka 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

# Permintaan pertama: Buat file dengan angka acak
response1 = client.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Ekstrak ID kontainer dari respons pertama
container_id = response1.container.id

# Permintaan kedua: Gunakan kembali kontainer untuk membaca file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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)



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. Panggilan alat eksekusi kode melalui Messages Batches API dikenakan harga yang sama dengan permintaan Messages API reguler.



Penggunaan dan harga

Code execution gratis ketika digunakan bersama web search atau web fetch. Ketika web_search_20260209 (atau versi lebih baru) atau web_fetch_20260209 (atau versi lebih baru) 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 khusus Python yang sudah ada



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 terprogram):

• 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 terprogram

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



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.