Anthropic API는 함께 사용할 때 매우 뛰어난 시너지를 내는 두 가지 강력한 기능을 제공합니다: 바로 Files API와 코드 실행(Code Execution)입니다. 처음에는 서로 별개로 보일 수 있지만, 이 둘을 결합하면 복잡한 작업을 Claude에 위임할 수 있는 정말 흥미로운 가능성이 열립니다.
Files API
Files API는 파일 업로드를 처리하는 또 다른 방법을 제공합니다. 이미지나 PDF를 메시지에 base64 데이터로 직접 인코딩하는 대신, 파일을 미리 업로드해 두고 이후에 참조할 수 있습니다.

작동 방식은 다음과 같습니다:
- 별도의 API 호출을 통해 파일(이미지, PDF, 텍스트 등)을 Claude에 업로드합니다
- 고유한 파일 ID가 포함된 파일 메타데이터 객체를 받습니다
- 이후 메시지에서 원본 파일 데이터를 포함하는 대신 해당 파일 ID를 참조합니다

이 방식은 동일한 파일을 여러 번 참조하고자 할 때나, 모든 요청에 포함시키기에는 번거로운 대용량 파일을 다룰 때 특히 유용합니다.
코드 실행 도구
코드 실행은 구현을 직접 제공할 필요가 없는 서버 기반 도구입니다. 요청에 미리 정의된 도구 스키마를 포함시키기만 하면, Claude가 격리된 Docker 컨테이너 내에서 선택적으로 Python 코드를 실행할 수 있습니다.

코드 실행 환경의 주요 특징은 다음과 같습니다:
- 격리된 Docker 컨테이너에서 실행됩니다
- 네트워크 접근이 불가능합니다(외부 API 호출 불가)
- Claude는 단일 대화 내에서 코드를 여러 번 실행할 수 있습니다
- 결과는 Claude가 캡처하고 해석하여 최종 응답에 반영합니다
Files API와 코드 실행의 결합
진정한 강력함은 이 두 기능을 함께 사용할 때 나옵니다. Docker 컨테이너는 네트워크 접근이 없기 때문에, Files API는 실행 환경으로 데이터를 넣고 빼내는 주요 수단이 됩니다.

일반적인 워크플로우는 다음과 같습니다:
- Files API를 사용하여 데이터 파일(예: CSV)을 업로드합니다
- 메시지에 파일 ID가 포함된 컨테이너 업로드 블록을 추가합니다
- Claude에게 데이터를 분석하도록 요청합니다
- Claude가 파일을 처리하기 위한 코드를 작성하고 실행합니다
- Claude는 다운로드 가능한 결과물(예: 플롯)을 생성할 수 있습니다
실제 예제
스트리밍 서비스 데이터를 사용한 실제 예제를 살펴보겠습니다. 이 CSV 파일에는 구독 등급, 시청 습관, 그리고 해지 여부(구독 취소 여부)를 포함한 사용자 정보가 들어 있습니다.

먼저, 헬퍼 함수를 사용하여 파일을 업로드합니다:
file_metadata = upload('streaming.csv')그런 다음 업로드한 파일과 분석 요청을 모두 포함하는 메시지를 작성합니다:
messages = []
add_user_message(
messages,
[
{
"type": "text",
"text": """Run a detailed analysis to determine major drivers of churn.
Your final output should include at least one detailed plot summarizing your findings."""
},
{"type": "container_upload", "file_id": file_metadata.id},
],
)
chat(
messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)응답 이해하기
Claude가 코드 실행을 사용할 때, 응답에는 여러 유형의 블록이 포함됩니다:
- 텍스트 블록 - Claude의 분석 및 설명
- 서버 도구 사용 블록 - Claude가 실행하기로 결정한 실제 코드
- 코드 실행 도구 결과 블록 - 코드 실행 결과

Claude는 단일 응답 내에서 코드를 여러 번 실행하며 점진적으로 분석을 구축해 나갈 수 있습니다. 각 실행 사이클에는 코드와 그 결과가 포함됩니다.
생성된 파일 다운로드하기
가장 강력한 기능 중 하나는 Claude가 파일(예: 플롯이나 보고서)을 생성하고 이를 다운로드 가능하게 만드는 능력입니다. Claude가 시각화 자료를 생성하면 컨테이너에 저장되며, Files API를 사용하여 이를 다운로드할 수 있습니다.
응답에서 type: "bash_code_execution_output"이 포함된 블록을 찾아보세요. 이러한 블록에는 생성된 콘텐츠의 파일 ID가 들어 있습니다:
download_file("file_id_from_response")
그 결과 수작업 코딩으로는 상당한 시간이 소요되었을 법한 전문적인 시각화 자료를 포함한 종합적인 분석 결과를 얻을 수 있습니다.
데이터 분석을 넘어서
데이터 분석은 자연스러운 활용 사례이지만, Files API와 코드 실행을 결합하면 다음과 같은 다양한 가능성이 열립니다:
- 이미지 처리 및 조작
- 문서 파싱 및 변환
- 수학적 계산 및 모델링
- 맞춤형 서식을 적용한 보고서 생성
핵심은 Files API를 통해 입력과 출력에 대한 제어권을 유지하면서도, 복잡한 연산 작업을 Claude에 위임할 수 있다는 점입니다. 이를 통해 Claude가 실제로 솔루션을 실행하고 반복적으로 개선해 나가는 코딩 어시스턴트 역할을 수행하는 강력한 워크플로우가 만들어집니다.