コード実行ツールを使用すると、Claudeは安全でサンドボックス化された環境でPythonコードを実行できます。 Claudeはデータを分析し、視覚化を作成し、複雑な計算を実行し、APIの会話内で直接アップロードされた ファイルを処理することができます。

この機能にはベータヘッダーが必要です: "anthropic-beta": "code-execution-2025-05-22"

​
サポートされているモデル

コード実行ツールは以下で利用可能です:

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

​
クイックスタート

以下は、Claudeに計算を実行するよう依頼する簡単な例です:

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

​
コード実行の仕組み

コード実行ツールをAPIリクエストに追加すると:

  1. Claudeは質問に答えるためにコード実行が役立つかどうかを評価します
  2. Claudeは安全なサンドボックス環境でPythonコードを記述して実行します
  3. コード実行は1つのリクエスト内で複数回発生する場合があります
  4. Claudeは生成されたチャート、計算、または分析を含む結果を提供します

​
ツール定義

コード実行ツールには追加のパラメータは必要ありません:

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

​
レスポンスフォーマット

以下はコード実行を含むレスポンスの例です:

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

​
結果

コード実行の結果には以下が含まれます:

  • stdout: print文と正常実行からの出力
  • stderr: コード実行が失敗した場合のエラーメッセージ
  • return_code (成功の場合は0、失敗の場合は0以外)
{
  "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
  }
}

​
エラー

ツールの使用中にエラーが発生した場合、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"
  }
}

考えられるエラーには以下が含まれます

  • unavailable: コード実行ツールが利用できません
  • code_execution_exceeded: 実行時間が許容される最大値を超えました
  • container_expired: コンテナの有効期限が切れて利用できません

​
pause_turn 停止理由

レスポンスには pause_turn 停止理由が含まれる場合があり、これはAPIが長時間実行されるターンを一時停止したことを示します。 Claudeにターンを続行させるために、レスポンスをそのまま後続のリクエストで提供することも、会話を中断したい場合は 内容を変更することもできます。

​
コンテナ

コード実行ツールは、Pythonコード実行専用に設計された安全なコンテナ化環境で実行されます。

​
ランタイム環境

  • Pythonバージョン: 3.11.12
  • オペレーティングシステム: Linuxベースのコンテナ
  • アーキテクチャ: x86_64 (AMD64)

​
リソース制限

  • メモリ: 1GiB RAM
  • ディスク容量: 5GiBワークスペースストレージ
  • CPU: 1 CPU
  • 実行タイムアウト: 実行はメッセージリクエストごとに制限され、max_execution_durationパラメータで制御できます
  • コンテナの有効期限: 1時間の非アクティブ状態後、コンテナにはアクセスできなくなります

​
ネットワークとセキュリティ

  • インターネットアクセス: セキュリティのために完全に無効化
  • 外部接続: アウトバウンドネットワークリクエストは許可されていません
  • サンドボックス分離: ホストシステムおよび他のコンテナからの完全な分離
  • ファイルアクセス: ワークスペースディレクトリのみに制限

​
プリインストールされたライブラリ

サンドボックス化されたPython環境には、これらの一般的に使用されるライブラリが含まれています:

  • データサイエンス: pandas, numpy, scipy, scikit-learn, statsmodels
  • 視覚化: matplotlib, seaborn
  • ファイル処理: pyarrow, openpyxl, xlrd, pillow
  • 数学と計算: sympy, mpmath
  • ユーティリティ: tqdm, python-dateutil, pytz, joblib

​
コード実行でのファイルの操作

コード実行では、Files APIを通じてアップロードされたCSVファイル、Excelファイル、その他のデータ形式などのファイルを分析できます。 これにより、Claudeはデータを読み取り、処理し、洞察を生成することができます。

コード実行でFiles APIを使用するには、2つのベータヘッダーが必要です: "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"

​
サポートされているファイルタイプ

Python環境は以下のファイルタイプを含む（ただしこれらに限定されない）ファイルタイプを処理できます

  • CSV
  • Excel (.xlsx, .xls)
  • JSON
  • XML
  • 画像 (JPEG, PNG, GIF, WebP)
  • テキストファイル (.txt, .md, .py, など)

​
例

  1. ファイルをアップロードする Files APIを使用
  2. ファイルを参照する container_upload コンテンツブロックを使用してメッセージ内で
  3. コード実行ツールを含める APIリクエストに
# まず、ファイルをアップロード
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_idをコード実行で使用
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"
        }]
    }'

​
ストリーミング

ストリーミングを有効にすると、コード実行イベントが発生した時点で受信できます:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}}

// コード実行がストリーミングされる
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())\"}"}}

// コード実行中の一時停止

// 実行結果がストリーミングされる
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": ""}}}

​
バッチリクエスト

Messages Batches APIでコード実行ツールを含めることができます。Messages Batches APIを通じたコード実行ツールの呼び出しは、通常のMessages APIリクエストと同じ価格です。

​
使用量と価格

コード実行ツールの使用量はトークン使用量とは別に追跡されます。実行時間は最低5分です。 リクエストにファイルが含まれている場合、ファイルがコンテナに事前ロードされるため、ツールが使用されなくても実行時間が課金されます。

価格: セッション時間あたり$0.05。