Code execution 與 Files API

TL;DR

• Code execution：server-side Python sandbox（Docker 容器），Claude 自己寫 code 自己跑——回 stdout、stderr、產生的圖檔；沒網路、CPU/記憶體有上限
• Files API：把檔案上傳一次拿 file_id，之後在 messages 裡 reference 不用再傳 base64 bytes
• 兩個一起用：上傳 CSV → container_upload block 讓 sandbox 拿到檔 → Claude 寫 pandas 跑分析 → 產 PNG 圖檔，你再 download 回來

一個情境：「分析這份 churn 資料」

PM 丟你一個 streaming.csv：50 個欄位、5 萬列、最後一欄 churned 是 0/1。「找出哪些 feature 跟 churn 最相關，畫個 chart 給我。」

過去要這樣：

1. 你寫 prompt 叫 Claude 教你怎麼分析
2. Claude 給一段 pandas code
3. 你自己跑 code、貼結果回去
4. Claude 看結果再建議下一步⋯⋯
5. 反覆 3–5 輪

慢、煩、來回上下文很多。

Code execution 把 step 2–3 收進 server。你給 prompt + 檔案，Claude 自己寫 code 自己跑，多次迭代後直接給你帶圖表的分析報告。

Files API：上傳一次、到處 reference

傳統做法把檔案 base64 後塞進每個 request 的 content——同一份檔案 multi-turn 用 5 次就重傳 5 次 bytes，浪費頻寬。

Files API 把這拆兩步：

# 1. 上傳一次（獨立 endpoint）
file_meta = client.beta.files.upload(file=open("streaming.csv", "rb"))
print(file_meta.id)
# → "file_abc123..."

# 2. 後續 messages 用 file_id reference
messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "分析這份 churn data"},
        {"type": "container_upload", "file_id": file_meta.id},
    ],
}]

支援 image / PDF / text / CSV / 任何 binary。

操作	計費
上傳	免費
儲存	有保留期，過了會刪
Reference	跟原本傳 bytes 算一樣的 token（重點是省你頻寬，不是省 token）

Code execution tool

跟 self-hosted tool 不同——code execution 是 server-side built-in tool，你不用寫 implementation，只要在 tools 陣列加 schema：

res = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
    messages=messages,
)

type 字串裡的日期是 tool 的 versioning，未來新版會換編號——以當前 docs 為準。

Sandbox 的限制

限制	內容
執行環境	隔離 Docker 容器，每次 request 開新的
語言	Python（含 numpy、pandas、matplotlib 等常用 lib）
網路	完全沒有——requests.get(...) 直接 fail
CPU / 記憶體	有上限——大 dataset 跑 ML training 會 OOM
持久化	本次 request 結束後容器銷毀；要存東西要透過 Files API 取出來

「沒網路」是最常被誤解的點：很多分析任務的下意識寫法是 pd.read_csv("https://...")，在這 sandbox 直接 fail。所有要進 container 的資料都得走 Files API → container_upload block。

完整流程：CSV 分析

# 1. 上傳檔案
file_meta = client.beta.files.upload(file=open("streaming.csv", "rb"))

# 2. 包成 message：text prompt + container_upload block
messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": """
分析使用者 churn 主要驅動因子。
你的最終 output 必須包含至少一張綜合圖表（可用 matplotlib 存成 PNG）。
"""},
        {"type": "container_upload", "file_id": file_meta.id},
    ],
}]

# 3. 開 code execution tool
res = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
    messages=messages,
)

Response 長什麼樣

res.content 會混合好幾種 block——Claude 可能多次 run code 迭代：

Block type	內容
text	Claude 的解說
server_tool_use	Claude 決定要跑的 code 字串
code_execution_tool_result	stdout / stderr / return_code，可能含 file_id（產出的圖檔）

順序大致是 text → server_tool_use → tool_result → text → server_tool_use → ... 反覆迭代，最後產出包含圖檔的 tool_result。

把 sandbox 產出的圖載回來

最後一塊 code_execution_tool_result 裡面常會夾 file_id——那是 Claude 在 sandbox 裡 savefig 的圖檔。透過 Files API 下載：

content = client.beta.files.download(file_id="file_xyz")
with open("churn_analysis.png", "wb") as f:
    f.write(content.read())

開啟看圖，常常會直接看到 4–6 個 subplot 的綜合圖表——subscription tier vs churn、viewing hours vs churn、price tier vs churn 之類，不用你自己 plot 一張一張。

何時用、何時不用

場景	適合？
一次性資料分析、產 chart	適合
Math / 統計計算	適合（避免 LLM 算錯）
抓資料分析（要打 API）	不適合——sandbox 沒網路
大規模 ETL / 1GB+ 資料	不適合——記憶體爆
Production cron job 跑 SQL	不適合——用你自己的 worker
Image 後處理、PDF 抽欄位	適合（搭配 Files API 上傳）

計費怎麼算

Code execution 是 tool use 計費——除了 input/output token，code 跑的時間 另外算（按 sandbox 用量）。Files API 上傳免費、儲存到期會刪。

具體費率請查當前 pricing 頁面——code execution 的部分跟一般 tool use 略有不同。

何時用 Files API（不一定要配 code execution）

Files API 不是只能跟 code execution 搭——任何 multi-turn 場景對同一份大檔反覆問問題，用 file_id 都比 base64 重傳省事：

# 上傳一次
file_meta = client.beta.files.upload(file=open("big-pdf.pdf", "rb"))

# turn 1
content = [{"type": "document", "source": {"type": "file", "file_id": file_meta.id}},
           {"type": "text", "text": "違約金條款？"}]

# turn 2、3、4⋯ 同樣 reference file_id，不用重傳

跟 prompt caching 搭起來最完整：file_id reference 省頻寬、cache_control 省 token。

接下來

Section 6 結束——Claude 的進階能力都摸過一輪。下一章換主題到 MCP：Anthropic API 怎麼直接掛遠端 MCP server，不用自己包 tool schema。