코드 실행 도구

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

웹 검색 또는 웹 가져오기와 함께 사용할 때 코드 실행은 무료입니다. web_search_20260209 또는 web_fetch_20260209가 요청에 포함되면, 표준 입력 및 출력 토큰 비용을 초과하는 코드 실행 도구 호출에 대한 추가 요금이 없습니다. 이러한 도구가 포함되지 않으면 표준 코드 실행 요금이 적용됩니다.

코드 실행은 고성능 에이전트를 구축하기 위한 핵심 기본 요소입니다. 웹 검색 및 웹 가져오기 도구에서 동적 필터링을 활성화하여 Claude가 결과를 컨텍스트 윈도우에 도달하기 전에 처리할 수 있게 하며, 정확도를 개선하면서 토큰 소비를 줄입니다.

모델 호환성

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

플랫폼 가용성

코드 실행은 다음에서 사용할 수 있습니다:

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

코드 실행은 현재 Amazon Bedrock 또는 Google Vertex AI에서 사용할 수 없습니다.

빠른 시작

Claude에게 계산을 수행하도록 요청하는 간단한 예제입니다:

client = anthropic.Anthropic()

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

print(response)

코드 실행 작동 방식

API 요청에 코드 실행 도구를 추가하면:

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

이는 웹 검색 또는 웹 가져오기와 코드 실행을 결합할 때 특히 중요합니다. 이들은 코드 실행을 자동으로 활성화합니다. 애플리케이션이 이미 클라이언트 측 셸 도구를 제공하는 경우, 자동 코드 실행은 Claude가 구분해야 하는 두 번째 실행 환경을 생성합니다.

도구 사용 방법

자신의 파일 업로드 및 분석

자신의 데이터 파일(CSV, Excel, 이미지 등)을 분석하려면 Files API를 통해 업로드하고 요청에서 참조하세요:

Python 환경은 Files API를 통해 업로드된 다양한 파일 유형을 처리할 수 있습니다:

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• 이미지 (JPEG, PNG, GIF, WebP)
• 텍스트 파일 (.txt, .md, .py 등)

파일 업로드 및 분석

1. 파일 업로드 Files API 사용
2. 파일 참조 container_upload 콘텐츠 블록을 사용하여 메시지에서 파일 참조
3. 코드 실행 도구 포함 API 요청에 코드 실행 도구 포함

client = anthropic.Anthropic()

# Upload a file
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Use the file_id with code execution
response = client.beta.messages.create(
    model="claude-opus-4-7",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response)

생성된 파일 검색

Claude가 코드 실행 중에 파일을 생성할 때, Files API를 사용하여 이러한 파일을 검색할 수 있습니다:

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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":
                # concrete-typed list: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    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}")

도구 정의

코드 실행 도구는 추가 매개변수가 필요하지 않습니다:

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

도구 유형별 오류 코드:

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 요청에서 기존 컨테이너를 재사용할 수 있습니다. 이를 통해 요청 간에 생성된 파일을 유지할 수 있습니다.

예제

# 첫 번째 요청: 난수를 포함한 파일 생성
response1 = client.messages.create(
    model="claude-opus-4-7",
    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.messages.create(
    container=container_id,  # 동일한 컨테이너 재사용
    model="claude-opus-4-7",
    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"}],
)

print(response2)

스트리밍

스트리밍이 활성화되면 코드 실행 이벤트가 발생할 때마다 수신됩니다:

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 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 기능을 포함한 여러 언어의 코드에 액세스할 수 있습니다. 가격 차이는 없습니다.

변경 사항

하위 호환성

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

업그레이드 단계

업그레이드하려면 API 요청에서 도구 유형을 업데이트하세요:

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

응답 처리 검토 (응답을 프로그래밍 방식으로 구문 분석하는 경우):

• Python 실행 응답에 대한 이전 블록은 더 이상 전송되지 않습니다
• 대신 Bash 및 파일 작업에 대한 새로운 응답 유형이 전송됩니다 (응답 형식 섹션 참조)

프로그래밍 방식의 도구 호출

코드 실행 컨테이너 내에서 도구를 실행하려면 프로그래밍 방식의 도구 호출을 참조하세요.

데이터 보존

코드 실행은 서버 측 샌드박스 컨테이너에서 실행됩니다. 실행 아티팩트, 업로드된 파일 및 출력을 포함한 컨테이너 데이터는 최대 30일 동안 보존됩니다. 이 보존은 컨테이너 환경 내에서 처리되는 모든 데이터에 적용됩니다. 코드 실행이 Files API에서 생성하는 파일(client.beta.files.download()를 통해 검색 가능)은 명시적으로 삭제될 때까지 유지됩니다.

모든 기능에 걸친 ZDR 적격성은 API 및 데이터 보존을 참조하세요.

Agent Skills와 함께 코드 실행 사용

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

Agent Skills 문서 및 Agent Skills API 가이드에서 자세히 알아보세요.