やす研究所 AI Lab
戻る

Claude Code Execution Tool実践2026:Pythonをサンドボックスで走らせる実装手順

Claude Code Execution Tool実践2026:Pythonをサンドボックスで走らせる実装手順

「Claude に CSV を渡して集計させたいけど、自前でサンドボックス組むのが面倒」——私も同じところで詰まっていました。

そこで先週、Anthropic の Code Execution tool を本番の API エージェントに組み込んでみたら、想像以上に楽で拍子抜けするほどでした。Python も Bash も動く、ファイルも吐ける、しかも Web Search と併用なら実行料金が無料。

この記事では、2026年7月時点の最新版(code_execution_20260521)を前提に、最小コード・料金の落とし穴・Bedrock 非対応まで、実際に触って詰まったポイントを共有します。

結論:Claude Code Execution Toolは「自前サンドボックス」を捨てる選択肢

先に結論から言います。

もしあなたが今、Claude API のエージェントに「Python を実行させる」ために自前で Docker サンドボックスを組んでいるなら、Code Execution tool に置き換えるだけで、その配管の8割は捨てられます。

私が置き換えて感じた実利はこの3つでした。

ただし、Amazon Bedrock と Google Vertex AI では動きません。ここは後述しますが、マルチクラウド前提の設計だと詰みます。

Claude Code Execution Toolの仕組みと3つのバージョン

Code Execution tool は、Claude が Bash コマンドやファイル操作、Python コードを サンドボックス内で直接実行できる組み込みツールです。会話 API のリクエストに tools として指定するだけで有効になります。

Anthropic の公式ドキュメントによると、このサンドボックスは gVisor で隔離された環境で動き、Python の REPL と Bash が使えます。外部ネットワークはデフォルトで遮断されており、pandas / numpy / matplotlib などのデータ分析系ライブラリは最初から入っています。

2026年7月時点で使えるバージョンは3系統あります。

code_execution_20250825(初代)

最初にリリースされた版。Bash コマンドとファイル操作がメイン。全モデルで使えますが、REPL の状態は毎回リセットされます。

code_execution_20260120(REPL永続化)

2026年1月に追加されたバージョン。REPL state persistence と programmatic tool calling(サンドボックスの中から別のツールを呼べる)が入りました。これが実務で効きます。

たとえば「CSV を読み込む → 途中で Web 検索で辞書を引く → 結果をマージする」みたいな多段処理が、変数を再ロードせずに流せる。地味だけどコストに直結する変更でした。

ただし注意点として、Haiku 4.5 ではこのバージョンを指定できても、内部的には旧仕様と同じ挙動になります。programmatic tool calling は Sonnet / Opus 系だけです。

code_execution_20260521(最新)

2026年5月版。細かい安定化と Web Fetch との連携強化が入っています。新規プロジェクトはこれで始めるのが無難。

最小実装:Python 20行でCSV集計エージェントを作る

実際に動かしたコードを載せます。ローカルの CSV を Files API 経由で渡して、Claude に集計させる例です。

import anthropic

client = anthropic.Anthropic()

# 事前に Files API でアップロード済みの file_id を想定
file_id = "file_abc123"

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    tools=[{
        "type": "code_execution_20260521",
        "name": "code_execution"
    }],
    betas=["code-execution-2026-05-21", "files-api-2025-04-14"],
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "添付CSVを月次売上で集計し、上位5社を棒グラフで出して"},
            {"type": "container_upload", "file_id": file_id}
        ]
    }]
)

print(response.content)

ポイントは container_upload で Files API の file_id をそのまま渡せること。ファイルの中身をトークン化して詰め込む必要がありません。

実行後、Claude はサンドボックス内で pandas を呼び出し、matplotlib で PNG を吐きます。生成された画像は file_id として response に含まれ、そのまま次のターンで再利用できます。

Web Search 併用で料金がタダになる仕様を活用する

これは公式ドキュメントで明記されていて、実際にダッシュボードで確認したので間違いありません。

Code Execution が web_search_20260209 / web_fetch_20260209 以降のツールと同一リクエストで使われる場合、code execution の追加料金は発生しない。標準のトークン課金だけです。

背景としては、Web Search の結果が context window に入る前に、Claude がサンドボックス内で「必要な部分だけ抜き出す」動的フィルタリングをする設計になっているからです。要するに、Anthropic 側にとってもトークン節約になるので、無料で開放している。

私はこれを知ってから、リサーチ系のエージェントは全部 web_search + code_execution セットで組むようにしました。ノイズ削減とコスト削減が同時に効く、地味ですが年間で見ると効く改善です。

逆に、code execution 単体で使うとちゃんと課金されます。ここは請求書で二度見しないよう覚えておいてください。

本番で踏んだ落とし穴3つ

1. Bedrock / Vertex AI では動かない

これが一番痛かった。Team 400 の技術記事にもある通り、Code Execution は Anthropic 直 API と Microsoft Azure AI Foundry のみ対応で、Amazon Bedrock と Google Vertex AI では利用不可です。

私が組んでいたエージェントは Bedrock 前提だったので、この機能のためだけに一部を Anthropic 直 API に分離しました。マルチクラウド戦略と Code Execution は相性が悪い、と覚えておくと設計時に迷いません。

2. サンドボックスに外部ネットワークが無い

デフォルトで外向き通信が遮断されているので、サンドボックス内から pip install はできません。事前インストール済みのライブラリ(pandas / numpy / matplotlib / scikit-learn など)以外を使いたい場合は、programmatic tool calling で外側のツール経由にする必要があります。

「Claude に requests でスクレイピングさせよう」と思っても弾かれます。ここは Web Fetch tool を組み合わせて回避するのが定石です。

3. ストレージ 100GB の上限とセキュリティ

ワークスペースのファイル総量には 100GB の上限があります。長期運用するエージェントで生成ファイルを削除しないと、じわじわ溜まって上限に達します。

そして 2026年初頭に The Register が報じた通り、Code Execution 経由での API キー漏洩や workspace 汚染の脆弱性が過去に報告されています。Anthropic は即座に修正済みですが、本番運用では API キーの権限最小化と、workspace 内容の定期監査を必ず入れてください。私は .claude/ 配下と別に、日次で workspace の一覧を CloudWatch に流しています。

Claude Code の Bash tool との使い分け

混乱しがちなのが「Claude Code(CLI)にも Bash tool あるじゃん、何が違うの?」というポイント。

ざっくり整理するとこうです。

本番の Web サービスに組み込むエージェントなら、間違いなく Code Execution 一択です。ユーザーのマシンでコードを走らせるわけにはいかないので。

逆に、あなた自身の開発ループを回すなら Claude Code の Bash が速い。使い分けの判断軸は「実行環境を誰が所有しているか」だけで、思ったよりシンプルです。

まとめ:今日からやる3つのアクション

長くなったので、この記事を閉じたら実行できることを3つだけ。

  1. 手元の API エージェントで、自前サンドボックスを持っている部分を洗い出す。Docker + subprocess でコードを走らせている箇所があれば、置き換え候補です
  2. Web Search を使っているリクエストに code_execution_20260521 を追加する。追加料金なしで結果の質が上がります。まずは1本のエンドポイントで A/B して効果を計測してください
  3. Bedrock / Vertex 依存の設計を見直す。Code Execution を使いたいなら、その部分だけ Anthropic 直 API に分岐する構成が現実解です

私はこの置き換えで、CSV 分析系エージェントの実装コードを半分以下に圧縮できました。サンドボックス周りの配管って、書くのは面白くない割にバグの温床になりがちなので、公式に任せられるならそれが一番です。

あなたのエージェントも、たぶん一番地味な部分をまるっと預けられるはずです。

参考リンク

この記事をシェア:
X で共有 Facebook で共有 Telegram で共有
次の記事
Claude API副業でAI受託の粗利を守る方法2026|バッチ推論とキャッシュで原価70%削る設計図