코드 실행 도구 (Code Execution Tool)¶

Claude는 API 대화 안에서 직접 데이터를 분석하고, 시각화를 만들고, 복잡한 계산을 수행하고, 시스템 명령을 실행하고, 파일을 생성·수정하고, 업로드한 파일을 처리할 수 있어요. 코드 실행 도구(Code Execution Tool)는 Claude가 보안이 보장된 샌드박스 환경에서 Bash 명령을 실행하고 파일을 다루는 일(코드 작성 포함)을 가능하게 해주는 도구예요.

웹 검색이나 웹 페치(web_search_20260209, web_fetch_20260209 또는 그 이후 버전)와 함께 쓰면 코드 실행은 무료예요. 해당 도구 중 하나가 요청에 포함되어 있으면, 그 요청에서의 코드 실행에는 표준 토큰 비용 외에 추가 요금이 붙지 않아요. 여기엔 동적 필터링(dynamic filtering) 뒤에 있는 코드 실행과 Claude가 직접 실행하는 코드가 모두 포함돼요. 해당 도구가 포함되지 않을 때는 표준 코드 실행 요금이 적용돼요.

코드 실행은 또 웹 검색과 웹 페치 도구의 동적 필터링을 뒷받침하기도 해요. Claude가 그 결과를 컨텍스트 윈도우에 넣기 전에 코드 실행 환경 안에서 필터링을 하는 거죠. 동적 필터링이 실행되면 API가 요청에 필요한 코드 실행을 자동으로 프로비저닝하므로, 그 때문에 코드 실행 도구를 직접 요청에 추가할 필요는 없어요.

도구 버전¶

코드 실행 도구에는 현재 3가지 버전이 있고, 지원되는 모든 모델이 세 가지를 모두 받아들여요. 각 버전은 이전 버전 위에 쌓여 있어요:

code_execution_20250825는 Bash 명령과 파일 연산을 지원해요.
code_execution_20260120는 REPL 상태 유지와 샌드박스 안에서의 프로그래매틱 도구 호출을 추가해요. Claude Haiku 4.5는 code_execution_20260120과 code_execution_20260521 도구 타입을 받아들이지만, 프로그램매틱 도구 호출과 그에 의존하는 REPL 상태 유지는 지원되지 않아서 그 모델에서는 최신 버전들이 code_execution_20250825처럼 동작해요.
code_execution_20260521은 code_execution_20260120과 동일한 런타임이에요. 차이는 도구 설명이 프로그램매틱 도구 호출에서 각 Python 셀의 90초 벽시계(wall-clock) 제한을 Claude에게 알려줘서, 오래 실행되는 셀의 예산을 잡을 수 있게 해준다는 점이에요. 제한을 초과한 셀은 0이 아닌 return_code와 출력의 detection_timeout 상태 메시지를 가진 일반적인 코드 실행 결과를 반환해요. 이는 API가 전체 도구 호출이 최대 실행 시간을 초과했을 때 반환하는 execution_time_exceeded 오류 코드와는 별개의 것이에요.

세 도구 버전 모두 anthropic-beta 헤더를 요구하지 않아요. 기존의 레거시 코드 실행 베타 헤더는 여전히 유효한 옵트인(opt-in)이에요.

이 페이지의 예시들은 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의 텍스트가 이어져요. 최상위에는 컨테이너의 id를 요청 간에 재사용할 수 있는 container 객체도 포함돼요. 블록 형태는 응답 형식을 참고하세요.

코드 실행이 어떻게 동작하나요¶

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

Claude가 코드 실행이 질문에 답하는 데 도움이 될지 판단해요
도구가 자동으로 Claude에게 다음 능력을 제공해요:
Bash 명령: 시스템 연산을 위한 셸 명령 실행
파일 연산: 코드 작성 포함, 파일 생성·조회·편집
Claude는 단일 요청에서 이 능력들을 어떤 조합으로든 사용할 수 있어요
모든 연산은 보안이 보장된 샌드박스 컨테이너에서 실행돼요. 컨테이너에는 인터넷 접근이 없어서 Claude는 런타임에 패키지를 다운로드할 수 없고, 사전 설치된 라이브러리만 사용할 수 있어요
API는 모든 명령을 서버 측에서 실행하고 그 결과를 같은 요청 안에서 Claude에게 반환해요. 그래서 여러분이 코드를 직접 실행하거나 tool_result 블록을 직접 보내지 않아도 돼요. 예외가 하나 있는데, Claude가 코드 실행과 함께 여러분의 클라이언트 도구 중 하나를 호출할 때예요. 이때 API는 결과 없이 코드 실행 호출만 반환하고, 결과는 여러분이 클라이언트 도구의 tool_result 블록을 보낸 뒤 이후 응답에서 도착해요
이전 응답의 컨테이너 ID를 다시 전달하지 않는 한 (컨테이너 재사용 참고) 각 요청은 새 컨테이너에서 실행돼요
Claude는 생성된 차트, 계산, 분석 결과를 함께 제공해요

컨테이너에는 Python이 사전 설치되어 있어요. Claude는 파일 연산 하위 도구로 Python을 작성하고 Bash 명령으로 실행해요. code_execution_20260120 이상과 프로그래매틱 도구 호출에서는 Python 인터프리터 상태(변수 바인딩 등)도 컨테이너를 재사용하는 요청 간에 유지돼요.

언제 Claude가 코드를 실행하나요¶

Claude는 요청이 계산이나 파일 처리의 이점을 얻을 때 코드를 실행해요:

사소하지 않은 수학(큰 숫자, 많은 단계, 정밀도에 민감한 결과)
데이터 분석, 파일 파싱, 시각화
알고리즘 실행 또는 시뮬레이션
"실행", "계산", "수행"을 요청하는 명시적 요청

Claude는 다음 경우에는 코드를 실행하지 않고 바로 답해요:

단순 산술과 잘 알려진 수학 사실
사실적, 대화형, 창의적 요청
단순 단위 변환이나 번역

경계선에 있는 요청에서 Claude가 코드를 실행하길 원한다면 명시적으로 물어보세요(예: "코드로 이걸 검증해 봐"처럼요).

파일 다루기¶

여러분의 파일 업로드 및 분석¶

CSV, Excel, 이미지 같은 자신의 데이터 파일을 분석하려면 Files API로 업로드하고 요청에서 참조하세요.

Python 환경은 Files API로 업로드한 여러 파일 형식을 처리할 수 있어요:

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

파일 업로드 및 분석¶

Files API로 파일을 업로드해요
메시지에서 container_upload 콘텐츠 블록으로 파일을 참조해요
API 요청에 코드 실행 도구를 포함해요

client = anthropic.Anthropic()

# Upload a file
file_object = client.files.upload(file=Path("data.csv"))

# Use the file_id with code execution
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()

# Request code execution that creates files
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"}],
)

# Extract file IDs from the response
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

# Download the created files
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 콘텐츠 크레덴셜을 지녀요. 지원 형식에는 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, 오피스 문서는 서명 지원 형식이 아니므로 서명되지 않아요. 업로드한 파일은 이미 지니고 있는 콘텐츠 크레덴셜을 포함해 원본 그대로 저장돼요.

크레덴셜을 검증하려면 오픈소스 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"
  }
}

도구 타입별 오류 코드:

도구	오류 코드	설명
모든 도구	`unavailable`	도구가 일시적으로 사용 불가
모든 도구	`execution_time_exceeded`	도구 호출이 최대 실행 시간을 초과
모든 도구	`invalid_tool_input`	도구에 유효하지 않은 매개변수 제공
모든 도구	`too_many_requests`	도구 사용량 한도(레이트 리밋) 초과
bash	`output_file_too_large`	명령 출력이 최대 크기를 초과
text_editor	`file_not_found`	파일이 존재하지 않음 (조회/편집 연산)

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

`pause_turn` 중지 사유¶

응답에는 pause_turn 중지 사유가 포함될 수 있는데, 이는 API가 오래 실행되는 턴(turn)을 일시 중지했음을 나타내요. 이후 요청에서 응답을 그대로 다시 제공해 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 매개변수 없이 요청을 다시 보내면 돼요.

예시¶

첫 요청에서 새 컨테이너에 무작위 숫자가 든 파일을 만들고, 두 번째 요청에서 컨테이너 ID를 다시 전달해 같은 컨테이너를 재사용하는 흐름을 볼게요:

client = anthropic.Anthropic()

# First request: create a file with a random number in a new container
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"}],
)

# Second request: pass the container ID back so Claude reuses the same container
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) 환경에서 동작하게 돼요. 코드 실행 도구는 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
    }
  }
}

데이터 보존¶

코드 실행은 서버 측 샌드박스 컨테이너에서 실행돼요. 실행 산출물, 업로드된 파일, 출력을 포함한 컨테이너 데이터는 최대 30일 동안 보존돼요. 이 보존은 컨테이너 환경에서 처리된 모든 데이터에 적용돼요. 코드 실행이 Files API(client.files.download()로 가져올 수 있는)에 만든 파일은 명시적으로 삭제할 때까지 유지돼요.

모든 기능에 대한 ZDR 자격은 API and data retention을 참고하세요.

다음 단계¶

Advisor tool

더 빠른 실행기 모델과 더 높은 지능의 어드바이저 모델을 짝지어, 생성 중간에 전략적 지침을 제공받아요.

프로그래매틱 도구 호출

코드 실행 컨테이너 안에서 실행되는 코드에서 여러분의 도구를 호출해요.

Files API

분석할 파일을 업로드하고 코드 실행이 만든 파일을 다운로드해요.

API에서 Agent Skills 사용하기

Agent Skills로 API를 통해 Claude의 기능을 확장하는 방법을 배워요.

호환성¶

| 지원 모델 | - Fable 5 and 5.1
- Mythos 5 and 5.1
- Opus 4.5, 4.6, 4.7, 4.8, and 5
- Sonnet 4.5, 4.6, and 5
- Haiku 4.5 | | 지원 플랫폼 | - Claude API
- Claude Platform on AWS
- Microsoft Foundry1 |

Microsoft Foundry에서 코드 실행은 Hosted on Anthropic deployment를 요구해요. ↩
모든 지원 모델은 세 가지 도구 버전을 모두 받아들여요. Claude Haiku 4.5에서는 프로그램매틱 도구 호출과 REPL 상태 유지가 지원되지 않아서, 최신 버전들이 그 모델에서는 code_execution_20250825처럼 동작해요.
Claude Mythos Preview에서는 코드 실행이 Claude API와 Microsoft Foundry에서 지원돼요.

구성 요소	레거시	현재
베타 헤더	`code-execution-2025-05-22`	필요 없음
도구 타입	`code_execution_20250522`	`code_execution_20250825` 이상
기능	Python 전용	Bash 명령, 파일 연산
응답 타입	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_*_result`

D-SKET Canvas가
정식 런칭되었습니다.

코드 실행 도구 (Code Execution Tool)¶

도구 버전¶

빠른 시작¶

코드 실행이 어떻게 동작하나요¶

언제 Claude가 코드를 실행하나요¶

파일 다루기¶

여러분의 파일 업로드 및 분석¶

파일 업로드 및 분석¶

생성된 파일 가져오기¶

생성된 파일이 어떻게 캡처되나요¶

생성 파일의 콘텐츠 크레덴셜 (Content Credentials)¶

도구 정의¶

응답 형식¶

Bash 명령 응답¶

파일 연산 응답¶

결과¶

오류¶

`pause_turn` 중지 사유¶

컨테이너¶

런타임 환경¶

리소스 제한¶

네트워킹과 보안¶

사전 설치된 라이브러리¶

컨테이너 재사용¶

예시¶

코드 실행을 다른 실행 도구와 함께 쓰기¶

스트리밍¶

배치 요청¶

사용량과 요금¶

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

무엇이 바뀌었나요¶

하위 호환성¶

업그레이드 단계¶

데이터 보존¶

다음 단계¶

호환성¶

코드 실행 도구 (Code Execution Tool)¶

도구 버전¶

빠른 시작¶

코드 실행이 어떻게 동작하나요¶

언제 Claude가 코드를 실행하나요¶

파일 다루기¶

여러분의 파일 업로드 및 분석¶

파일 업로드 및 분석¶

생성된 파일 가져오기¶

생성된 파일이 어떻게 캡처되나요¶

생성 파일의 콘텐츠 크레덴셜 (Content Credentials)¶

도구 정의¶

응답 형식¶

Bash 명령 응답¶

파일 연산 응답¶

결과¶

오류¶

pause_turn 중지 사유¶

컨테이너¶

런타임 환경¶

리소스 제한¶

네트워킹과 보안¶

사전 설치된 라이브러리¶

컨테이너 재사용¶

예시¶

코드 실행을 다른 실행 도구와 함께 쓰기¶

스트리밍¶

배치 요청¶

사용량과 요금¶

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

무엇이 바뀌었나요¶

하위 호환성¶

업그레이드 단계¶

데이터 보존¶

다음 단계¶

호환성¶

`pause_turn` 중지 사유¶