コード実行ツール

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

コード実行は、ウェブ検索またはウェブフェッチと併用する場合は無料です。 リクエストにweb_search_20260209（またはそれ以降）またはweb_fetch_20260209（またはそれ以降）が含まれている場合、標準の入力および出力トークンコスト以外に、コード実行ツール呼び出しに対する追加料金は発生しません。これらのツールが含まれていない場合は、標準のコード実行料金が適用されます。

コード実行は、高性能なエージェントを構築するための中核的なプリミティブです。ウェブ検索およびウェブフェッチツールでの動的フィルタリングを可能にし、Claudeが結果をコンテキストウィンドウに到達する前に処理できるようにすることで、トークン消費を削減しながら精度を向上させます。



モデルの互換性

コード実行ツールは、以下のモデルで利用可能です。



プラットフォームの利用可能性

コード実行は以下で利用可能です。

• Claude API（Anthropic）
• Claude Platform on AWS
• Microsoft Foundry

コード実行は現在、Amazon BedrockおよびVertex AIでは利用できません。



クイックスタート

Claudeに計算を実行させる簡単な例を以下に示します。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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"}],
)

print(response)



コード実行の仕組み

APIリクエストにコード実行ツールを追加すると、以下のように動作します。

1. Claudeは、コード実行が質問への回答に役立つかどうかを評価します
2. ツールは自動的にClaudeに以下の機能を提供します。
   • Bashコマンド：システム操作やパッケージ管理のためのシェルコマンドを実行
   • ファイル操作：コードの記述を含む、ファイルの作成、表示、編集を直接実行
3. Claudeは、単一のリクエスト内でこれらの機能を任意に組み合わせて使用できます
4. すべての操作は安全なサンドボックス環境で実行されます
5. Claudeは、生成されたグラフ、計算、分析とともに結果を提供します



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

Claudeは、リクエストが計算やファイル処理によって恩恵を受ける場合にコードを実行します。

• 単純ではない数学（大きな数値、多くのステップ、精度が重要な結果）
• データ分析、ファイル解析、または視覚化
• アルゴリズムの実行またはシミュレーション
• 「実行」、「計算」、「実行して」といった明示的なリクエスト

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

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

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



他の実行ツールとのコード実行の併用

コード実行を、同じくコードを実行するクライアント提供ツール（bashツールやカスタムREPLなど）と併せて提供する場合、Claudeはマルチコンピュータ環境で動作していることになります。コード実行ツールはAnthropicのサンドボックス化されたコンテナで実行され、クライアント提供ツールはユーザーが管理する別の環境で実行されます。Claudeはこれらの環境を混同し、誤ったツールを使用しようとしたり、環境間で状態が共有されていると想定したりすることがあります。

これを避けるには、システムプロンプトに区別を明確にする指示を追加してください。

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

これは、コード実行を自動的に有効にするウェブ検索やウェブフェッチと組み合わせる場合に特に重要です。アプリケーションがすでにクライアント側のシェルツールを提供している場合、自動コード実行により2つ目の実行環境が作成され、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.beta.files.upload(
    file=open("data.csv", "rb"),
)

# コード実行でfile_idを使用
response = client.beta.messages.create(
    model="claude-opus-4-8",
    betas=["files-api-2025-04-14"],
    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)



生成されたファイルの取得

Claudeがコード実行中にファイルを作成した場合、Files APIを使用してこれらのファイルを取得できます。

# クライアントを初期化
client = Anthropic()

# ファイルを作成するコード実行をリクエスト
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# レスポンスからファイルIDを抽出
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":
                # 具象型のリスト: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# 作成されたファイルをダウンロード
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}")



ツール定義

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

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

このツールが提供されると、Claudeは自動的に2つのサブツールにアクセスできるようになります。

• bash_code_execution：シェルコマンドを実行
• text_editor_code_execution：コードの記述を含む、ファイルの表示、作成、編集



レスポンス形式

コード実行ツールは、操作に応じて2種類の結果を返すことができます。



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



ファイル操作のレスポンス

ファイルの表示：

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

ファイルの作成：

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

ファイルの編集（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"]
  }
}



結果

すべての実行結果には以下が含まれます。

• stdout：正常な実行からの出力
• stderr：実行が失敗した場合のエラーメッセージ
• return_code：成功の場合は0、失敗の場合は0以外

ファイル操作の追加フィールド：

• 表示：file_type、content、numLines、startLine、totalLines
• 作成：is_file_update（ファイルがすでに存在していたかどうか）
• 編集：oldStart、oldLines、newStart、newLines、lines（diff形式）



エラー

各ツールタイプは特定のエラーを返すことがあります。

共通エラー（すべてのツール）：

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

ツールタイプ別のエラーコード：



pause_turn停止理由

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



コンテナ

コード実行ツールは、コード実行専用に設計された安全なコンテナ化環境で実行され、特にPythonに重点が置かれています。



ランタイム環境

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



リソース制限

• メモリ：5GiB RAM
• ディスク容量：5GiBのワークスペースストレージ
• CPU：1 CPU



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

• インターネットアクセス：セキュリティのため完全に無効化
• 外部接続：アウトバウンドネットワークリクエストは許可されません
• サンドボックス分離：ホストシステムおよび他のコンテナから完全に分離
• ファイルアクセス：ワークスペースディレクトリのみに制限
• ワークスペースのスコープ：Filesと同様に、コンテナはAPIキーのワークスペースにスコープされます
• 有効期限：コンテナは作成から30日後に期限切れになります



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

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

• データサイエンス：pandas、numpy、scipy、scikit-learn、statsmodels
• 視覚化：matplotlib、seaborn
• ファイル処理：pyarrow、openpyxl、xlsxwriter、xlrd、pillow、python-pptx、python-docx、pypdf、pdfplumber、pypdfium2、pdf2image、pdfkit、tabula-py、reportlab[pycairo]、Img2pdf
• 数学・計算：sympy、mpmath
• ユーティリティ：tqdm、python-dateutil、pytz、joblib、unzip、unrar、7zip、bc、rg（ripgrep）、fd、sqlite



コンテナの再利用

以前のレスポンスからコンテナIDを提供することで、複数のAPIリクエスト間で既存のコンテナを再利用できます。これにより、リクエスト間で作成されたファイルを維持できます。



例

# 最初のリクエスト：ランダムな数値を含むファイルを作成
response1 = client.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# 最初のレスポンスからコンテナIDを抽出
container_id = response1.container.id

# 2番目のリクエスト：コンテナを再利用してファイルを読み取る
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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"}],
)

print(response2)



ストリーミング

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

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



バッチリクエスト

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



使用量と料金

コード実行は、ウェブ検索またはウェブ取得と併用する場合は無料です。 APIリクエストに web_search_20260209（またはそれ以降）もしくは web_fetch_20260209（またはそれ以降）が含まれている場合、標準の入力および出力トークンコスト以外に、コード実行ツール呼び出しに対する追加料金は発生しません。

これらのツールを使用せずにコード実行を利用する場合、トークン使用量とは別に追跡される実行時間に基づいて課金されます。

• 実行時間には最低5分が適用されます
• 各組織には月あたり1,550時間の無料利用枠が付与されます
• 1,550時間を超える追加利用分は、コンテナごとに1時間あたり$0.05で課金されます
• リクエストにファイルが含まれている場合、ファイルがコンテナに事前ロードされるため、ツールが呼び出されなくても実行時間が課金されます

コード実行の使用状況はレスポンスで追跡されます。

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



最新のツールバージョンへのアップグレード

code-execution-2025-08-25にアップグレードすることで、複数の言語でのコードを含む、ファイル操作とBash機能にアクセスできるようになります。料金に違いはありません。



変更点



後方互換性

• 既存のすべてのPythonコード実行は、これまでとまったく同じように動作し続けます
• 既存のPythonのみのワークフローに変更は必要ありません



アップグレード手順

アップグレードするには、APIリクエストのツールタイプを更新します。

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

レスポンス処理の確認（プログラムでレスポンスを解析している場合）：

• Python実行レスポンスの以前のブロックは送信されなくなります
• 代わりに、Bashおよびファイル操作用の新しいレスポンスタイプが送信されます（レスポンス形式セクションを参照）



プログラマティックツール呼び出し

コード実行コンテナ内でツールを実行する方法については、プログラマティックツール呼び出しを参照してください。



データ保持

コード実行はサーバー側のサンドボックスコンテナで実行されます。実行アーティファクト、アップロードされたファイル、出力を含むコンテナデータは、最大30日間保持されます。この保持期間は、コンテナ環境内で処理されるすべてのデータに適用されます。コード実行がFiles APIに作成するファイル（client.beta.files.download()で取得可能）は、明示的に削除されるまで保持されます。

すべての機能におけるZDR適格性については、APIとデータ保持を参照してください。



Agent Skillsとのコード実行の併用

コード実行ツールにより、ClaudeはAgent Skillsを使用できるようになります。スキルは、Claudeの機能を拡張する指示、スクリプト、リソースで構成されるモジュール式の機能です。

詳細については、Agent SkillsおよびAPIでのAgent Skillsの使用を参照してください。