Claude는 API 대화 내에서 직접 데이터를 분석하고, 시각화를 생성하고, 복잡한 계산을 수행하고, 시스템 명령을 실행하고, 파일을 생성 및 편집하고, 업로드된 파일을 처리할 수 있습니다. 코드 실행 도구를 사용하면 Claude가 안전한 샌드박스 환경에서 Bash 명령을 실행하고 코드 작성을 포함한 파일을 조작할 수 있습니다.
코드 실행 도구는 현재 공개 베타 버전입니다.이 기능을 사용하려면 API 요청에 "code-execution-2025-08-25" 베타 헤더를 추가하세요.
최근 코드 실행 도구를 업그레이드하여 Bash 명령과 직접 파일 조작을 지원합니다. 최신 도구 버전으로 업그레이드하는 방법은 최신 도구 버전으로 업그레이드를 참조하세요.

​
지원되는 모델

코드 실행 도구는 다음에서 사용할 수 있습니다:
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
빠른 시작

다음은 Claude에게 계산을 수행하도록 요청하는 간단한 예제입니다: 
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-opus-4-1-20250805",
        "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 요청에 코드 실행 도구를 추가하면:
  1. Claude는 코드 실행이 질문에 답하는 데 도움이 될지 평가합니다
  2. 도구는 자동으로 Claude에게 다음 기능을 제공합니다:
    • Bash 명령: 시스템 작업 및 패키지 관리를 위한 셸 명령 실행
    • 파일 작업: 코드 작성을 포함하여 파일을 직접 생성, 보기 및 편집
  3. Claude는 단일 요청에서 이러한 기능의 조합을 사용할 수 있습니다
  4. 모든 작업은 안전한 샌드박스 환경에서 실행됩니다
  5. Claude는 생성된 차트, 계산 또는 분석과 함께 결과를 제공합니다

​
도구 사용 방법

​
Bash 명령 실행

Claude에게 시스템 정보를 확인하고 패키지를 설치하도록 요청하세요: 
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-opus-4-1-20250805",
        "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 "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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를 사용하려면 두 개의 베타 헤더가 필요합니다: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"
Python 환경은 Files API를 통해 업로드된 다양한 파일 유형을 처리할 수 있습니다:
  • CSV
  • Excel (.xlsx, .xls)
  • JSON
  • XML
  • 이미지 (JPEG, PNG, GIF, WebP)
  • 텍스트 파일 (.txt, .md, .py 등)

​
파일 업로드 및 분석

  1. Files API를 사용하여 파일 업로드
  2. container_upload 콘텐츠 블록을 사용하여 메시지에서 파일 참조
  3. API 요청에 코드 실행 도구 포함
# 먼저 파일을 업로드합니다
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-opus-4-1-20250805",
        "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

# 클라이언트 초기화
client = Anthropic()

# 파일을 생성하는 코드 실행 요청
response = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    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.get('type') == 'code_execution_result':
                for file in content_item.get('content', []):
                    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-opus-4-1-20250805",
        "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: 셸 명령 실행
  • 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, 실패의 경우 0이 아닌 값
파일 작업에 대한 추가 필드:
  • 보기: file_type, content, numLines, startLine, totalLines
  • 생성: is_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_editorfile_not_found파일이 존재하지 않음 (보기/편집 작업의 경우)
text_editorstring_not_found파일에서 old_str을 찾을 수 없음 (str_replace의 경우)

​
pause_turn 중지 이유

응답에는 pause_turn 중지 이유가 포함될 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다. Claude가 턴을 계속하도록 하려면 응답을 그대로 후속 요청에 제공하거나, 대화를 중단하려면 콘텐츠를 수정할 수 있습니다.

​
컨테이너

코드 실행 도구는 Python에 중점을 둔 코드 실행을 위해 특별히 설계된 안전한 컨테이너화된 환경에서 실행됩니다.

​
런타임 환경

  • Python 버전: 3.11.12
  • 운영 체제: Linux 기반 컨테이너
  • 아키텍처: x86_64 (AMD64)

​
리소스 제한

  • 메모리: 1GiB RAM
  • 디스크 공간: 5GiB 작업 공간 저장소
  • CPU: 1 CPU

​
네트워킹 및 보안

  • 인터넷 액세스: 보안을 위해 완전히 비활성화됨
  • 외부 연결: 아웃바운드 네트워크 요청 허용되지 않음
  • 샌드박스 격리: 호스트 시스템 및 다른 컨테이너와 완전 격리
  • 파일 액세스: 작업 공간 디렉토리로만 제한
  • 작업 공간 범위: Files와 마찬가지로 컨테이너는 API 키의 작업 공간으로 범위가 지정됨
  • 만료: 컨테이너는 생성 후 1시간 후에 만료됨

​
사전 설치된 라이브러리

샌드박스 Python 환경에는 다음과 같이 일반적으로 사용되는 라이브러리가 포함되어 있습니다:
  • 데이터 사이언스: pandas, numpy, scipy, scikit-learn, statsmodels
  • 시각화: matplotlib, seaborn
  • 파일 처리: pyarrow, openpyxl, 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

# 클라이언트 초기화
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# 첫 번째 요청: 임의의 숫자로 파일 생성
response1 = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    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-opus-4-1-20250805",
    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"
    }]
)

​
스트리밍

스트리밍이 활성화되면 코드 실행 이벤트가 발생할 때 수신됩니다: 
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 요청과 동일하게 가격이 책정됩니다.

​
사용량 및 가격

The code execution tool usage is tracked separately from token usage. Execution time is 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. Pricing: $0.05 per session-hour.

​
최신 도구 버전으로 업그레이드

code-execution-2025-08-25로 업그레이드하면 여러 언어의 코드를 포함한 파일 조작 및 Bash 기능에 액세스할 수 있습니다. 가격 차이는 없습니다.

​
변경 사항

구성 요소레거시현재
베타 헤더code-execution-2025-05-22code-execution-2025-08-25
도구 유형code_execution_20250522code_execution_20250825
기능Python만Bash 명령, 파일 작업
응답 유형code_execution_resultbash_code_execution_result, text_editor_code_execution_result

​
하위 호환성

  • 기존의 모든 Python 코드 실행은 이전과 정확히 동일하게 계속 작동합니다
  • 기존 Python 전용 워크플로에는 변경이 필요하지 않습니다

​
업그레이드 단계

업그레이드하려면 API 요청에서 다음 변경 사항을 수행해야 합니다:
  1. 베타 헤더 업데이트: 
    - "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"
  2. 도구 유형 업데이트: 
    - "type": "code_execution_20250522"
+ "type": "code_execution_20250825"
  3. 응답 처리 검토 (응답을 프로그래밍 방식으로 구문 분석하는 경우):
    • Python 실행 응답에 대한 이전 블록은 더 이상 전송되지 않습니다
    • 대신 Bash 및 파일 작업에 대한 새로운 응답 유형이 전송됩니다 (응답 형식 섹션 참조)