Claude는 API 대화 내에서 데이터를 분석하고, 시각화를 생성하고, 복잡한 계산을 수행하고, 시스템 명령을 실행하고, 파일을 생성 및 편집하고, 업로드된 파일을 직접 처리할 수 있습니다. 코드 실행 도구를 사용하면 Claude가 보안 샌드박스 환경에서 Bash 명령을 실행하고 파일을 조작할 수 있습니다(코드 작성 포함).
코드 실행 도구는 현재 공개 베타 버전입니다.
이 기능을 사용하려면 API 요청에 "code-execution-2025-08-25" 베타 헤더를 추가하세요.
코드 실행 도구는 다음 모델에서 사용할 수 있습니다:
| 모델 | 도구 버전 |
|---|---|
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.5 (claude-sonnet-4-5-20250929) | 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 요청에 코드 실행 도구를 추가하면:
Claude에게 시스템 정보를 확인하고 패키지를 설치하도록 요청합니다:
Claude는 샌드박스의 파일 조작 기능을 사용하여 파일을 직접 생성, 보기 및 편집할 수 있습니다:
자신의 데이터 파일(CSV, Excel, 이미지 등)을 분석하려면 Files API를 통해 업로드하고 요청에서 참조하세요:
Files API와 함께 Code Execution을 사용하려면 두 개의 베타 헤더가 필요합니다: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"
Python 환경은 Files API를 통해 업로드된 다양한 파일 유형을 처리할 수 있습니다:
container_upload 콘텐츠 블록을 사용하여 메시지에서 파일 참조Claude가 코드 실행 중에 파일을 생성할 때 Files API를 사용하여 이러한 파일을 검색할 수 있습니다:
모든 기능을 사용하는 복잡한 워크플로우:
코드 실행 도구는 추가 매개변수가 필요하지 않습니다:
{
"type": "code_execution_20250825",
"name": "code_execution"
}이 도구가 제공되면 Claude는 자동으로 두 개의 하위 도구에 액세스할 수 있습니다:
bash_code_execution: 셸 명령 실행text_editor_code_execution: 파일 보기, 생성 및 편집(코드 작성 포함)코드 실행 도구는 작업에 따라 두 가지 유형의 결과를 반환할 수 있습니다:
{
"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, 실패하면 0이 아닌 값파일 작업의 추가 필드:
file_type, content, numLines, startLine, totalLinesis_file_update (파일이 이미 존재했는지 여부)oldStart, oldLines, newStart, newLines, lines (diff 형식)각 도구 유형은 특정 오류를 반환할 수 있습니다:
공통 오류 (모든 도구):
{
"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 | 파일이 없습니다 (보기/편집 작업의 경우) |
pause_turn 중지 이유응답에는 pause_turn 중지 이유가 포함될 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다. 응답을 그대로 후속 요청에 제공하여 Claude가 턴을 계속하도록 하거나, 대화를 중단하려면 콘텐츠를 수정할 수 있습니다.
코드 실행 도구는 코드 실행을 위해 특별히 설계된 보안 컨테이너 환경에서 실행되며, Python에 더 중점을 두고 있습니다.
샌드박스 Python 환경에는 다음과 같은 일반적으로 사용되는 라이브러리가 포함되어 있습니다:
이전 응답의 컨테이너 ID를 제공하여 여러 API 요청에서 기존 컨테이너를 재사용할 수 있습니다. 이를 통해 요청 간에 생성된 파일을 유지할 수 있습니다.
스트리밍이 활성화되면 코드 실행 이벤트가 발생할 때 수신합니다:
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}}
// 코드 실행이 스트리밍됩니다
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())\"}"}}
// 코드 실행 중 일시 중지
// 실행 결과가 스트리밍됩니다
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 tool usage is tracked separately from token usage. Execution time has a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container.
Each organization receives 1,550 free hours of usage with the code execution tool per month. Additional usage beyond the first 1,550 hours is billed at $0.05 per hour, per container.
code-execution-2025-08-25로 업그레이드하면 파일 조작 및 Bash 기능(여러 언어의 코드 포함)에 액세스할 수 있습니다. 가격 차이는 없습니다.
| 구성 요소 | 레거시 | 현재 |
|---|---|---|
| 베타 헤더 | 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 |
업그레이드하려면 API 요청에서 다음 변경을 수행해야 합니다:
베타 헤더 업데이트:
- "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"도구 유형 업데이트:
- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"응답 처리 검토 (프로그래밍 방식으로 응답을 구문 분석하는 경우):
코드 실행 도구는 프로그래밍 방식 도구 호출을 지원하며, 이를 통해 Claude가 실행 컨테이너 내에서 프로그래밍 방식으로 사용자 정의 도구를 호출하는 코드를 작성할 수 있습니다. 이를 통해 효율적인 다중 도구 워크플로우, Claude의 컨텍스트에 도달하기 전에 데이터 필터링, 복잡한 조건부 논리가 가능합니다.
# 도구에 대한 프로그래밍 방식 호출을 활성화합니다
response = client.beta.messages.create(
model="claude-sonnet-4-5",
betas=["advanced-tool-use-2025-11-20"],
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"] # 프로그래밍 방식 호출을 활성화합니다
}
]
)프로그래밍 방식 도구 호출 설명서에서 자세히 알아보세요.
코드 실행 도구를 사용하면 Claude가 Agent Skills를 사용할 수 있습니다. Skills는 Claude의 기능을 확장하는 지침, 스크립트 및 리소스로 구성된 모듈식 기능입니다.
Agent Skills 설명서 및 Agent Skills API 가이드에서 자세히 알아보세요.
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: code-execution-2025-08-25" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5",
"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"
}]
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: code-execution-2025-08-25" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Check the Python version and list installed packages"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "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: code-execution-2025-08-25" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5",
"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"
}]
}'# 먼저 파일을 업로드합니다
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_id를 사용합니다
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5",
"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"
}]
}'from anthropic import Anthropic
# 클라이언트를 초기화합니다
client = Anthropic()
# 파일을 생성하는 코드 실행을 요청합니다
response = client.beta.messages.create(
model="claude-sonnet-4-5",
betas=["code-execution-2025-08-25", "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"
}]
)
# 응답에서 파일 ID를 추출합니다
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
# 생성된 파일을 다운로드합니다
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}")# 먼저 파일을 업로드합니다
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
# file_id를 추출합니다 (jq 사용)
FILE_ID=$(jq -r '.id' file_response.json)
# 그런 다음 코드 실행과 함께 사용합니다
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5",
"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"
}]
}'| text_editor |
string_not_found |
old_str을 파일에서 찾을 수 없습니다 (str_replace의 경우) |
import os
from anthropic import Anthropic
# 클라이언트를 초기화합니다
client = Anthropic(
api_key=os.getenv("ANTHROPIC_API_KEY")
)
# 첫 번째 요청: 난수를 포함한 파일을 생성합니다
response1 = client.beta.messages.create(
model="claude-sonnet-4-5",
betas=["code-execution-2025-08-25"],
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"
}]
)
# 첫 번째 응답에서 컨테이너 ID를 추출합니다
container_id = response1.container.id
# 두 번째 요청: 컨테이너를 재사용하여 파일을 읽습니다
response2 = client.beta.messages.create(
container=container_id, # 동일한 컨테이너를 재사용합니다
model="claude-sonnet-4-5",
betas=["code-execution-2025-08-25"],
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"
}]
)