工具

程式碼執行工具

使用 Claude 的程式碼執行工具在安全的沙盒環境中執行 Bash 命令、操作檔案並處理上傳的檔案。

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 工具或自訂 REPL）一起提供時，Claude 在多電腦環境中運作。程式碼執行工具在 Anthropic 的沙盒容器中執行，而您的用戶端提供工具則在您控制的獨立環境中執行。Claude 有時可能會混淆這些環境，嘗試使用錯誤的工具或假設狀態在它們之間共享。

為避免這種情況，請在您的系統提示中加入說明以釐清區別：

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

這在將程式碼執行與網路搜尋或網路擷取結合使用時尤為重要，因為這些工具會自動啟用程式碼執行。如果您的應用程式已提供用戶端 shell 工具，自動程式碼執行會建立第二個執行環境，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

網路和安全性

網際網路存取：出於安全考量完全停用
外部連線：不允許任何出站網路請求
沙盒隔離：與主機系統和其他容器完全隔離
檔案存取：僅限於工作區目錄
工作區範圍：與檔案類似，容器的範圍限定於 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
        },
    ],
)

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

資料保留

程式碼執行在伺服器端沙盒容器中運行。容器資料，包括執行產物、上傳的檔案和輸出，最多保留 30 天。此保留期適用於在容器環境中處理的所有資料。

有關所有功能的 ZDR 資格，請參閱 API 與資料保留。

搭配 Agent Skills 使用程式碼執行

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

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

Was this page helpful?

工具

程式碼執行工具

使用 Claude 的程式碼執行工具在安全的沙盒環境中執行 Bash 命令、操作檔案並處理上傳的檔案。

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

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 提供包含任何生成的圖表、計算或分析的結果

與其他執行工具一起使用程式碼執行

為避免這種情況，請在您的系統提示中加入說明以釐清區別：

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

如何使用工具

執行 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

網路和安全性

網際網路存取：出於安全考量完全停用
外部連線：不允許任何出站網路請求
沙盒隔離：與主機系統和其他容器完全隔離
檔案存取：僅限於工作區目錄
工作區範圍：與檔案類似，容器的範圍限定於 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
        },
    ],
)

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

資料保留

有關所有功能的 ZDR 資格，請參閱 API 與資料保留。

搭配 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` 停止原因