Code execution tool

データ分析、可視化、複雑な計算、アップロードしたファイルの処理を、API の会話の中で直接行えます。コマンドはすべて API のサーバー側で実行され、結果は同じリクエストの中で Claude に返されます。

API はすべてのコマンドをサーバー側で実行し、同じリクエストの中で結果を Claude に返します。そのため、利用者がコードを実行したり tool_result ブロックを送り返したりする必要はありません。ただし、Claude が利用者側のクライアントツールも呼び出す場合は例外です。

• 処理はすべてサンドボックス化されたコンテナで実行され、インターネットへのアクセスはセキュリティのため完全に無効です。実行時にパッケージをダウンロードできず、使えるのはあらかじめ入っているライブラリだけです。
• Bash コマンドの結果には stdout、stderr、return_code と、$OUTPUT_DIR に残った各ファイルの file_id を含む content リストが入ります。
• ストリーミングを有効にすると、コード実行のイベントを発生順に受け取れます。サブツールの入力は input_json_delta イベントとして流れ、各結果ブロックは 1 つの content_block_start イベントでまとめて届きます。
• Messages Batches API のリクエストにも Code execution tool を含められます。

コードを実行するかどうか判断が分かれる依頼では、「run code to verify this」のように明示的にコードの実行を依頼します。

ツールのバージョンは type の文字列で選びます。現在の 3 つのバージョンの間は、リクエストの type を書き換えるだけで切り替えられ、どのバージョンも anthropic-beta ヘッダーは不要です。

• code_execution_20260120: REPL の状態保持と、サンドボックス内からのプログラムによるツール呼び出し (programmatic tool calling) を追加したバージョンです。プログラムによるツール呼び出しに必要な最小バージョンです。Claude Fable 5、Claude Mythos 5、Claude Opus 4.5 以降、Claude Sonnet 4.5 以降のモデルで利用できます。
• code_execution_20260521: code_execution_20260120 と同じランタイムです。違いは、プログラムによるツール呼び出しでの Python セルごとの実行時間上限 90 秒をツール説明で Claude に伝える点で、Claude は長時間かかるセルの時間配分を見積もれます。

モデルがこのツールを受け付けるかは、リクエストを送る前に Models API の capabilities.server_tools.code_execution.supported の値で確認します。最上位の capabilities.code_execution の値はこの確認に使いません。

旧バージョンの code_execution_20250522 から移行する場合は、API リクエストのツールの type を code_execution_20250825 に更新します。Bash とファイル操作については以前のブロックに代わる新しい応答の型が返るため、応答をプログラムで解析している場合は処理を見直します。

各リクエストは、前の応答のコンテナ ID を渡さない限り新しいコンテナで実行されます。同じコンテナを使い続けるには、応答に含まれるコンテナの id を、リクエストの最上位の container パラメーターに渡します。

• コンテナは作成から 30 日で期限が切れます。約 5 分操作が無いとチェックポイントが取られ、30 日以内にその ID を付けてリクエストを送ると復元されます。
• 期限切れのコンテナは再利用できず、参照するとエラーが返ります。container パラメーターを付けずにリクエストを送り直すと、新しいコンテナが割り当てられます。
• 応答の停止理由が pause_turn の場合は、その応答をそのまま次のリクエストに渡すと Claude がターンを続けます。このとき応答のコンテナ ID も一緒に送ります。送らないと新しいコンテナで実行され、そのターンの前半に作られたファイルは失われます。

Claude が出力ディレクトリに保存したファイルは、各ファイルの ID がツールの結果に含まれ、Files API でダウンロードできます。結果として返るのは $OUTPUT_DIR の最上位にあるファイルだけで、それ以外の場所に書かれたファイルはコンテナに残り、返されません。アプリケーションがファイルの受け取りを前提にしている場合は、ファイルを $OUTPUT_DIR にコピーし、同じコマンドでそのディレクトリを一覧表示するよう Claude に指示します。ls の出力で取り込みを確かめられます。

• 実行の生成物、アップロードしたファイル、出力を含むコンテナのデータは、最大 30 日間保持されます。
• コンテナからインターネットへのアクセスはできません。
• Claude API では、サンドボックスで Claude が作成した対応形式の画像・動画・音声ファイルを Files API でダウンロードすると、C2PA の Content Credentials が付いています。テキストファイル、PDF、オフィス文書は署名の対象形式ではないため、署名されません。
• 利用者側で用意した実行ツールと併用する場合は、両者の実行環境の違いをシステムプロンプトで明確に指示します。

自分のファイルをアップロードして分析させる場合の流れです。

1. Files API を使ってファイルをアップロードします。
2. メッセージの中で、container_upload コンテンツブロックを使ってそのファイルを参照します。
3. API リクエストに Code execution tool を含めます。ツール定義では type にツールのバージョン (例: code_execution_20250825) を、name に code_execution を指定し、追加のパラメーターは不要です。