코드 실행 도구

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

코드 실행은 웹 검색 또는 웹 가져오기(web_search_20260209, web_fetch_20260209 이상)와 함께 사용할 때 무료입니다. 요청에 이러한 도구 중 하나가 포함되어 있으면, 해당 요청에서 코드 실행에 대해 표준 토큰 비용 외에 추가 요금이 부과되지 않습니다. 이는 동적 필터링에 사용되는 코드 실행과 Claude가 직접 실행하는 모든 코드에 모두 적용됩니다. 이러한 도구가 포함되지 않은 경우에는 표준 코드 실행 요금이 적용됩니다.

코드 실행은 웹 검색 및 웹 가져오기 도구의 "dynamic filtering"(동적 필터링)도 지원합니다. Claude는 결과가 "context window"(컨텍스트 윈도우)에 도달하기 전에 코드 실행 환경 내에서 결과를 필터링합니다. 동적 필터링이 실행되면 API가 요청에 필요한 코드 실행을 자동으로 프로비저닝하므로, 이를 위해 요청에 코드 실행 도구를 추가할 필요가 없습니다.

도구 버전

코드 실행 도구에는 현재 세 가지 버전이 있으며, 지원되는 모든 모델은 세 가지 버전을 모두 허용합니다. 각 버전은 이전 버전을 기반으로 합니다:

• code_execution_20250825는 Bash 명령과 파일 작업을 지원합니다.
• code_execution_20260120은 "Read-Eval-Print Loop"(읽기-평가-출력 루프), 즉 REPL의 상태 유지와 샌드박스 내에서의 "programmatic tool calling"(프로그래밍 방식 도구 호출)을 추가합니다. Claude Haiku 4.5는 code_execution_20260120 및 code_execution_20260521 도구 유형을 허용하지만, 해당 모델에서는 프로그래밍 방식 도구 호출과 이에 의존하는 REPL 상태 유지를 사용할 수 없으므로, 최신 버전도 해당 모델에서는 code_execution_20250825처럼 동작합니다.
• code_execution_20260521은 code_execution_20260120과 동일한 런타임입니다. 차이점은 도구 설명이 프로그래밍 방식 도구 호출에서 각 Python 셀에 적용되는 90초의 실제 경과 시간 제한을 Claude에게 알려주므로, Claude가 오래 실행되는 셀의 시간을 계획할 수 있다는 것입니다. 제한을 초과한 셀은 0이 아닌 return_code와 출력에 detection_timeout 상태 메시지가 포함된 일반 코드 실행 결과를 반환합니다. 이는 전체 도구 호출이 최대 실행 시간을 초과할 때 API가 반환하는 execution_time_exceeded 오류 코드와는 별개입니다.

세 가지 도구 버전 모두 anthropic-beta 헤더가 필요하지 않습니다. 레거시 코드 실행 베타 헤더는 여전히 유효한 옵트인 방식입니다.

이 페이지의 예제는 code_execution_20250825를 사용합니다. 이 버전은 예제에서 보여주는 Bash 및 파일 작업을 지원하며 지원되는 모든 모델에서 동일하게 동작합니다. 프로그래밍 방식 도구 호출이나 REPL 상태 유지가 필요한 경우 code_execution_20260120 이상을 사용하세요. 현재 웹 검색 및 웹 가져오기 도구(web_search_20260209, web_fetch_20260209 이상)는 코드 실행 버전으로 code_execution_20260120 이상이 필요합니다.

이전 도구 버전은 최신 모델과의 호환성이 보장되지 않습니다. 새 모델을 도입할 때는 도구 버전과 호환성을 확인하고, 통합에서 지원하는 최신 도구 버전을 사용하는 것이 좋습니다.

빠른 시작

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to 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.to_json())

응답에는 server_tool_use 블록(Claude가 실행한 명령)과 해당 도구 결과 블록이 번갈아 나타나고, 그 뒤에 Claude의 텍스트가 이어집니다. 최상위 수준에는 container 객체도 포함되며, 이 객체의 id를 여러 요청에서 재사용할 수 있습니다. 블록 형태는 응답 형식을 참조하세요.

코드 실행 작동 방식

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

1. Claude는 코드 실행이 질문에 답하는 데 도움이 되는지 평가합니다
2. 도구는 Claude에게 다음 기능을 자동으로 제공합니다:
   • Bash 명령: 시스템 작업을 위한 셸 명령 실행
   • 파일 작업: 코드 작성을 포함하여 파일을 직접 생성, 조회 및 편집
3. Claude는 단일 요청에서 이러한 기능을 어떤 조합으로든 사용할 수 있습니다
4. 모든 작업은 안전한 샌드박스 컨테이너에서 실행됩니다. 컨테이너는 인터넷에 접근할 수 없으므로 Claude는 런타임에 패키지를 다운로드할 수 없으며, 사전 설치된 라이브러리만 사용할 수 있습니다
5. API는 모든 명령을 서버 측에서 실행하고 동일한 요청 내에서 결과를 Claude에게 반환하므로, 사용자가 직접 코드를 실행하거나 tool_result 블록을 다시 보낼 필요가 없습니다. 한 가지 예외는 Claude가 코드 실행과 함께 클라이언트 도구 중 하나를 호출하는 경우입니다. 이때 API는 결과 없이 코드 실행 호출을 반환합니다. 결과는 클라이언트 도구에 대한 tool_result 블록을 다시 보낸 후 이후 응답에서 도착합니다
6. 이전 응답의 컨테이너 ID를 다시 전달하지 않는 한 각 요청은 새 컨테이너에서 실행됩니다(컨테이너 재사용 참조)
7. Claude는 생성된 차트, 계산 또는 분석과 함께 결과를 제공합니다

컨테이너에는 Python이 사전 설치되어 있습니다. Claude는 파일 작업 하위 도구로 Python을 작성하고 Bash 명령으로 실행합니다. code_execution_20260120 이상과 프로그래밍 방식 도구 호출을 사용하면, Python 인터프리터 상태(예: 변수 바인딩)도 컨테이너를 재사용하는 요청 간에 유지됩니다.

Claude가 코드를 실행하는 경우

Claude는 요청이 계산이나 파일 처리의 이점을 얻을 수 있을 때 코드를 실행합니다:

• 간단하지 않은 수학(큰 숫자, 여러 단계, 정밀도가 중요한 결과)
• 데이터 분석, 파일 파싱 또는 시각화
• 알고리즘 실행 또는 시뮬레이션
• "run", "compute" 또는 "execute"와 같은 명시적 요청

Claude는 다음의 경우 코드를 실행하지 않고 직접 답변합니다:

• 간단한 산술 및 잘 알려진 수학적 사실
• 사실 확인, 대화형 또는 창작 요청
• 간단한 단위 변환 또는 번역

경계에 있는 요청에 대해 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()

# 파일을 업로드합니다
file_object = client.files.upload(file=Path("data.csv"))

# 코드 실행에 file_id를 사용합니다
response = client.messages.create(
    model="claude-opus-5",
    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.to_json())

생성된 파일 가져오기

Claude가 코드 실행 중에 출력 디렉터리에 파일을 저장하면(생성된 파일이 캡처되는 방식 참조), 각 파일의 ID가 코드 실행 도구 결과에 나타나며 Files API로 다운로드할 수 있습니다:

client = Anthropic()

# 파일을 생성하는 코드 실행을 요청합니다
response = client.messages.create(
    model="claude-opus-5",
    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: Message) -> list[str]:
    file_ids: list[str] = []
    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 output_block in content_item.content:
                    file_ids.append(output_block.file_id)
    return file_ids


# 생성된 파일을 다운로드합니다
for file_id in extract_file_ids(response):
    file_metadata = client.files.retrieve_metadata(file_id)
    file_content = client.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

생성된 파일이 캡처되는 방식

각 bash_code_execution 호출은 새로운 빈 디렉터리를 받으며, 명령에서 $OUTPUT_DIR로 사용할 수 있습니다. 명령이 완료되면 해당 디렉터리의 최상위 수준에 있는 파일이 캡처되어 결과의 content 목록에 file_id 항목으로 반환됩니다. 다른 위치에 작성된 파일은 컨테이너에 남아 있으며 반환되지 않습니다.

도구 설명은 Claude에게 파일을 $OUTPUT_DIR에 복사하여 공유하도록 안내합니다. 애플리케이션이 파일을 받는 것에 의존한다면, Claude에게 파일을 $OUTPUT_DIR에 복사하고 같은 명령에서 디렉터리 목록을 출력하도록 프롬프트를 작성하세요. 그러면 ls 출력으로 캡처를 확인할 수 있습니다(Claude는 content 목록을 볼 수 없습니다):

python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"

Claude가 다른 위치에 작성한 파일은 여전히 컨테이너에 있으므로, 컨테이너를 재사용하여 Claude에게 해당 파일을 $OUTPUT_DIR에 복사하도록 요청할 수 있습니다.

생성된 파일의 Content Credentials

Claude API에서 Claude가 코드 실행 샌드박스에서 생성한 지원되는 이미지, 비디오 및 오디오 파일은 Files API를 통해 다운로드할 때 C2PA Content Credentials를 포함합니다. 지원되는 형식에는 PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC 및 M4A가 포함됩니다. 자격 증명은 파일의 메타데이터에 포함된 암호화 서명된 매니페스트입니다. 이는 Anthropic을 발급자로 식별하고, 타임스탬프를 포함하며, "Claude provided this file at the request of a user and may have created or modified the file contents."라는 작업 설명을 기록합니다.

서명을 위해 요청이나 응답 처리를 변경할 필요가 없으며, 매니페스트에는 사용자, 조직 또는 요청에 관한 정보가 기록되지 않습니다. 파일의 보이는 콘텐츠는 변경되지 않습니다. 매니페스트는 몇 킬로바이트를 추가하므로, 다운로드한 파일의 크기와 체크섬은 컨테이너 내부에 있는 파일과 다릅니다. 텍스트 파일, PDF 및 오피스 문서는 서명 지원 형식이 아니므로 서명되지 않습니다. 업로드한 파일은 이미 포함된 Content Credentials를 포함하여 있는 그대로 저장됩니다.

자격 증명을 확인하려면 오픈 소스 c2patool 명령줄 유틸리티와 같은 C2PA 호환 도구로 파일을 검사하세요. 재인코딩, 형식 변환, 스크린샷 및 메타데이터를 제거하는 도구는 자격 증명을 제거하므로, 자격 증명이 없다고 해서 파일이 Claude로 생성되지 않았다는 의미는 아닙니다. 자격 증명이 누락될 수 있는 이유에 대한 자세한 내용은 How Claude marks AI-generated content를 참조하세요.

도구 정의

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

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

두 필드 모두 고정되어 있습니다. type은 도구 버전을 선택하며, name은 반드시 code_execution이어야 합니다.

이 도구를 제공하면 Claude는 자동으로 두 가지 하위 도구에 접근할 수 있습니다:

• bash_code_execution: 셸 명령 실행
• text_editor_code_execution: 코드 작성을 포함하여 파일 조회, 생성 및 편집

Claude가 코드를 실행하면 응답에는 컨테이너의 id와 expires_at 타임스탬프가 포함된 최상위 container 객체도 포함됩니다. 동일한 컨테이너를 계속 사용하려면 해당 ID를 최상위 container 요청 매개변수로 다시 전달하세요. 컨테이너 재사용을 참조하세요.

응답 형식

코드 실행 도구는 작업에 따라 두 가지 유형의 결과를 반환할 수 있습니다:

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,
    "content": []
  }
}

파일 작업 응답

파일 조회:

{
  "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_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 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_create_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_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}

결과

Bash 명령 결과(bash_code_execution_result)에는 다음이 포함됩니다:

• stdout: 성공적인 실행의 출력
• stderr: 실행 실패 시 오류 메시지
• return_code: 성공 시 0, 실패 시 0이 아닌 값
• content: 명령이 $OUTPUT_DIR에 남긴 각 파일에 대한 항목이 포함된 목록(생성된 파일이 캡처되는 방식 참조). 각 항목에는 Files API로 파일을 가져오는 데 사용할 file_id가 포함됩니다

파일 작업 결과에는 고유한 필드가 있습니다:

• 조회 (text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_lines
• 생성 (text_editor_code_execution_create_result): is_file_update (파일이 이미 존재했는지 여부)
• 편집 (text_editor_code_execution_str_replace_result): old_start, old_lines, new_start, new_lines, lines (diff 형식)

오류

각 도구 유형은 특정 오류를 반환할 수 있습니다:

공통 오류 (모든 도구):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

도구 유형별 오류 코드:

만료된 컨테이너는 재사용할 수 없습니다. 만료된 컨테이너를 참조하는 요청은 컨테이너를 복원하는 대신 오류를 반환합니다. 새 컨테이너를 받으려면 container 매개변수 없이 요청을 다시 보내세요.

pause_turn 중지 이유

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

컨테이너

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

런타임 환경

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

리소스 제한

• 메모리: 5 GiB RAM
• 디스크 공간: 5 GiB 작업 공간 스토리지
• CPU: 1 CPU
• 실행 시간: 최대 실행 시간을 초과하여 실행되는 도구 호출은 execution_time_exceeded 오류를 반환합니다. 프로그래밍 방식 도구 호출을 사용하는 경우, 각 REPL 셀에도 90초의 실제 경과 시간 제한이 있습니다

네트워킹 및 보안

• 인터넷 접근: 보안을 위해 완전히 비활성화됨
• 외부 연결: 아웃바운드 네트워크 요청이 허용되지 않음
• 샌드박스 격리: 호스트 시스템 및 다른 컨테이너로부터 완전히 격리됨
• 파일 접근: 작업 공간 디렉터리로만 제한됨
• 작업 공간 범위: 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와 같은 명령줄 도구도 포함되어 있습니다.

컨테이너는 인터넷에 접근할 수 없으므로 Claude는 런타임에 추가 패키지를 다운로드하거나 설치할 수 없으며, 사전 설치된 라이브러리만 사용할 수 있습니다.

컨테이너 재사용

이전 응답의 컨테이너 ID를 제공하여 여러 API 요청에서 기존 컨테이너를 재사용할 수 있습니다. 이를 통해 요청 간에 생성된 파일을 유지할 수 있습니다. code_execution_20260120 이상과 프로그래밍 방식 도구 호출을 사용하면 Python 인터프리터 상태도 유지됩니다.

컨테이너는 생성 후 30일이 지나면 만료됩니다. 약 5분 동안 활동이 없으면 컨테이너가 체크포인트되며, 30일 기간 내에 해당 ID로 요청을 보내면 컨테이너가 복원됩니다. 응답의 container 객체에 있는 expires_at 타임스탬프는 더 짧은 롤링 값이며 30일 제한을 나타내지 않습니다. 만료된 컨테이너는 재사용할 수 없습니다. 새 컨테이너를 받으려면 container 매개변수 없이 요청을 다시 보내세요.

예제

client = anthropic.Anthropic()

# 첫 번째 요청: 새 컨테이너에서 임의의 숫자가 담긴 파일을 생성합니다
response1 = client.messages.create(
    model="claude-opus-5",
    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"}],
)

# 두 번째 요청: Claude가 같은 컨테이너를 재사용하도록 컨테이너 ID를 다시 전달합니다
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5",
    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.to_json())

다른 실행 도구와 함께 코드 실행 사용하기

코드를 실행하는 클라이언트 제공 도구(예: Bash 도구 또는 사용자 정의 REPL)와 함께 코드 실행을 제공하면, Claude는 "multicomputer environment"(다중 컴퓨터 환경)에서 작동하게 됩니다. 코드 실행 도구는 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가 구분해야 하는 두 번째 실행 환경을 만듭니다.

Claude가 코드 실행과 함께 클라이언트 도구 중 하나를 호출하면, API는 결과 없이 코드 실행 호출을 반환합니다. 결과는 클라이언트 도구에 대한 tool_result 블록을 다시 보낸 후 이후 응답에서 도착합니다.

스트리밍

스트리밍을 활성화하면("stream": true), 코드 실행 이벤트가 발생할 때 이를 수신하게 됩니다. 하위 도구 입력은 input_json_delta 이벤트로 스트리밍되며, 각 결과 블록은 단일 content_block_start 이벤트에서 전체가 한 번에 도착합니다:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}

배치 요청

Messages Batches API에 코드 실행 도구를 포함할 수 있습니다. Messages Batches API를 통한 코드 실행 도구 호출은 일반 Messages API 요청의 호출과 동일한 가격이 책정됩니다.

사용량 및 가격

코드 실행은 웹 검색 또는 웹 가져오기와 함께 사용할 경우 무료입니다. API 요청에 web_search_20260209(또는 이후 버전) 또는 web_fetch_20260209(또는 이후 버전)가 포함되어 있으면, 표준 입력 및 출력 토큰 비용 외에 코드 실행 도구 호출에 대한 추가 요금이 부과되지 않습니다.

이러한 도구 없이 사용할 경우, 코드 실행은 실행 시간을 기준으로 청구되며 토큰 사용량과는 별도로 추적됩니다:

• 실행 시간은 최소 5분입니다
• 각 조직은 매월 1,550시간의 무료 사용량을 제공받습니다
• 1,550시간을 초과하는 추가 사용량은 컨테이너당 시간당 $0.05 USD로 청구됩니다
• 요청에 파일이 포함된 경우, 파일이 컨테이너에 미리 로드되므로 도구가 호출되지 않더라도 실행 시간이 청구됩니다

코드 실행 사용량은 응답에서 추적됩니다:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}

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

최신 도구 버전은 code_execution_20260521입니다. 현재 세 가지 버전 간에 전환하려면 요청의 type 문자열을 업데이트하세요. 세 버전 모두 응답 형식에 설명된 응답 블록을 반환합니다. 각 버전이 추가하는 기능은 도구 버전을, 이를 지원하는 모델은 호환성을 참조하세요.

이 섹션의 나머지 부분에서는 레거시 Python 전용 code_execution_20250522에서 현재 도구 버전으로 마이그레이션하는 방법을 다룹니다.

변경 사항

하위 호환성

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

업그레이드 단계

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

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

응답 처리 검토 (프로그래밍 방식으로 응답을 파싱하는 경우):

• API는 더 이상 Python 실행 응답에 대해 이전 블록을 보내지 않습니다
• 대신 API는 Bash 및 파일 작업에 대한 새로운 응답 유형을 보냅니다(응답 형식 참조)

데이터 보존

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

모든 기능의 ZDR 적격성에 대해서는 API 및 데이터 보존을 참조하세요.

다음 단계

Compatibility