코드 실행 도구
Claude가 안전한 샌드박스 환경에서 Python 코드를 실행할 수 있게 해주는 코드 실행 도구에 대해 알아보세요.
코드 실행 도구는 Claude가 안전한 샌드박스 환경에서 Python 코드를 실행할 수 있게 해줍니다. Claude는 데이터를 분석하고, 시각화를 생성하며, 복잡한 계산을 수행하고, 업로드된 파일을 API 대화 내에서 직접 처리할 수 있습니다.
코드 실행 도구는 현재 베타 버전입니다.
이 기능을 사용하려면 베타 헤더가 필요합니다: "anthropic-beta": "code-execution-2025-05-22"
지원되는 모델
코드 실행 도구는 다음 모델에서 사용할 수 있습니다:
- 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는 안전한 샌드박스 환경에서 Python 코드를 작성하고 실행합니다
- 단일 요청 중에 코드 실행이 여러 번 발생할 수 있습니다
- Claude는 생성된 차트, 계산 또는 분석과 함께 결과를 제공합니다
도구 정의
코드 실행 도구는 추가 매개변수가 필요하지 않습니다:
응답 형식
다음은 코드 실행이 포함된 응답 예제입니다:
결과
코드 실행 결과에는 다음이 포함됩니다:
stdout
: print 문과 성공적인 실행의 출력stderr
: 코드 실행이 실패할 경우 오류 메시지return_code
(성공 시 0, 실패 시 0이 아닌 값)
오류
도구 사용 중 오류가 발생하면 code_execution_tool_result_error
가 나타납니다
가능한 오류는 다음과 같습니다
unavailable
: 코드 실행 도구를 사용할 수 없음code_execution_exceeded
: 실행 시간이 허용된 최대 시간을 초과함container_expired
: 컨테이너가 만료되어 사용할 수 없음
pause_turn
중지 이유
응답에는 pause_turn
중지 이유가 포함될 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다.
Claude가 턴을 계속하도록 하려면 응답을 그대로 후속 요청에 제공하거나, 대화를 중단하려면 내용을 수정할 수 있습니다.
코드 실행에서 파일 작업
코드 실행은 CSV 파일, Excel 파일 및 기타 데이터 형식과 같이 Files API를 통해 업로드된 파일을 분석할 수 있습니다. 이를 통해 Claude는 데이터를 읽고, 처리하고, 인사이트를 생성할 수 있습니다. 요청당 여러 파일을 전달할 수 있습니다.
코드 실행과 함께 Files API를 사용하려면 두 개의 베타 헤더가 필요합니다: "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"
지원되는 파일 유형
Python 환경은 다음 파일 유형과 작업할 수 있지만 이에 국한되지 않습니다
- CSV
- Excel (.xlsx, .xls)
- JSON
- XML
- 이미지 (JPEG, PNG, GIF, WebP)
- 텍스트 파일 (.txt, .md, .py 등)
코드 실행을 위한 파일 로드
- Files API를 사용하여 파일 업로드
container_upload
콘텐츠 블록을 사용하여 메시지에서 파일 참조- API 요청에 코드 실행 도구 포함
코드 실행으로 생성된 파일 검색
Claude가 코드 실행 중에 파일을 생성할 때(예: matplotlib 플롯 저장, CSV 생성), Files API를 사용하여 이러한 파일을 검색할 수 있습니다:
컨테이너
코드 실행 도구는 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
- 파일 처리: pyarrow, openpyxl, xlrd, pillow
- 수학 및 컴퓨팅: sympy, mpmath
- 유틸리티: tqdm, python-dateutil, pytz, joblib
컨테이너 재사용
이전 응답의 컨테이너 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.