工具

程式碼執行工具

Claude 可以在 API 對話中直接分析資料、建立視覺化圖表、執行複雜計算、運行系統命令、建立和編輯檔案，以及處理上傳的檔案。程式碼執行工具允許 Claude 在安全的沙箱環境中運行 Bash 命令和操作檔案，包括撰寫程式碼。

當與網路搜尋或網頁擷取一起使用時，程式碼執行是免費的。 當您的請求中包含 web_search_20260209 或 web_fetch_20260209 時，除了標準的輸入和輸出 token 費用外，程式碼執行工具呼叫不會產生額外費用。當未包含這些工具時，將適用標準的程式碼執行費用。

程式碼執行是建構高效能代理的核心基礎元件。它能為網路搜尋和網頁擷取工具啟用動態過濾，讓 Claude 在結果進入上下文視窗之前先行處理——在減少 token 消耗的同時提高準確性。

請透過我們的意見回饋表單分享您對此功能的回饋。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

模型相容性

程式碼執行工具可在以下模型上使用：

模型	工具版本
Claude Opus 4.6 (`claude-opus-4-6`)	`code_execution_20250825`
Claude Sonnet 4.6 (`claude-sonnet-4-6`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`code_execution_20250825`
Claude Opus 4.1 (`claude-opus-4-1-20250805`)	`code_execution_20250825`
Claude Opus 4 (`claude-opus-4-20250514`)	`code_execution_20250825`
Claude Sonnet 4 (`claude-sonnet-4-20250514`)	`code_execution_20250825`
Claude Sonnet 3.7 (`claude-3-7-sonnet-20250219`) (已棄用)	`code_execution_20250825`
Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)	`code_execution_20250825`
Claude Haiku 3.5 (`claude-3-5-haiku-latest`) (已棄用)	`code_execution_20250825`

目前版本 code_execution_20250825 支援 Bash 命令和檔案操作。舊版 code_execution_20250522（僅限 Python）也仍可使用。請參閱升級至最新工具版本了解遷移詳情。

舊版工具版本不保證與較新模型向後相容。請始終使用與您的模型版本對應的工具版本。

平台可用性

程式碼執行可在以下平台使用：

Claude API (Anthropic)
Microsoft Azure AI Foundry

程式碼執行目前不適用於 Amazon Bedrock 或 Google Vertex AI。

快速開始

以下是一個要求 Claude 執行計算的簡單範例：

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 命令：執行 shell 命令以進行系統操作和套件管理
- 檔案操作：直接建立、檢視和編輯檔案，包括撰寫程式碼
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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 與程式碼執行一起使用需要 Files API beta 標頭："anthropic-beta": "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 請求中包含程式碼執行工具

# First, upload a file
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"' \

# Then use the file_id with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Extract file IDs from the response
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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids


# Download the created files
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}")

組合操作

使用所有功能的複雜工作流程：

# First, upload a file
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

# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Then use it with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 會自動獲得兩個子工具的存取權限：

bash_code_execution：運行 shell 命令
text_editor_code_execution：檢視、建立和編輯檔案，包括撰寫程式碼

回應格式

程式碼執行工具可以根據操作返回兩種類型的結果：

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（差異格式）

錯誤

每種工具類型可以返回特定的錯誤：

通用錯誤（所有工具）：

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

資源限制

記憶體：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 請求之間重複使用現有容器。這允許您在請求之間維護已建立的檔案。

範例

import os
from anthropic import Anthropic

# Initialize the client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# First request: Create a file with a random number
response1 = client.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-6",
    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"}}

// 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 請求中的相同。

使用量與定價

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

Execution time has a minimum of 5 minutes
Each organization receives 1,550 free hours of usage per month
Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

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

升級至最新工具版本

透過升級至 code-execution-2025-08-25，您可以獲得檔案操作和 Bash 功能的存取權限，包括多種語言的程式碼。價格沒有差異。

變更內容

元件	舊版	目前版本
Beta 標頭	`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`

向後相容性

所有現有的 Python 程式碼執行繼續完全如前運作
現有的僅限 Python 工作流程無需任何變更

升級步驟

要升級，請更新 API 請求中的工具類型：

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

檢查回應處理（如果以程式方式解析回應）：

先前用於 Python 執行回應的區塊將不再發送
取而代之的是，將發送 Bash 和檔案操作的新回應類型（請參閱回應格式章節）

程式化工具呼叫

程式碼執行工具支援程式化工具呼叫，允許 Claude 在執行容器中撰寫程式碼來以程式方式呼叫您的自訂工具。這能實現高效的多工具工作流程、在資料到達 Claude 上下文之前進行過濾，以及複雜的條件邏輯。

Python

# Enable programmatic calling for your tools
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Get weather for 5 cities and find the warmest"}
    ],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "input_schema": {...},
            "allowed_callers": [
                "code_execution_20250825"
            ],  # Enable programmatic calling
        },
    ],
)

在程式化工具呼叫文件中了解更多。

將程式碼執行與 Agent Skills 搭配使用

程式碼執行工具使 Claude 能夠使用 Agent Skills。Skills 是由指令、腳本和資源組成的模組化功能，可擴展 Claude 的能力。

在 Agent Skills 文件和 Agent Skills API 指南中了解更多。

Was this page helpful?

工具

程式碼執行工具

請透過我們的意見回饋表單分享您對此功能的回饋。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

模型相容性

程式碼執行工具可在以下模型上使用：

模型	工具版本
Claude Opus 4.6 (`claude-opus-4-6`)	`code_execution_20250825`
Claude Sonnet 4.6 (`claude-sonnet-4-6`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`code_execution_20250825`
Claude Opus 4.1 (`claude-opus-4-1-20250805`)	`code_execution_20250825`
Claude Opus 4 (`claude-opus-4-20250514`)	`code_execution_20250825`
Claude Sonnet 4 (`claude-sonnet-4-20250514`)	`code_execution_20250825`
Claude Sonnet 3.7 (`claude-3-7-sonnet-20250219`) (已棄用)	`code_execution_20250825`
Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)	`code_execution_20250825`
Claude Haiku 3.5 (`claude-3-5-haiku-latest`) (已棄用)	`code_execution_20250825`

舊版工具版本不保證與較新模型向後相容。請始終使用與您的模型版本對應的工具版本。

平台可用性

程式碼執行可在以下平台使用：

Claude API (Anthropic)
Microsoft Azure AI Foundry

程式碼執行目前不適用於 Amazon Bedrock 或 Google Vertex AI。

快速開始

以下是一個要求 Claude 執行計算的簡單範例：

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 命令：執行 shell 命令以進行系統操作和套件管理
- 檔案操作：直接建立、檢視和編輯檔案，包括撰寫程式碼
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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 與程式碼執行一起使用需要 Files API beta 標頭："anthropic-beta": "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 請求中包含程式碼執行工具

# First, upload a file
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"' \

# Then use the file_id with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Extract file IDs from the response
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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids


# Download the created files
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}")

組合操作

使用所有功能的複雜工作流程：

# First, upload a file
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

# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Then use it with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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 會自動獲得兩個子工具的存取權限：

bash_code_execution：運行 shell 命令
text_editor_code_execution：檢視、建立和編輯檔案，包括撰寫程式碼

回應格式

程式碼執行工具可以根據操作返回兩種類型的結果：

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（差異格式）

錯誤

每種工具類型可以返回特定的錯誤：

通用錯誤（所有工具）：

{
  "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` 停止原因

容器

程式碼執行工具在專為程式碼執行設計的安全容器化環境中運行，特別著重於 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 請求之間重複使用現有容器。這允許您在請求之間維護已建立的檔案。

範例

import os
from anthropic import Anthropic

# Initialize the client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# First request: Create a file with a random number
response1 = client.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-6",
    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"}}

// 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 請求中的相同。

使用量與定價

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

Execution time has a minimum of 5 minutes
Each organization receives 1,550 free hours of usage per month
Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

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

升級至最新工具版本

透過升級至 code-execution-2025-08-25，您可以獲得檔案操作和 Bash 功能的存取權限，包括多種語言的程式碼。價格沒有差異。

變更內容

元件	舊版	目前版本
Beta 標頭	`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`

向後相容性

所有現有的 Python 程式碼執行繼續完全如前運作
現有的僅限 Python 工作流程無需任何變更

升級步驟

要升級，請更新 API 請求中的工具類型：

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

檢查回應處理（如果以程式方式解析回應）：

先前用於 Python 執行回應的區塊將不再發送
取而代之的是，將發送 Bash 和檔案操作的新回應類型（請參閱回應格式章節）

程式化工具呼叫

Python

# Enable programmatic calling for your tools
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Get weather for 5 cities and find the warmest"}
    ],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "input_schema": {...},
            "allowed_callers": [
                "code_execution_20250825"
            ],  # Enable programmatic calling
        },
    ],
)

在程式化工具呼叫文件中了解更多。

將程式碼執行與 Agent Skills 搭配使用

程式碼執行工具使 Claude 能夠使用 Agent Skills。Skills 是由指令、腳本和資源組成的模組化功能，可擴展 Claude 的能力。

在 Agent Skills 文件和 Agent Skills API 指南中了解更多。

Was this page helpful?

模型相容性

平台可用性

快速開始

程式碼執行的運作方式

如何使用此工具

執行 Bash 命令

直接建立和編輯檔案

上傳並分析您自己的檔案

上傳並分析檔案

擷取生成的檔案

組合操作

工具定義

回應格式

Bash 命令回應

檔案操作回應

結果

錯誤

pause_turn 停止原因

容器

執行環境

資源限制

網路與安全

預先安裝的函式庫

容器重複使用

範例

串流

批次請求

使用量與定價

升級至最新工具版本

變更內容

向後相容性

升級步驟

程式化工具呼叫

將程式碼執行與 Agent Skills 搭配使用

模型相容性

平台可用性

快速開始

程式碼執行的運作方式

如何使用此工具

執行 Bash 命令

直接建立和編輯檔案

上傳並分析您自己的檔案

上傳並分析檔案

擷取生成的檔案

組合操作

工具定義

回應格式

Bash 命令回應

檔案操作回應

結果

錯誤

pause_turn 停止原因

容器

執行環境

資源限制

網路與安全

預先安裝的函式庫

容器重複使用

範例

串流

批次請求

使用量與定價

升級至最新工具版本

變更內容

向後相容性

升級步驟

程式化工具呼叫

將程式碼執行與 Agent Skills 搭配使用

`pause_turn` 停止原因

`pause_turn` 停止原因