코드 실행: Claude가 직접 작성한 코드를 실행합니다

이 영상의 데모는 2026년 9월에 녹화되었습니다. Claude Sonnet 5 (claude-sonnet-5)에서 실행되었습니다. 최신 모델에서는 결과가 다를 수 있습니다.

일부 질문은 여러 파일에 걸친 계산이 필요합니다. 이는 코드가 해결할 일입니다.

가상의 엔지니어링 컨설팅 회사인 Meridian을 예로 들어보겠습니다. 이 회사는 펌프장마다 하나씩, 총 12개의 CSV 파일을 보유하고 있으며, 각 파일에는 1년치 유량 측정값이 담겨 있습니다. 이 회사는 어느 펌프장이든 설계 용량을 초과한 적이 있는지, 있다면 언제였는지 알고 싶어 합니다.

코드 실행은 Claude가 이 작업을 해내는 방법입니다. Claude는 자신이 작성한 Python 코드를 실행할 수 있는 컨테이너를 받고, 그 코드가 출력한 내용을 바탕으로 답변합니다.

요청에 도구 추가하기

코드 실행은 서버 도구, 즉 Anthropic의 인프라에서 실행되는 도구입니다. 이 도구를 위한 핸들러를 직접 작성할 필요가 없으며, 코드에서 tool_result를 다시 보낼 필요도 없습니다.

코드 실행을 추가하려면 tools 목록에 항목 하나만 추가하면 됩니다. 항목의 type 끝에 있는 날짜는 도구의 버전이며, Meridian은 code_execution_20260120을 사용합니다. 현재 버전들은 도구 참조 문서에 나와 있으므로, 거기서 type 값을 복사하세요.

Meridian은 이 목록을 TOOLS라는 상수로 유지하며, 요청에서 이를 tools=TOOLS로 전달합니다:

TOOLS = [{"type": "code_execution_20260120", "name": "code_execution"}]

2026년 10월 기준으로, 코드 실행은 Claude API, AWS의 Claude Platform, Anthropic이 관리하는 Google Cloud의 Claude 모델, 그리고 Anthropic에서 호스팅하는 Microsoft Foundry 배포에서 실행됩니다.

파일을 컨테이너에 넣기

Claude의 코드는 Anthropic 측의 컨테이너에서 실행됩니다. 파일은 여전히 사용자의 컴퓨터에 있으므로, 컨테이너는 아직 그 파일을 가지고 있지 않습니다. Meridian의 프로그램은 두 단계를 거쳐 파일을 컨테이너에 전달합니다:

1. Files API를 사용해 각 파일을 업로드하면 파일 ID를 돌려받습니다.
2. 그 파일 ID를 메시지 안의 container_upload 블록에 넣습니다.

Meridian의 프로그램은 질문과 같은 메시지 안에, 파일마다 하나씩 container_upload 블록을 추가합니다. 그러면 파일들이 컨테이너에 로드되어, Claude의 코드가 이를 열 수 있게 됩니다.

Claude의 답변 읽기

코드는 요청을 한 번 보내고 보통은 완성된 답변을 바로 돌려받습니다.

API는 장시간 실행되는 턴을 일시 중지하고 stop_reason을 pause_turn으로 반환할 수 있습니다. 이런 경우, 응답의 content를 동일한 tools와 함께 assistant 메시지로 다시 보내면 Claude가 작업을 이어갑니다.

Meridian에 대한 Claude의 답변은 7번 펌프장이 설계 용량인 600 L/s를 2025년 4월과 5월, 두 차례 초과했다는 것입니다. 응답에서는 이 답변이 Claude가 실행한 명령들 뒤에 나옵니다.

프로그램 조립하기

아래 Meridian의 프로그램은 도구를 추가하고, 파일을 컨테이너에 넣고, 답변을 읽어옵니다. 프로그램 안에서 paths는 12개의 CSV 파일을 pathlib.Path 객체로 담고 있으며, QUESTION은 Meridian의 질문을 담고 있습니다.

핵심 요약

• 코드 실행은 서버 도구입니다. tools에 항목 하나를 추가하면, Claude의 코드가 Anthropic 측 컨테이너에서 실행됩니다.
• Files API로 각 파일을 업로드한 다음, 그 파일 ID를 container_upload 블록에 넣으세요.