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 sandbox yang aman.

Eksekusi kode gratis saat digunakan dengan web search atau web fetch. 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 pemfilteran dinamis dalam alat web search dan web fetch, memungkinkan Claude 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)
• 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 melakukan perhitungan:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

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 kemampuan berikut kepada Claude:
   • 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 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 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 container sandbox Anthropic, sementara alat yang disediakan klien berjalan di lingkungan terpisah yang Anda kendalikan. Claude terkadang dapat membingungkan lingkungan-lingkungan ini, mencoba menggunakan alat yang salah atau mengasumsikan status dibagikan di antara keduanya.

Untuk menghindari hal ini, tambahkan instruksi ke system prompt Anda yang mengklarifikasi 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 saat 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

Menjalankan perintah Bash

Minta Claude untuk memeriksa informasi sistem dan menginstal paket:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Membuat dan mengedit file secara langsung

Claude dapat membuat, melihat, dan mengedit file secara langsung di sandbox menggunakan kemampuan manipulasi file:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Mengunggah dan menganalisis 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)

Mengunggah dan menganalisis 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

# First, upload a file
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \

# Then use the file_id with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Mengambil file yang dihasilkan

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

from anthropic import Anthropic

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Extract file IDs from the response
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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids


# Download the created files
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}")

Menggabungkan operasi

Alur kerja kompleks menggunakan semua kemampuan:

# First, upload a file
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \
    > file_response.json

# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Then use it with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
                },
                {
                    "type": "container_upload",
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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

Bidang tambahan untuk operasi file:

• View: file_type, content, numLines, startLine, totalLines
• Create: is_file_update (apakah file sudah ada)
• 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:

Alasan berhenti pause_turn

Respons mungkin menyertakan alasan berhenti 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 menginterupsi percakapan.

Container

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

Lingkungan runtime

• Versi Python: 3.11.12
• Sistem operasi: Container 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 untuk keamanan
• Koneksi eksternal: Tidak ada permintaan jaringan keluar yang diizinkan
• Isolasi sandbox: Isolasi penuh dari sistem host dan container lainnya
• Akses file: Terbatas hanya pada direktori workspace
• Cakupan workspace: Seperti Files, container dicakupkan ke workspace kunci API
• Kedaluwarsa: Container kedaluwarsa 30 hari setelah pembuatan

Pustaka yang sudah terinstal

Lingkungan Python sandbox mencakup pustaka yang umum digunakan ini:

• Ilmu Data: 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 container

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

Contoh

import os
from anthropic import Anthropic

# Initialize the client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# First request: Create a file with a random number
response1 = client.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-6",
    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"}],
)

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

// 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 dihargai sama dengan yang ada dalam 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
  }
}

Upgrade ke versi alat terbaru

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

Yang berubah

Kompatibilitas ke belakang

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

Langkah upgrade

Untuk melakukan upgrade, 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 Bash dan operasi file akan dikirim (lihat bagian Format Respons)

Pemanggilan alat terprogram

Alat eksekusi kode mendukung pemanggilan alat terprogram, yang memungkinkan Claude menulis kode yang memanggil alat kustom Anda secara terprogram dalam container eksekusi. Ini memungkinkan alur kerja multi-alat yang efisien, pemfilteran data sebelum mencapai konteks Claude, dan logika kondisional yang kompleks.

# Enable programmatic calling for your tools
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Get weather for 5 cities and find the warmest"}
    ],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "input_schema": {...},
            "allowed_callers": [
                "code_execution_20250825"
            ],  # Enable programmatic calling
        },
    ],
)

Pelajari lebih lanjut dalam dokumentasi pemanggilan alat terprogram.

Retensi data

Eksekusi kode berjalan di dalam container sandbox sisi server. Data container, termasuk artefak eksekusi, file yang diunggah, dan output, disimpan hingga 30 hari. Retensi ini berlaku untuk semua data yang diproses dalam lingkungan container.

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.