コード実行ツール

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

コード実行ツールは現在パブリックベータ版です。

この機能を使用するには、APIリクエストに"code-execution-2025-08-25" ベータヘッダーを追加してください。

最近、Bashコマンドと直接的なファイル操作をサポートするためにコード実行ツールをアップグレードしました。最新のツールバージョンへのアップグレード手順については、最新ツールバージョンへのアップグレードを参照してください。

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

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

Claude Opus 4.1 (claude-opus-4-1-20250805)
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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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"
        }]
    }'

コード実行の仕組み

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

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

ツールの使用方法

Bashコマンドの実行

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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

ファイルの直接作成と編集

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-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

独自のファイルのアップロードと分析

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

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

Python環境は、Files API経由でアップロードされた様々なファイルタイプを処理できます：

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

ファイルのアップロードと分析

Files APIを使用してファイルをアップロード
container_uploadコンテンツブロックを使用してメッセージでファイルを参照
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-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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_20250825",
            "name": "code_execution"
        }]
    }'

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

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

from anthropic import Anthropic

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

# ファイルを作成するコード実行をリクエスト
response = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25", "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.get('type') == 'code_execution_result':
                for file in content_item.get('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}")

操作の組み合わせ

すべての機能を使用する複雑なワークフロー：

# まず、ファイルをアップロード
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_response.json

# file_idを抽出（jqを使用）
FILE_ID=$(jq -r '.id' file_response.json)

# 次に、コード実行と一緒に使用
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-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
                },
                {
                    "type": "container_upload", 
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

ツール定義

コード実行ツールは追加のパラメータを必要としません：

JSON
{
  "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、失敗の場合は非ゼロ

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

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

ツールタイプ別エラーコード:

ツール	エラーコード	説明
すべてのツール	`unavailable`	ツールが一時的に利用できません
すべてのツール	`execution_time_exceeded`	実行が最大時間制限を超えました
すべてのツール	`container_expired`	コンテナが期限切れで利用できません
すべてのツール	`invalid_tool_input`	ツールに無効なパラメータが提供されました
すべてのツール	`too_many_requests`	ツール使用のレート制限を超えました
text_editor	`file_not_found`	ファイルが存在しません（表示/編集操作の場合）
text_editor	`string_not_found`	`old_str`がファイル内で見つかりません（str_replaceの場合）

`pause_turn` 停止理由

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

コンテナ

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

ランタイム環境

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

リソース制限

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

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

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

プリインストールライブラリ

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

データサイエンス: pandas, numpy, scipy, scikit-learn, statsmodels
視覚化: matplotlib, seaborn
ファイル処理: pyarrow, openpyxl, 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リクエスト間で既存のコンテナを再利用できます。これにより、リクエスト間で作成されたファイルを維持できます。

例

import os
from anthropic import Anthropic

# クライアントを初期化
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# 最初のリクエスト: ランダムな数値でファイルを作成
response1 = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    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.beta.messages.create(
    container=container_id,  # 同じコンテナを再利用
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

ストリーミング

ストリーミングが有効になっている場合、コード実行イベントが発生するたびに受信されます：

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リクエストと同じ価格で提供されます。

使用方法と価格

The code execution tool usage is tracked separately from token usage. Execution time is a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container.

Pricing: $0.05 per session-hour.

コンポーネント	レガシー	現在
ベータヘッダー	`code-execution-2025-05-22`	`code-execution-2025-08-25`
ツールタイプ	`code_execution_20250522`	`code_execution_20250825`
機能	Pythonのみ	Bashコマンド、ファイル操作
レスポンスタイプ	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_result`

はじめの手順

モデルと料金

Claudeについて学ぶ

機能

ツール

Model Context Protocol (MCP)

使用例

プロンプトエンジニアリング

テスト・評価

ガードレールを強化

法的センター

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

​クイックスタート

​コード実行の仕組み

​ツールの使用方法

​Bashコマンドの実行

​ファイルの直接作成と編集

​独自のファイルのアップロードと分析

​ファイルのアップロードと分析

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

​操作の組み合わせ

​ツール定義

​レスポンス形式

​Bashコマンドレスポンス

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

​結果

​エラー

​pause_turn 停止理由

​コンテナ

​ランタイム環境

​リソース制限

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

​プリインストールライブラリ

​コンテナの再利用

​例

​ストリーミング

​バッチリクエスト

​使用方法と価格

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

​変更点

​後方互換性

​アップグレード手順

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

クイックスタート

コード実行の仕組み

ツールの使用方法

Bashコマンドの実行

ファイルの直接作成と編集

独自のファイルのアップロードと分析

ファイルのアップロードと分析

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

操作の組み合わせ

ツール定義

レスポンス形式

Bashコマンドレスポンス

ファイル操作レスポンス

結果

エラー

`pause_turn` 停止理由

コンテナ

ランタイム環境

リソース制限

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

プリインストールライブラリ

コンテナの再利用

例

ストリーミング

バッチリクエスト

使用方法と価格

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

変更点

後方互換性

アップグレード手順