Claude Platform Docs
Messagesツール

コード実行ツール

サンドボックス化されたコンテナでPythonとbashのコードを実行し、データの分析、ファイルの生成、ソリューションの反復改善を行います。

Claudeは、APIの会話内で直接、データの分析、可視化の作成、複雑な計算の実行、システムコマンドの実行、ファイルの作成と編集、アップロードされたファイルの処理を行うことができます。コード実行ツールを使用すると、Claudeは安全な「sandboxed」（サンドボックス化された）環境で、Bashコマンドの実行やファイルの操作（コードの記述を含む）を行えます。

コード実行は、ウェブ検索またはウェブフェッチ（web_search_20260209、web_fetch_20260209、またはそれ以降）と併用する場合は無料です。 これらのツールのいずれかがリクエストに含まれている場合、そのリクエストでは標準のトークンコスト以外にコード実行の追加料金は発生しません。これは、動的フィルタリングの背後で行われるコード実行と、Claudeが直接実行するコードの両方に適用されます。これらのツールが含まれていない場合は、標準のコード実行料金が適用されます。

コード実行は、ウェブ検索ツールとウェブフェッチツールにおける「dynamic filtering」（動的フィルタリング）も支えています。Claudeは、結果が「context window」（コンテキストウィンドウ）に到達する前に、コード実行環境内で結果をフィルタリングします。動的フィルタリングが実行される場合、APIはリクエストに必要なコード実行を自動的にプロビジョニングするため、そのためにコード実行ツールをリクエストに追加する必要はありません。

ツールバージョン

コード実行ツールには現在3つのバージョンがあり、サポートされているすべてのモデルが3つすべてを受け付けます。各バージョンは前のバージョンを基に構築されています。

  • code_execution_20250825は、Bashコマンドとファイル操作をサポートします。
  • code_execution_20260120は、「read-eval-print loop」（対話型評価ループ）、すなわちREPLの状態の永続化と、サンドボックス内からの「programmatic tool calling」（プログラムによるツール呼び出し）を追加します。Claude Haiku 4.5はcode_execution_20260120およびcode_execution_20260521のツールタイプを受け付けますが、プログラムによるツール呼び出しと、それに依存するREPL状態の永続化は利用できないため、新しいバージョンはcode_execution_20250825と同様に動作します。
  • code_execution_20260521は、code_execution_20260120と同じランタイムです。違いは、ツールの説明がプログラムによるツール呼び出しにおける各Pythonセルの90秒の実時間制限についてClaudeに伝える点であり、これによりClaudeは長時間実行されるセルの時間配分を計画できます。制限を超えたセルは、ゼロ以外のreturn_codeと、出力内のdetection_timeoutステータスメッセージを含む通常のコード実行結果を返します。これは、ツール呼び出し全体が最大実行時間を超えた場合にAPIが返すexecution_time_exceededエラーコードとは別のものです。

3つのツールバージョンのいずれもanthropic-betaヘッダーを必要としません。従来のコード実行ベータヘッダーも、オプトインとして引き続き有効です。

このページの例ではcode_execution_20250825を使用しています。これは例で示すBashおよびファイル操作をカバーしており、サポートされているすべてのモデルで同じように動作します。プログラムによるツール呼び出しやREPL状態の永続化が必要な場合は、code_execution_20260120以降を使用してください。現在のウェブ検索ツールとウェブフェッチツール（web_search_20260209、web_fetch_20260209、およびそれ以降）では、コード実行バージョンとしてcode_execution_20260120以降が必要です。

古いツールバージョンは、新しいモデルとの互換性が維持されることは保証されていません。新しいモデルを採用する際は、ツールバージョンと互換性を確認し、統合がサポートする最新のツールバージョンを優先して使用してください。

リクエストを送信する前に、モデルがコード実行ツールを受け付けるかどうかを確認するには、Models APIからそのモデルのcapabilities.server_tools.code_execution.supportedの値を読み取ってください。この目的にはトップレベルのcapabilities.code_executionの値を使用しないでください。この値は、プログラムによるツール呼び出しのように、このツール内で実行されるコードがリクエストの他のツールを呼び出せるかどうかを示すものです。両方のフィールドについては、Models APIの使用で説明しています。

クイックスタート

以下は、Claudeに計算を実行するよう依頼する例です。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to 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"}],
)

print(response.to_json())

レスポンスでは、server_tool_useブロック（Claudeが実行したコマンド）とそのツール結果ブロックが交互に並び、その後にClaudeのテキストが続きます。トップレベルにはcontainerオブジェクトも含まれており、そのidはリクエスト間で再利用できます。ブロックの形式についてはレスポンス形式を参照してください。

コード実行の仕組み

APIリクエストにコード実行ツールを追加すると、次のようになります。

  1. Claudeは、コード実行が質問への回答に役立つかどうかを評価します
  2. ツールは自動的にClaudeに以下の機能を提供します。
    • Bashコマンド： システム操作のためのシェルコマンドを実行します
    • ファイル操作： コードの記述を含め、ファイルを直接作成、表示、編集します
  3. Claudeは、1回のリクエストでこれらの機能を任意に組み合わせて使用できます
  4. すべての操作は、安全なサンドボックス化された「container」（コンテナ）内で実行されます。コンテナにはインターネットアクセスがないため、Claudeは実行時にパッケージをダウンロードできません。利用できるのはプリインストールされたライブラリのみです
  5. APIはすべてのコマンドをサーバー側で実行し、同じリクエスト内で結果をClaudeに返すため、ユーザー自身がコードを実行したりtool_resultブロックを送り返したりする必要はありません。例外の1つは、Claudeがコード実行と並行してクライアントツールのいずれかを呼び出す場合です。この場合、APIはコード実行の呼び出しを結果なしで返します。結果は、クライアントツールのtool_resultブロックを送り返した後の、後続のレスポンスで届きます
  6. 以前のレスポンスのコンテナIDを渡さない限り、各リクエストは新しいコンテナで実行されます（コンテナの再利用を参照）
  7. Claudeは、生成されたグラフ、計算、または分析とともに結果を提供します

コンテナにはPythonがプリインストールされています。Claudeはファイル操作サブツールでPythonを記述し、Bashコマンドで実行します。code_execution_20260120以降とプログラムによるツール呼び出しを使用すると、Pythonインタープリターの状態（変数のバインディングなど）も、コンテナを再利用するリクエスト間で永続化されます。

Claudeがコードを実行するタイミング

Claudeは、計算やファイル処理がリクエストに役立つ場合にコードを実行します。

  • 自明でない数学（大きな数値、多くのステップ、精度が重要な結果）
  • データ分析、ファイルの解析、または可視化
  • アルゴリズムの実行またはシミュレーション
  • 「run」、「compute」、「execute」などの明示的な依頼

Claudeは、以下の場合にはコードを実行せずに直接回答します。

  • 単純な算術やよく知られた数学的事実
  • 事実に関する、会話的な、または創作的なリクエスト
  • 単純な単位変換や翻訳

判断が分かれるリクエストでClaudeにコードを実行させたい場合は、明示的に依頼してください（例：「これを検証するためにコードを実行してください」）。

ファイルの操作

独自のファイルをアップロードして分析する

独自のデータファイル（CSV、Excel、画像など）を分析するには、Files APIを通じてアップロードし、リクエストで参照します。

Python環境は、Files APIを通じてアップロードされたさまざまなファイルタイプを処理できます。これには以下が含まれます。

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

ファイルをアップロードして分析する

  1. Files APIを使用してファイルをアップロードします
  2. container_uploadコンテンツブロックを使用して、メッセージ内でファイルを参照します
  3. APIリクエストにコード実行ツールを含めます
client = anthropic.Anthropic()

# ファイルをアップロードします
file_object = client.files.upload(file=Path("data.csv"))

# file_id をコード実行で使用します
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())

生成されたファイルを取得する

コード実行中にClaudeが出力ディレクトリにファイルを保存すると（生成されたファイルのキャプチャ方法を参照）、各ファイルのIDがコード実行ツールの結果に表示され、Files APIでダウンロードできます。

client = Anthropic()

# ファイルを作成するコード実行をリクエストします
response = client.messages.create(
    model="claude-opus-5-5"