Code execution tool

原典: Code execution tool ／ 日本語版

一行要約

Anthropic 側のコンテナで Python と bash を走らせるサーバツール。 インターネットは無く、生成物は $OUTPUT_DIR に置いたものしか返らず、web search / web fetch（web_search_20260209 / web_fetch_20260209 以降）と一緒に使うときは無料。

要点

実行はサーバ側で完結する

The API runs every command server-side and returns the results to Claude within the same request, so you never execute code or send back tool_result blocks yourself.

API はすべてのコマンドをサーバ側で実行し、同じリクエストの中で Claude に結果を返す。だから自分でコードを実行したり tool_result ブロックを返したりすることは無い。

例外が1つある。自分のクライアントツールを code execution と並べて呼んだ場合、code execution の呼び出しは結果なしで返り、こちらが tool_result を返した後の応答で結果が届く。

使える場所: Claude API と Claude Platform on AWS。Amazon Bedrock と Google Cloud では使えず、Microsoft Foundry では Hosted on Anthropic のデプロイが要る。

Claude がコードを走らせるのは計算やファイル処理が効くとき（自明でない数学、データ分析・パース・可視化、アルゴリズムやシミュレーション、「run / compute / execute」と頼まれたとき）。簡単な算術や事実・会話・創作の依頼では走らせずに答える。境界の依頼で走らせたいなら明示的に頼む（「run code to verify this」）。

ツール定義は2フィールドだけで、Claude には自動的に2つのサブツール（bash_code_execution と text_editor_code_execution）が生える。

バージョンが3つあり、上位互換

type	加わるもの
code_execution_20250825	bash コマンドとファイル操作
code_execution_20260120	REPL 状態の保持と、サンドボックス内からの programmatic-tool-calling
code_execution_20260521	ランタイムは同じ。programmatic tool calling での Python セル1つあたり 90 秒という壁時計制限を、ツール説明で Claude に知らせる

90 秒を超えたセルはエラーではなく通常の結果として返り、return_code が非ゼロ、出力に detection_timeout が入る。 ツール呼び出し全体が上限を超えたときの execution_time_exceeded エラーとは別物。

どれも anthropic-beta ヘッダを要らない。 ただし現行の web search / web fetch（web_search_20260209 以降）は code_execution_20260120 以降を要求する。

Haiku 4.5 は3つとも受け付けるが、programmatic tool calling とそれに依存する REPL 状態保持が使えないので、新しい type を渡しても code_execution_20250825 と同じ振る舞いになる。

コンテナ —— 何が無いか

Internet access: Completely disabled for security

インターネットアクセス: セキュリティのため完全に無効

The container has no internet access, so Claude can’t download or install additional packages at runtime: only the pre-installed libraries are available.

コンテナにはインターネットが無いので、Claude は実行時に追加パッケージをダウンロードもインストールもできない。あらかじめ入っているライブラリだけが使える。

Python 3.11 / メモリ 5 GiB / ディスク 5 GiB / CPU 1。pandas・numpy・scipy・scikit-learn・matplotlib・pypdf・python-docx などが同梱され、rg・fd・sqlite・unzip のようなコマンドも入っている。作れるものは、この一覧の中で作れるものに限られる。

生成ファイルは $OUTPUT_DIR に置いたものだけが返る

Each bash_code_execution call gets a new, empty directory, available to the command as $OUTPUT_DIR. When the command finishes, the files at the top level of that directory are captured and returned as the file_id entries in the result’s content list. Files written anywhere else stay in the container and aren’t returned.

bash_code_execution の呼び出しごとに新しい空のディレクトリが用意され、コマンドからは $OUTPUT_DIR として見える。コマンドが終わると、そのディレクトリ直下のファイルが回収され、結果の content に file_id として返る。それ以外の場所に書いたファイルはコンテナに残るだけで返らない。

しかも Claude 自身は content の一覧を見られない（原典の括弧書き: “Claude doesn’t see the content list”）。だから確実に受け取りたいなら、同じコマンドの中で $OUTPUT_DIR にコピーして ls させ、その出力で確認するというのが原典の指示になる。取りこぼしても、コンテナを再利用して「コピーして」と頼めば拾える。

課金 —— トークンではなく実行時間

Code execution is free when used with web search or web fetch.

web search や web fetch と一緒に使うとき、code execution は無料。

対象は web_search_20260209 / web_fetch_20260209 以降で、それより古い web search と併用しても無料にはならない。

単独で使うときは実行時間で課金される。最低 5 分、組織ごとに毎月 1,550 時間が無料枠、超過はコンテナあたり 1 時間 $0.05 USD。

If files are included in the request, execution time is billed even if the tool is not called, because files are preloaded onto the container

リクエストにファイルが含まれていれば、ツールが呼ばれなくても実行時間は課金される。 ファイルがコンテナに先読みされるため。

コンテナ再利用の時間感覚が3つある

Containers expire 30 days after creation. After about 5 minutes of inactivity a container is checkpointed, and sending a request with its ID inside the 30-day window restores it. The expires_at timestamp in the response’s container object is a shorter rolling value and doesn’t report the 30-day limit.

コンテナは作成から30日で失効する。約5分間の無操作でチェックポイントされ、30日以内なら ID を渡したリクエストで復元される。応答の container にある expires_at はもっと短いローリング値で、30日の期限を表しているのではない。

失効したコンテナは再利用できない。 container を外して投げ直すと新しいものが取れる。

実行環境が2つあると Claude は混ざる

Claude can sometimes confuse these environments, attempting to use the wrong tool or assuming state is shared between them.

Claude はこの2つの環境を取り違えることがある。誤ったツールを使おうとしたり、状態が共有されていると思い込んだりする。

自前の bash ツールや REPL を持たせている場合に起きる。web search / web fetch は code execution を自動で有効にするので、意図せず2つ目の実行環境が生えるのが厄介なところ。原典は system プロンプトで区別を明示せよと言い、その文面を載せている（下記）。

生成した画像・動画・音声には C2PA の Content Credentials が付く

The manifest adds a few kilobytes, so the downloaded file’s size and checksum differ from the file as it exists inside the container.

マニフェストが数キロバイト足すので、ダウンロードしたファイルのサイズとチェックサムは、コンテナの中にあるファイルとは一致しない。

Re-encoding, format conversion, screenshots, and tools that strip metadata remove the credential, so a missing credential doesn’t mean a file wasn’t produced with Claude.

再エンコード・形式変換・スクリーンショット・メタデータを落とすツールは Content Credentials を消す。Content Credentials が無いことは、そのファイルが Claude 製でないことを意味しない。

Claude API で Files API からダウンロードしたときに付き、対象は PNG・JPEG・MP4・MP3・WAV などの画像・動画・音声（以前の取得の後に音声の形式が加わった。その後の控えにすでにある）。テキスト・PDF・オフィス文書は署名されない。

そのまま使える具体例

実行環境が複数あるときの system プロンプト（原典そのまま）:

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

生成物を確実に回収させる言い回し:

python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"

ツール定義:

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

エラーコード: unavailable / execution_time_exceeded / invalid_tool_input / too_many_requests（全ツール共通）、output_file_too_large（bash）、file_not_found（text_editor）。長いターンでは pause_turn が返るので、応答をそのまま送り返すと続きを実行する。

原典で言及されている関連文書

• programmatic-tool-calling — code_execution_20260120 以降で使える。REPL 状態の保持もこれに依存する
• improved-web-search-with-dynamic-filtering — 原典が指すのは web search ツールの文書だが、dynamic filtering が code execution の上で動くという話はこちらに詳しい