코드 실행 도구
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에게 계산을 수행하도록 요청하는 간단한 예제입니다:
코드 실행 작동 방식
API 요청에 코드 실행 도구를 추가하면:
- Claude는 코드 실행이 질문에 답하는 데 도움이 될지 평가합니다
- 도구는 자동으로 Claude에게 다음 기능을 제공합니다:
- Bash 명령: 시스템 작업 및 패키지 관리를 위한 셸 명령 실행
- 파일 작업: 코드 작성을 포함하여 파일을 직접 생성, 보기 및 편집
- Claude는 단일 요청에서 이러한 기능의 조합을 사용할 수 있습니다
- 모든 작업은 안전한 샌드박스 환경에서 실행됩니다
- Claude는 생성된 차트, 계산 또는 분석과 함께 결과를 제공합니다
도구 사용 방법
Bash 명령 실행
Claude에게 시스템 정보를 확인하고 패키지를 설치하도록 요청하세요:
파일 직접 생성 및 편집
Claude는 파일 조작 기능을 사용하여 샌드박스에서 파일을 직접 생성, 보기 및 편집할 수 있습니다:
자신의 파일 업로드 및 분석
자신의 데이터 파일(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 요청에 코드 실행 도구 포함
생성된 파일 검색
Claude가 코드 실행 중에 파일을 생성할 때 Files API를 사용하여 이러한 파일을 검색할 수 있습니다:
작업 결합
모든 기능을 사용하는 복잡한 워크플로:
도구 정의
코드 실행 도구는 추가 매개변수가 필요하지 않습니다:
이 도구가 제공되면 Claude는 자동으로 두 개의 하위 도구에 액세스할 수 있습니다:
bash_code_execution
: 셸 명령 실행text_editor_code_execution
: 코드 작성을 포함하여 파일 보기, 생성 및 편집
응답 형식
코드 실행 도구는 작업에 따라 두 가지 유형의 결과를 반환할 수 있습니다:
Bash 명령 응답
파일 작업 응답
파일 보기:
파일 생성:
파일 편집 (str_replace):
결과
모든 실행 결과에는 다음이 포함됩니다:
stdout
: 성공적인 실행의 출력stderr
: 실행이 실패할 경우 오류 메시지return_code
: 성공의 경우 0, 실패의 경우 0이 아닌 값
파일 작업에 대한 추가 필드:
- 보기:
file_type
,content
,numLines
,startLine
,totalLines
- 생성:
is_file_update
(파일이 이미 존재했는지 여부) - 편집:
oldStart
,oldLines
,newStart
,newLines
,lines
(diff 형식)
오류
각 도구 유형은 특정 오류를 반환할 수 있습니다:
공통 오류 (모든 도구):
도구 유형별 오류 코드:
도구 | 오류 코드 | 설명 |
---|---|---|
모든 도구 | 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)
리소스 제한
- 메모리: 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 요청에서 기존 컨테이너를 재사용할 수 있습니다. 이를 통해 요청 간에 생성된 파일을 유지할 수 있습니다.
예제
스트리밍
스트리밍이 활성화되면 코드 실행 이벤트가 발생할 때 수신됩니다:
배치 요청
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-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 코드 실행은 이전과 정확히 동일하게 계속 작동합니다
- 기존 Python 전용 워크플로에는 변경이 필요하지 않습니다
업그레이드 단계
업그레이드하려면 API 요청에서 다음 변경 사항을 수행해야 합니다:
-
베타 헤더 업데이트:
-
도구 유형 업데이트:
-
응답 처리 검토 (응답을 프로그래밍 방식으로 구문 분석하는 경우):
- Python 실행 응답에 대한 이전 블록은 더 이상 전송되지 않습니다
- 대신 Bash 및 파일 작업에 대한 새로운 응답 유형이 전송됩니다 (응답 형식 섹션 참조)