CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API
Claude의 기능
Code execution and the Files API
Anthropic API의 두 기능을 함께 봅니다. Files API는 파일을 미리 업로드해 두고 이후 요청에서 file_id로 참조하게 해 줍니다. 코드 실행은 Claude가 격리된 Docker 컨테이너에서 Python을 직접 돌리는 서버 도구입니다. Docker엔 네트워크가 없으므로, 둘을 결합해 CSV를 주입하고 분석·시각화까지 맡깁니다.
Stephen Grider · Anthropic 기술 스태프
이번 영상에선 Anthropic API가 제공하는 두 기능을 봅니다. 둘은 조금 별개처럼 보이지만, 사실 아주 흥미로운 방식으로 결합할 수 있습니다. 먼저 Files API가 무엇인지부터 이해해 봅시다.
앞에서 이미지를 Claude에 넘겨 해석시키는 법을 다뤘습니다. image 블록 안에 base64로 인코딩한 실제 이미지 데이터를 넣었죠. PDF 업로드도 거의 같은 방식이었습니다. Files API는 여기에 약간의 변형을 더합니다. 미리 따로 요청을 보내 파일을 — PDF든 이미지든 텍스트 파일이든 — 업로드해 둡니다. 그러면 file metadata 객체를 돌려받습니다. 이 객체엔 여러 정보가 있지만 우리에게 가장 중요한 건 file ID입니다. 이 ID로 나중에 그 업로드한 파일을 다시 참조할 수 있습니다.
그래서 나중에 사용자가 이 이미지에서 뭐가 보이냐고 물으면, image 블록 안에 raw 데이터 대신 file ID만 넣으면 됩니다. 그러면 Claude가 미리 업로드해 둔 그 파일을 찾아 해석합니다. 정리하면 Files API는 파일을 미리 올려 두고, 나중에 요청에서 그 파일을 참조하게 해 줍니다. 이미지나 PDF를 Claude에 건네는 또 하나의 방법이라고 보면 됩니다.
이제 이 영상의 다른 주제, 코드 실행으로 넘어갑니다. 코드 실행은 서버 기반 도구입니다. 그래서 우리가 실제 구현을 제공할 필요가 없습니다. 미리 정의된 tool 스키마만 넣으면 됩니다. 처음 보내는 요청에 이 특별한 스키마와 사용자 메시지를 함께 넣습니다. 그러면 뒤에서 Claude가 격리된 Docker 컨테이너 안에서 원하는 만큼 Python 코드를 실행할 수 있습니다. 여러 번 실행할 수도 있습니다. 실행 결과로 print된 것이 Claude에게 돌아가고, Claude가 그 결과를 해석해 최종 응답을 씁니다.
이 Docker 컨테이너에는 네트워크 접근이 없습니다. 즉 Claude가 네트워크 요청을 하거나 외부 API에 접근하는 코드는 쓸 수 없습니다. 그래서 컨테이너 안으로 정보를 넣고 빼려면, 방금 본 Files API와 이 코드 실행 도구를 함께 씁니다.
전체 흐름을 예로 들어 보죠. maybemydata.csv 같은 표 형식 데이터가 있고 Claude에게 분석을 맡기고 싶다고 합시다. 우리가 직접 코드를 짜서 실행하는 복잡한 과정 대신, Files API로 CSV를 먼저 업로드해 file ID를 받습니다. 그 file ID를 후속 요청에 넣되, container upload 블록을 더합니다. container upload 블록은 미리 업로드한 파일을 컨테이너 안에 넣어 달라는 뜻입니다. type은 container_upload, file_id는 업로드 때 받은 ID입니다. 그리고 별도 text 블록에 분석을 요청합니다. 그러면 Claude가 코드 실행 도구로 컨테이너 안의 그 파일에 접근해 분석 코드를 짜고, 결과를 처리해 전체 보고서를 돌려줍니다.
실제 예시를 봅시다. 005 코드 실행이라는 노트북과 streaming.csv 파일을 준비했습니다. 동영상 스트리밍 서비스의 가짜 데이터로, 사용자별 구독 등급, 총 시청 시간, 선호 장르 같은 통계가 들어 있고, 맨 끝 열은 churned입니다. 0은 구독 유지, 1은 해지를 뜻합니다. 직접 코드를 잔뜩 짜서 어떤 요인이 해지와 상관있는지 볼 수도 있지만, 그 일을 통째로 Claude에 맡기겠습니다.
노트북 헬퍼 함수 셀을 보면 upload, list_files, delete, download, 그리고 파일 정보를 가져오는 함수를 추가해 뒀습니다. 셀을 실행하고, 다음 셀에서 streaming.csv를 업로드합니다. 실행하면 file metadata 객체가 오고 그 안에 ID가 있습니다. 이 ID가 이 파일을 Claude에 식별해 주며, 이후 대화에 넣고 싶을 때 이 ID로 참조합니다.
다음 셀엔 짧은 프롬프트가 있습니다. 고객이 왜 구독을 해지하는지 상세히 분석하고, 결과를 요약하는 plot을 출력해 달라고 합니다. 그리고 container upload 블록으로 업로드한 파일을 요청에 포함합니다. 셀을 실행합니다. 코드 실행은 가끔 시간이 좀 걸립니다. 돌아오는 응답엔 엄청난 양의 텍스트가 들어 있습니다. Claude가 작성한 코드, 모든 print 출력, 그리고 최종 분석까지요. Claude는 컨테이너 안에서 코드를 여러 번 실행할 수 있어, 한 메시지 안에 코드 블록과 실행 결과가 여러 개 들어 있을 수 있습니다.
메시지가 어떻게 구성되는지 보기 좋게 정리해 봤습니다. content 리스트 안에 여러 블록이 있습니다. 첫 블록은 text로 Claude가 문제를 정리합니다. 다음은 server tool use 블록으로, 컨테이너에서 실행할 코드가 들어 있습니다. 그다음은 code execution tool result로, 실제 실행 정보 — 표준 출력, 표준 에러, 반환 코드 등 — 가 들어 있습니다. 이 경우 Claude가 이어서 코드를 더 실행해, 추가 분석과 결과가 여러 번 반복됩니다. 이 내용을 사용자에게 다 보여줄지는 애플리케이션에 따라 정하면 됩니다. 원하면 보기 좋은 보고서로 꾸밀 수도 있습니다.
마지막으로 코드 실행에서 가장 흥미로운 부분입니다. 아까 프롬프트에서 결과를 요약하는 plot 하나를 포함해 달라고 했죠. Claude는 뒤에서 이미지 파일로 plot을 생성했고, 그건 Docker 컨테이너 안에 저장돼 있습니다. 이 생성된 plot을 Files API로 다운로드할 수 있습니다. 정리한 메시지를 훑다 보면, 추가로 nested content 속성을 가진 text 블록이 보이고, 그 안에 type이 code execution output인 게 있습니다. 응답에서 안 보이면 code execution output을 검색해 보세요. 바로 그 아래 file ID가 있습니다.
그 file ID를 복사해 노트북 맨 아래 새 셀에서 download_file에 넣습니다. 영상 앞에서 본 미리 정의된 함수 중 하나죠. 실행하면 성공하고, 노트북과 같은 폴더에 PNG나 JPEG 파일이 생깁니다. 이름은 Claude가 정한 무작위에 가까운 이름입니다. 파일을 열면 Claude가 CSV에서 추출한 정보 — 시청 시간별 churn, 월 비용 구간별 churn 등 — 가 담긴 훌륭한 시각화가 보입니다.
이 데모처럼 Files API와 코드 실행 도구를 결합하면 꽤 복잡한 작업을 Claude에 통째로 맡길 수 있습니다. 물론 데이터 분석에만 한정되지 않습니다. 둘의 결합으로 다양한 작업을 실행할 수 있고, 이를 애플리케이션에 어떻게 녹일지는 여러분에게 달려 있습니다.
이 장에서 배우는 것What you'll learn
약 8분베타 헤더 — code-execution-2025-08-25 · files-api-2025-04-14
Files API: upload로 미리 올리고 file_id로 참조 (list/delete/download/metadata)
코드 실행 = 서버 도구 code_execution_20250825 — 구현 불필요
격리 Docker에서 Python 실행, 네트워크 없음
결합: upload -> container_upload 블록으로 컨테이너 주입
응답 = server_tool_use + code_execution_tool_result 반복, plot은 file_id로 다운로드
file_id로 참조. raw 데이터를 매번 안 보내도 된다.file_id 지정).Files API는 파일을 미리 업로드해 두고 이후 요청에서 file_id로 참조하게 합니다. 코드 실행은 Claude가 격리 Docker에서 Python을 직접 돌리는 서버 도구입니다. 둘 다 베타라 클라이언트에 헤더를 답니다.
from anthropic import Anthropic # 두 기능 모두 베타 — 헤더로 활성화 client = Anthropic(default_headers={ "anthropic-beta": "code-execution-2025-08-25, files-api-2025-04-14" }) model = "claude-sonnet-4-5-20250929"
헬퍼 셀엔 Files API 함수들을 추가합니다. upload는 확장자로 mime 타입을 정해 client.beta.files.upload를 호출하고, 그 밖에 list_files·delete_file·download_file·get_metadata가 있습니다.
from pathlib import Path def upload(file_path): path = Path(file_path) extension = path.suffix.lower() mime_type_map = {".csv": "text/csv", ".pdf": "application/pdf", ".png": "image/png", ".txt": "text/plain", ...} mime_type = mime_type_map.get(extension) with open(file_path, "rb") as file: return client.beta.files.upload(file=(path.name, file, mime_type)) def list_files(): return client.beta.files.list() def delete_file(id): return client.beta.files.delete(id) def get_metadata(id): return client.beta.files.retrieve_metadata(id) def download_file(id, filename=None): file_content = client.beta.files.download(id) if not filename: filename = get_metadata(id).filename file_content.write_to_file(filename)
예시 데이터는 streaming.csv — 스트리밍 서비스의 가짜 데이터입니다. 맨 끝 열 churned가 0(유지)/1(해지)입니다. 직접 분석 코드를 짜는 대신, 파일을 업로드해 file metadata를 받고, 그 안의 id를 챙깁니다.
# streaming.csv = 동영상 스트리밍 서비스의 가짜 데이터 # 사용자별 구독 등급, 시청 시간, 선호 장르 ... 마지막 열 churned(0/1) file_metadata = upload("streaming.csv") file_metadata # -> FileMetadata(id="file_011C...", filename="streaming.csv", ...) # 이 id 로 나중에 파일을 참조한다
raw 데이터를 매 요청마다 인코딩해 보내는 대신, 한 번 올려 두고 file_id로 가리킵니다. 같은 파일을 여러 요청에서 재사용하기 좋습니다.
이제 container_upload 블록으로 그 파일을 컨테이너에 주입하고, 분석을 요청합니다. tools엔 코드 실행 스키마만 넣으면 됩니다 — 구현은 필요 없습니다.
messages = []
add_user_message(messages, [
{"type": "text", "text": """
이탈(churn)의 주요 원인을 상세히 분석하세요.
최종 출력에는 결과를 요약하는 plot 을 최소 1개 포함하세요.
주의: 코드를 실행할 때마다 완전히 새 상태에서 시작합니다.
이전 실행의 변수/임포트는 남지 않으니 매번 다시 선언/임포트하세요.
"""},
{"type": "container_upload", "file_id": file_metadata.id},
])
chat(messages, tools=[{
"type": "code_execution_20250825",
"name": "code_execution",
}])응답엔 엄청난 양이 들어옵니다. text로 문제를 정리하고, server_tool_use로 실행할 코드를, code_execution_tool_result로 stdout·stderr·return_code를 담는데, 이것이 여러 번 반복될 수 있습니다.
[ text Claude 가 문제를 정리
server_tool_use 실행할 Python 코드
code_execution_tool_result stdout / stderr / return_code
server_tool_use 추가 분석 코드
code_execution_tool_result ... <- 여러 번 반복
text 최종 분석 요약
+- content: code_execution_output(file_id="file_011CPYZ...") ]Claude가 그린 plot은 컨테이너 안의 이미지 파일입니다. 응답을 훑어 code_execution_output의 file_id를 찾아 download_file로 내려받습니다.
# 응답 속 code_execution_output 의 file_id 로 plot 다운로드 # (컨테이너 안에서 Claude 가 그린 이미지 파일) download_file("file_011CPYZqxoMSsfbrSzFw8j9X") # -> 노트북과 같은 폴더에 PNG 저장. Claude 가 정한 이름.
한 메시지 안에서 3~5단계가 자동으로 일어납니다. 우리가 짜는 코드는 업로드·요청·다운로드뿐 — 컨테이너에서의 코드 작성·실행은 Claude가 합니다.
default_headers에 code-execution-2025-08-25, files-api-2025-04-14.upload로 미리 올리고 받은 file_id로 참조(list/delete/download/metadata).code_execution_20250825) — 구현 없이 스키마만. 격리 Docker, 네트워크 없음.container_upload로 컨테이너 주입 -> server_tool_use/code_execution_tool_result 반복 -> plot은 file_id로 다운로드.Q1Files API는 무엇에 쓰나요?
업로드 시 받는 file metadata의 file_id로 이후 요청에서 파일을 가리킵니다.
Q2코드 실행 도구의 핵심 제약은?
외부 API에 접근할 수 없어, 데이터 입출력은 Files API와 결합해 처리합니다. 코드는 여러 번 실행될 수 있습니다.
Q3업로드한 CSV를 컨테이너 안에서 분석시키려면 요청에 무엇을 넣나요?
container_upload로 미리 올린 파일을 컨테이너에 주입하고, 코드 실행 도구로 Claude가 그 파일을 분석합니다. Docker엔 네트워크가 없습니다.
이로써 Claude의 고급 기능들을 모두 살펴봤습니다 — 확장된 사고부터 코드 실행까지. 다음은 배운 내용을 점검하는 섹션 퀴즈입니다. -> Claude 기능 퀴즈
전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 76개 레슨을 끝까지 읽을 수 있습니다.
이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.