도구

코드 실행 도구

Claude는 API 대화 내에서 직접 데이터를 분석하고, 시각화를 생성하고, 복잡한 계산을 수행하고, 시스템 명령을 실행하고, 파일을 생성 및 편집하고, 업로드된 파일을 처리할 수 있습니다. 코드 실행 도구를 사용하면 Claude가 안전한 샌드박스 환경에서 Bash 명령을 실행하고 코드 작성을 포함한 파일 조작을 수행할 수 있습니다.

코드 실행 도구는 현재 공개 베타 상태입니다.

이 기능을 사용하려면 API 요청에 "code-execution-2025-08-25" 베타 헤더를 추가하세요.

이 기능에 대한 피드백을 공유하려면 피드백 양식을 통해 연락해 주세요.

모델 호환성

코드 실행 도구는 다음 모델에서 사용할 수 있습니다:

모델	도구 버전
Claude Opus 4.6 (`claude-opus-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에게 계산을 수행하도록 요청하는 간단한 예제입니다:

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-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 명령: 시스템 작업 및 패키지 관리를 위한 셸 명령 실행
- 파일 작업: 코드 작성을 포함하여 파일을 직접 생성, 보기 및 편집
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 "anthropic-beta: code-execution-2025-08-25" \
    --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 "anthropic-beta: code-execution-2025-08-25" \
    --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를 사용하려면 두 개의 베타 헤더가 필요합니다: "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 등)

파일 업로드 및 분석

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: code-execution-2025-08-25,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=["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"
    }]
)

# 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: code-execution-2025-08-25,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: 셸 명령 실행
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_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.beta.messages.create(
    model="claude-opus-4-6",
    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"
    }]
)

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

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

// 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 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-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`

프로그래밍 방식 도구 호출

코드 실행 도구는 프로그래밍 방식 도구 호출을 지원하며, 이를 통해 Claude가 실행 컨테이너 내에서 사용자 정의 도구를 프로그래밍 방식으로 호출하는 코드를 작성할 수 있습니다. 이를 통해 효율적인 다중 도구 워크플로, Claude의 컨텍스트에 도달하기 전 데이터 필터링, 복잡한 조건부 로직이 가능합니다.

Python

# Enable programmatic calling for your tools
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"]  # Enable programmatic calling
        }
    ]
)

자세한 내용은 프로그래밍 방식 도구 호출 문서에서 확인하세요.

Agent Skills와 함께 코드 실행 사용

코드 실행 도구를 사용하면 Claude가 Agent Skills를 사용할 수 있습니다. Skills는 Claude의 기능을 확장하는 지침, 스크립트 및 리소스로 구성된 모듈식 기능입니다.

자세한 내용은 Agent Skills 문서 및 Agent Skills API 가이드에서 확인하세요.

Was this page helpful?

도구

코드 실행 도구

코드 실행 도구는 현재 공개 베타 상태입니다.

이 기능을 사용하려면 API 요청에 "code-execution-2025-08-25" 베타 헤더를 추가하세요.

이 기능에 대한 피드백을 공유하려면 피드백 양식을 통해 연락해 주세요.

모델 호환성

코드 실행 도구는 다음 모델에서 사용할 수 있습니다:

모델	도구 버전
Claude Opus 4.6 (`claude-opus-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에게 계산을 수행하도록 요청하는 간단한 예제입니다:

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-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 명령: 시스템 작업 및 패키지 관리를 위한 셸 명령 실행
- 파일 작업: 코드 작성을 포함하여 파일을 직접 생성, 보기 및 편집
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 "anthropic-beta: code-execution-2025-08-25" \
    --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 "anthropic-beta: code-execution-2025-08-25" \
    --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를 사용하려면 두 개의 베타 헤더가 필요합니다: "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 등)

파일 업로드 및 분석

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: code-execution-2025-08-25,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=["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"
    }]
)

# 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: code-execution-2025-08-25,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: 셸 명령 실행
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_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

컨테이너 재사용

예제

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.beta.messages.create(
    model="claude-opus-4-6",
    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"
    }]
)

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

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

// 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": ""}}}

배치 요청

사용량 및 가격

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

# Enable programmatic calling for your tools
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"]  # Enable programmatic calling
        }
    ]
)

자세한 내용은 프로그래밍 방식 도구 호출 문서에서 확인하세요.

Agent Skills와 함께 코드 실행 사용

자세한 내용은 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` 중지 사유