Alat eksekusi kode

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

Eksekusi kode gratis saat digunakan dengan pencarian web atau pengambilan web. Ketika web_search_20260209 atau web_fetch_20260209 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 penyaringan dinamis dalam alat pencarian web dan pengambilan web, memungkinkan Claude memproses hasil sebelum mencapai jendela konteks, meningkatkan akurasi sambil mengurangi konsumsi token.

Kompatibilitas model

Alat eksekusi kode tersedia pada model berikut:

Ketersediaan platform

Eksekusi kode tersedia di:

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

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

Mulai cepat

Berikut adalah contoh sederhana yang meminta Claude untuk 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 secara otomatis memberikan Claude dengan kemampuan berikut:
   • Perintah Bash: Jalankan perintah shell untuk operasi sistem dan manajemen paket
   • Operasi file: Buat, lihat, dan edit 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 dengan grafik, perhitungan, atau analisis yang dihasilkan

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 khusus), Claude beroperasi dalam lingkungan multi-komputer. Alat eksekusi kode berjalan dalam kontainer bersandbox Anthropic, sementara alat yang disediakan klien Anda berjalan di lingkungan terpisah yang Anda kontrol. Claude kadang-kadang dapat membingungkan lingkungan ini, mencoba menggunakan alat yang salah atau mengasumsikan status dibagikan di antara mereka.

Untuk menghindari 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

Ini sangat penting ketika menggabungkan eksekusi kode dengan pencarian web atau pengambilan web, yang mengaktifkan eksekusi kode secara otomatis. Jika aplikasi Anda sudah menyediakan alat shell sisi klien, eksekusi kode otomatis menciptakan lingkungan eksekusi kedua yang perlu Claude bedakan.

Cara menggunakan alat

Unggah dan analisis file Anda sendiri

Untuk menganalisis file data Anda sendiri (CSV, Excel, gambar, dll.), 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, dll)

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 code execution dalam permintaan API Anda

Ambil file yang dihasilkan

Ketika Claude membuat file selama code execution, Anda dapat mengambil file ini menggunakan Files API:

Definisi alat

Alat code execution 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: Jalankan perintah shell
• text_editor_code_execution: Lihat, buat, dan edit file, termasuk menulis kode

Format respons

Alat code execution dapat mengembalikan dua jenis hasil tergantung pada operasi:

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

Lihat 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
  }
}

Buat 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
  }
}

Edit 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 sukses, non-nol untuk kegagalan

Bidang tambahan untuk operasi file:

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

Kesalahan

Setiap jenis alat dapat mengembalikan kesalahan spesifik:

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:

Alasan penghentian pause_turn

Respons mungkin menyertakan alasan penghentian pause_turn, yang menunjukkan bahwa API menjeda giliran yang berjalan lama. Anda dapat memberikan respons kembali apa adanya dalam permintaan berikutnya untuk membiarkan Claude melanjutkan gilirannya, atau memodifikasi konten jika Anda ingin mengganggu percakapan.

Kontainer

Alat code execution berjalan di lingkungan kontainer yang aman dan dirancang khusus untuk code execution, dengan fokus yang 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 ruang kerja
• CPU: 1 CPU

Jaringan dan keamanan

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

Perpustakaan yang sudah diinstal sebelumnya

Lingkungan Python yang disandboxkan mencakup perpustakaan yang umum digunakan ini:

• 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 ada di beberapa permintaan API dengan menyediakan ID kontainer dari respons sebelumnya. Ini memungkinkan Anda untuk mempertahankan file yang dibuat antar permintaan.

Contoh

Streaming

Dengan streaming diaktifkan, Anda akan menerima peristiwa 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"}}

// Kode eksekusi di-streaming
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())\"}"}}

// Jeda saat kode dieksekusi

// Hasil eksekusi di-streaming
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 dihargai sama dengan yang ada di permintaan Messages API biasa.

Penggunaan dan harga

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

• Execution time has a minimum of 5 minutes
• Each organization receives 1,550 free hours of usage per month
• Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
• If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

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

Tingkatkan ke versi alat terbaru

Dengan meningkatkan 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 untuk alur kerja Python saja yang ada

Langkah-langkah peningkatan

Untuk meningkatkan, perbarui jenis alat dalam permintaan API Anda:

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

Tinjau penanganan respons (jika mengurai respons secara terprogram):

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

Pemanggilan alat terprogram

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

Retensi data

Eksekusi kode berjalan dalam kontainer sandbox di 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 eksekusi kode di Files API (dapat diambil melalui client.beta.files.download()) bertahan sampai 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 untuk menggunakan Agent Skills. Skills adalah kemampuan modular yang terdiri dari instruksi, skrip, dan sumber daya yang memperluas fungsionalitas Claude.

Pelajari lebih lanjut di dokumentasi Agent Skills dan panduan API Agent Skills.