목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Programmatic Tool Calling 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling 마지막 확인: 2026-06-02
1. 한 줄 요약 #
Claude에게 도구를 20번 부탁하지 마세요. “이 20가지를 다 처리해서 결과만 알려달라"고 한 번에 부탁할 수 있습니다.
2. 무엇이고 왜 좋을까 #
도구를 하나하나 시키는 대신, Claude가 직접 짧은 코드를 써서 여러 도구를 한 번에 돌리는 방식입니다.
마트에서 장 보는 것과 같습니다. 항목 하나 살 때마다 집에 다녀오면 종일 걸리지만, 목록을 들고 한 번에 다녀오면 한 시간이면 끝나죠. Programmatic Tool Calling(코드로 도구 부르기, 줄여서 PTC)은 Claude에게 “목록 들고 한 번에 다녀와"라고 말하는 방법입니다.
기존에는 도구를 부를 때마다 Claude에게 다시 물어보고, Claude가 답을 보고, 또 다음 도구를 부르고… 이 왕복을 매번 반복했습니다. PTC는 Claude가 작은 파이썬 코드 한 덩어리를 써서 도구를 여러 번 돌린 뒤, 정리된 결과만 보고합니다.
핵심 수치 하나: 공식 문서 예시에 따르면, 도구 10개를 하나씩 부르는 방식보다 코드로 묶어서 부르면 토큰 사용량이 약 1/10로 줄어듭니다. 시간도 토큰도 함께 아끼는 셈입니다.
3. 이런 상황에서 써요 #
이 글의 심장입니다. PTC가 빛나는 일상·업무 시나리오 세 가지를 보여드릴게요.
상황 1: 한 학기 성적표 정리하는 학생 #
“이번 학기 수강한 과목 12개의 점수를 과목별로 조회해서, 평균이 90점 넘는 과목만 추려달라"고 부탁하고 싶다고 해볼게요.
기존 방식이라면 Claude가 “1교시 점수 알려줘”, “2교시 점수 알려줘”… 이렇게 12번 왔다 갔다 하면서 12과목 점수를 전부 본 다음에야 평균을 냅니다. PTC를 쓰면 Claude가 짧은 코드를 짜서 점수 12개를 모두 가져와 평균을 직접 계산하고, “3과목이 90점을 넘었어요"라는 깔끔한 한 줄만 돌려줍니다. 중간의 시시콜콜한 점수들은 보고서에 끼어들지 않습니다.
상황 2: 사내 출장비 점검을 맡은 사무직 직원 #
부서원 20명의 이번 달 출장비를 조회해서 한도를 넘은 사람만 알려달라고 하는 상황입니다.
원래대로면 직원 한 명씩 출장비 내역을 다 받아 본 뒤, 그 수많은 영수증 정보를 Claude가 일일이 읽으며 비교해야 합니다. PTC를 쓰면 Claude가 “20명 조회 → 한도와 비교 → 초과자만 정리"하는 코드를 한 번에 돌리고, “초과한 분은 김씨와 박씨 두 분입니다” 같은 깔끔한 결론만 보고합니다. 수백 줄짜리 영수증 데이터를 안 봐도 되니 답변도 훨씬 빠릅니다.
상황 3: 책 여러 권에서 한 주제를 모으는 일반 독자 #
좋아하는 작가의 책 다섯 권에서 “행복"이라는 단어가 나오는 부분만 모아 보고 싶다고 해볼게요.
도구를 하나하나 시켰다면 다섯 권을 각각 검색해 결과를 다 받아 보느라 시간이 오래 걸렸을 겁니다. PTC로 부탁하면 Claude가 다섯 권을 차례로 훑어 “행복” 문장만 골라 모은 뒤, 정리된 인용 모음만 보여줍니다. 중간에 책 전체 내용이 끼어들지 않으니 답도 빠르고 답변도 깔끔합니다.
4. 가볍게 시작하기 #
💻 개발 경험 있으신가요? 아래 코드는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “아, 이렇게 한 번에 시키는구나” 정도로 보고 넘어가셔도 충분합니다.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
messages=[{
"role": "user",
"content": "서울·부산·대구 지점 매출을 조회해서 가장 잘 판 지점을 알려줘",
}],
tools=[
# ① 코드 실행 도구 — Claude가 짧은 코드를 돌릴 작업 공간
{"type": "code_execution_20260120", "name": "code_execution"},
# ② 실제 일감 — 매출 조회 도구
{
"name": "query_sales",
"description": "지점 이름을 받아 그 지점의 매출(JSON)을 돌려줍니다.",
"input_schema": {
"type": "object",
"properties": {"branch": {"type": "string"}},
"required": ["branch"],
},
# ↓ 이 한 줄이 핵심! "이 도구는 Claude가 코드 안에서 부를 거예요"
"allowed_callers": ["code_execution_20260120"],
},
],
)
print(response)핵심은 allowed_callers 한 줄입니다. 이 줄이 있어야 Claude가 “아, 이 도구는 내가 직접 코드로 묶어서 호출해도 되는구나"라고 알아챕니다. 이게 없으면 예전처럼 한 번에 하나씩만 부탁하는 방식으로 돌아갑니다. 그래서 매번 도구 정의 마지막에 이 한 줄을 잊지 않으면 됩니다.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “도구만 만들어두면 알아서 코드로 묶어 부르겠죠?” #
아니요. 위에서 본 allowed_callers 한 줄을 빼먹으면 Claude는 예전 방식대로 하나씩 부릅니다. PTC의 효과를 보고 싶다면 묶어 부르고 싶은 도구마다 이 옵션을 적어두는 걸 잊지 마세요. 깜빡하면 평소처럼 동작할 뿐 에러가 나지는 않아 더 헷갈리기 쉽습니다.
⚠️ 함정 2: “도구 결과를 보내면서 ‘다음엔 이거 해줘’라고 같이 적어도 되죠?” #
여기는 평소와 다릅니다. Claude가 코드로 도구를 부른 상황에서는 도구 결과만 돌려보내야 합니다. 같은 메시지에 “이제 뭐 할까?” 같은 텍스트를 끼워 넣으면 거절당합니다.
❌ 도구 결과 + 추가 질문 메시지를 한 번에 보내기 ✅ 도구 결과만 보내기 → Claude가 코드 마저 돌리고 답을 보내면 그때 다음 질문
이 규칙은 PTC 상황에서만 적용됩니다. 평소 도구 사용은 자유롭게 글자도 같이 보낼 수 있어요.
⚠️ 함정 3: “도구가 답하는 데 시간이 좀 걸려도 괜찮겠죠?” #
PTC는 Claude의 코드가 도구의 답을 기다리며 잠시 멈춰 있는 구조라, 너무 오래 걸리면 작업 공간(컨테이너)이 닫혀버립니다. 기준은 약 4분 30초의 휴식 시간. 도구가 그 안에 답을 못 주면 시간 초과로 처리되고, Claude가 다시 시도하느라 답이 늦어집니다. 도구가 오래 걸린다면 작업을 더 잘게 쪼개 보세요.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
같은 일을 PTC가 있을 때와 없을 때 비교한 표입니다.
| 항목 | 기존 방식 (도구 하나씩) | PTC 방식 (코드로 묶어 부르기) |
|---|---|---|
| 도구를 20번 부르는 데 걸리는 모델 왕복 | 20번 | 1번 |
| Claude가 봐야 하는 데이터 | 20명의 모든 상세 내역 | 정리된 결론 한두 줄 |
| 토큰 사용량 (10개 도구 기준) | 기준 | 약 1/10 |
| 어울리는 작업 | 한 번에 하나만 묻기 | 여러 번 묶어 처리하기 |
| 어울리지 않는 작업 | — | 도구를 딱 한 번만 부를 때 |
여기서 한 가지 더. Claude가 코드 안에서 도구 결과를 받은 다음 조건에 따라 멈출 수도 있습니다. 예를 들어 “건강한 서버를 찾으면 거기서 멈춰"라고 말하면 이런 식으로 코드를 짭니다.
# Claude가 코드 안에서 이렇게 처리합니다 (개념 예시)
for region in ["서울", "부산", "대구"]:
status = await check_health(region)
if status == "정상":
print(f"정상인 지점 찾음: {region}")
break # ← 더 이상 다른 지점은 확인하지 않음이 한 줄짜리 break 덕에 나머지 도구 호출을 아예 건너뜁니다. 작은 차이 같지만, 도구가 10개 있을 때 9번을 아낄 수 있으니 답변 속도가 눈에 띄게 빨라집니다.
언제 PTC가 어울리고 어울리지 않을까요? 도구를 3개 이상 이어 부를 때, 큰 데이터에서 일부만 추릴 때, 여러 항목을 한꺼번에 처리할 때는 PTC가 빛납니다. 반대로 도구를 딱 한 번만 부르면 되거나 매 단계마다 사용자 확인이 필요한 작업이라면 굳이 PTC로 묶을 필요는 없습니다.
7. 한 마디 #
처음 보면 “도구를 코드로 부른다고?” 하고 어렵게 느껴질 수 있습니다. 하지만 사실은 **“한 번에 묶어서 해줘”**라는 한마디를 Claude가 알아들을 수 있게 만든 옵션 하나(allowed_callers)일 뿐입니다. 막혔을 때는 위 함정 셋 중 하나일 가능성이 큽니다 — 옵션 빼먹지 않았는지, 도구 결과만 보내고 있는지, 도구가 너무 늦지 않은지 확인해 보세요.
다음 시리즈 #24에서는 Fine-grained Tool Streaming(도구 호출도 토막토막 실시간으로 받기) 을 다룰 예정입니다. 도구를 부르는 모습을 실시간으로 지켜보고 싶은 분께 잘 어울리는 기능이에요.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
