Alat eksekusi kode

Alat eksekusi kode memungkinkan Claude untuk menjalankan kode Python dalam lingkungan yang aman dan terisolasi. Claude dapat menganalisis data, membuat visualisasi, melakukan perhitungan kompleks, dan memproses file yang diunggah langsung dalam percakapan API.

​

Model yang didukung

Alat eksekusi kode tersedia pada:

• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
• Claude Haiku 3.5 (claude-3-5-haiku-latest)

​

Mulai cepat

Berikut contoh sederhana yang meminta Claude untuk melakukan perhitungan:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-05-22" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "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_20250522",
            "name": "code_execution"
        }]
    }'

​

Bagaimana eksekusi kode bekerja

Ketika Anda menambahkan alat eksekusi kode ke permintaan API Anda:

1. Claude mengevaluasi apakah eksekusi kode akan membantu menjawab pertanyaan Anda
2. Claude menulis dan mengeksekusi kode Python dalam lingkungan sandbox yang aman
3. Eksekusi kode dapat terjadi beberapa kali selama satu permintaan
4. Claude memberikan hasil dengan grafik, perhitungan, atau analisis yang dihasilkan

​

Definisi alat

Alat eksekusi kode tidak memerlukan parameter tambahan:

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

​

Format respons

Berikut contoh respons dengan eksekusi kode:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll calculate the mean and standard deviation for you."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "name": "code_execution",
      "input": {
        "code": "import numpy as np\ndata = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\nmean = np.mean(data)\nstd = np.std(data)\nprint(f\"Mean: {mean}\")\nprint(f\"Standard deviation: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Mean: 5.5\nStandard deviation: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "The mean of the dataset is 5.5 and the standard deviation is approximately 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
    "server_tool_use": {
      "execution_time_seconds": 1.5
    }
  }
}

​

Hasil

Hasil eksekusi kode mencakup:

• stdout: Output dari pernyataan print dan eksekusi yang berhasil
• stderr: Pesan kesalahan jika eksekusi kode gagal
• return_code (0 untuk sukses, bukan nol untuk kegagalan)

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "NameError: name 'undefined_variable' is not defined",
    "return_code": 1
  }
}

​

Kesalahan

Jika terjadi kesalahan saat menggunakan alat, akan ada code_execution_tool_result_error

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Kemungkinan kesalahan meliputi

• unavailable: Alat eksekusi kode tidak tersedia
• code_execution_exceeded: Waktu eksekusi melebihi maksimum yang diizinkan
• container_expired: Kontainer kedaluwarsa dan tidak tersedia

​

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 mengganggu percakapan.

​

Kontainer

Alat eksekusi kode berjalan dalam lingkungan terkontainer yang aman yang dirancang khusus untuk eksekusi kode Python.

​

Lingkungan runtime

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

​

Batasan sumber daya

• Memori: 1GiB RAM
• Ruang disk: 5GiB penyimpanan workspace
• CPU: 1 CPU
• Batas waktu eksekusi: Eksekusi dibatasi per permintaan pesan dan dapat dikontrol dengan parameter max_execution_duration
• Kedaluwarsa Kontainer: Setelah 1 jam tidak aktif, kontainer tidak dapat diakses lagi

​

Jaringan dan keamanan

• Akses internet: Dinonaktifkan sepenuhnya untuk keamanan
• Koneksi eksternal: Tidak ada permintaan jaringan keluar yang diizinkan
• Isolasi sandbox: Isolasi penuh dari sistem host dan kontainer lain
• Akses file: Terbatas hanya pada direktori workspace

​

Pustaka yang telah diinstal

Lingkungan Python yang terisolasi mencakup pustaka yang umum digunakan ini:

• Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualisasi: matplotlib, seaborn
• Pemrosesan File: pyarrow, openpyxl, xlrd, pillow
• Matematika & Komputasi: sympy, mpmath
• Utilitas: tqdm, python-dateutil, pytz, joblib

​

Bekerja dengan File dalam Eksekusi Kode

Eksekusi kode dapat menganalisis file yang diunggah melalui API Files, seperti file CSV, file Excel, dan format data lainnya. Ini memungkinkan Claude untuk membaca, memproses, dan menghasilkan wawasan dari data Anda.

​

Jenis file yang didukung

Lingkungan Python mampu bekerja dengan tetapi tidak terbatas pada jenis file berikut

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

​

Contoh

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

# Pertama, unggah 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"' \

# Kemudian gunakan file_id dengan eksekusi kode
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-05-22,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "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_20250522",
            "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"}}

// Eksekusi kode yang distreaming
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 distreaming
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 API Messages Batches. Panggilan alat eksekusi kode melalui API Messages Batches dihargai sama dengan yang ada dalam permintaan API Messages biasa.

​

Penggunaan dan harga

Penggunaan alat eksekusi kode dilacak secara terpisah dari penggunaan token. Waktu eksekusi minimal 5 menit. Jika file disertakan dalam permintaan, waktu eksekusi ditagih meskipun alat tidak digunakan karena file telah dimuat sebelumnya ke kontainer.

Harga: $0,05 per jam sesi.