Claude Tool Use 완전 실전 가이드 — Function Calling JSON 스키마부터 Agentic Loop·Parallel까지
LLM이 "외부 도구를 부리는" 시대에 들어선 가장 큰 기술적 전환점이 Tool Use(Function Calling) 다. Claude는 사용자 요청을 분석해 적절한 도구를 호출하고, 그 결과를 다시 받아 다음 작업을 결정하는 에이전틱 루프를 자체적으로 돌릴 수 있다. 데이터베이스 조회·외부 API 호출·파일 시스템 작업 같은 행위를 LLM이 직접 수행하는 워크플로우의 표준 메커니즘이다.
이 글은 Claude Tool Use의 작동 원리, 도구를 정의하는 JSON 스키마 구조, 4가지 tool_choice 옵션, 병렬 도구 호출(parallel tool use), 그리고 에이전트형 워크플로우 전체 사이클(loop)을 실전 코드와 함께 정리한다.
01 Tool Use가 작동하는 원리
Tool Use는 Claude에게 "이런 도구가 있다"는 정의를 미리 전달하고, Claude가 필요한 시점에 그 도구를 호출하는 메커니즘이다. 응답이 일반 텍스트가 아니라 구조화된 tool_use 블록으로 돌아오면, 애플리케이션이 실제 도구를 실행하고 결과를 다시 Claude에게 전달한다.
Agentic Loop — 4단계 사이클
1. 요청
tools + user message
2. tool_use 응답
stop_reason="tool_use"
3. 도구 실행
앱이 실제 함수 호출
4. tool_result 전송 → Claude 최종 응답 (또는 다시 1번으로)
stop_reason="end_turn" 될 때까지 반복
💡 핵심 — 도구는 클라이언트가 실행
Anthropic 서버가 직접 도구를 실행하는 게 아니라, Claude가 "이 도구를 이런 인자로 호출해 달라"고 요청하고 클라이언트(애플리케이션)가 실제 실행한 뒤 결과를 다시 전달한다. 보안·인증·인프라가 모두 사용자 측에 머문다.
02 Tools 정의 — JSON 스키마
도구는 tools 배열에 각 도구의 name·description·input_schema(JSON Schema 형식)를 정의한다. Claude는 description을 읽고 언제 어떤 인자로 호출할지 결정한다.
# Python SDK — 도구 정의 예시
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "특정 도시의 현재 날씨를 조회한다.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "도시 이름 (예: Seoul)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "온도 단위"
}
},
"required": ["city"]
}
}
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "서울 날씨 알려줘"}
]
)
# response.stop_reason == "tool_use"
# response.content에 tool_use 블록 포함
| 필드 | 필수 | 설명 |
|---|---|---|
| name | 필수 | 도구 식별자. 영문·언더스코어만. 한 응답에 중복 X |
| description | 필수 | 언제·왜 호출할지 명확히 — Claude의 선택 근거 |
| input_schema | 필수 | JSON Schema 형식. properties·required·enum 활용 |
| cache_control | 선택 | Tools 정의 캐싱 (반복 호출 시 비용 절감) |
03 tool_choice — 4가지 선택 옵션
tool_choice 파라미터로 Claude가 도구를 사용하는 강도를 제어한다. 자동·강제·특정·해제 네 가지 옵션이 있다.
auto (기본값)
Claude가 도구 사용 여부를 자유롭게 결정. 일반 텍스트 응답·도구 호출 모두 가능.
any
반드시 도구 중 하나를 사용. 어떤 도구를 선택할지는 Claude가 결정.
tool (특정 도구)
{type: "tool", name: "X"} 형식으로 X 도구를 강제 사용. 단일 도구 강제 시.
none
도구 사용 금지. tools 배열은 정의되어 있어도 호출 안 함. 일반 응답만.
04 Agentic Loop — 전체 코드 예시
요청 → tool_use 응답 → 도구 실행 → tool_result → 최종 응답까지의 한 사이클을 코드로 구현하면 다음과 같다.
# Agentic Loop 전체 사이클
def get_weather(city: str, unit: str = "celsius") -> dict:
# 실제 외부 API 호출 (생략)
return {"city": city, "temp": 18, "unit": unit}
messages = [{"role": "user", "content": "서울 날씨 알려줘"}]
while True:
response = client.messages.create(
model="claude-sonnet-4-6", max_tokens=1024,
tools=tools, messages=messages
)
if response.stop_reason == "end_turn":
# Claude가 최종 응답 → 루프 종료
print(response.content[0].text)
break
if response.stop_reason == "tool_use":
# assistant 응답 누적
messages.append({"role": "assistant", "content": response.content})
tool_results = []
for block in response.content:
if block.type == "tool_use":
# 실제 도구 실행
result = get_weather(**block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
})
# 사용자 메시지로 tool_result 전송
messages.append({"role": "user", "content": tool_results})
05 Parallel Tool Use — 병렬 호출
Claude 4.x 모델은 한 번의 응답에서 여러 도구를 동시에 호출할 수 있다. 독립적인 작업을 묶어 한 번에 받아 처리하면 라운드트립이 줄어든다.
Parallel Tool Use 예시
사용자 질문
"서울·부산·도쿄 날씨를 한 번에 알려줘"
Claude 응답
3개의 get_weather() 호출을 동시에 반환
| 옵션 | 동작 |
|---|---|
| 기본값 (Claude 4.x) | 병렬 호출 활성 |
| disable_parallel_tool_use=true | 한 번에 1개 도구만 (tool_choice any/tool 시) |
| Claude 3.7 이하 | 병렬 호출 빈도 낮음, 베타 헤더로 활성 |
Tool Use는 LLM을 단순 텍스트 생성기에서
에이전트로 격상시키는 핵심 메커니즘이다.
DB 조회·외부 API·파일 작업·MCP 서버 모두 같은 패턴으로 통합된다.
06 실전 함정 5가지
① description 부실
"이 함수는 데이터를 가져온다" 같은 모호한 설명 → Claude가 잘못된 시점에 호출. 언제·왜·어떤 결과를 반환하는지 명시.
② required 누락
JSON Schema에 required 배열 누락 → Claude가 인자 일부를 생략. 필수 인자는 명시.
③ tool_result content 형식
tool_result content는 문자열 또는 content 블록 배열이어야 함. dict 객체 직접 넘기면 오류.
④ 무한 루프
에러가 반복되거나 도구가 영구히 실패하면 무한 루프. 최대 반복 횟수·타임아웃 설정 필수.
⑤ Tools 캐싱 누락
Tools 정의는 매 호출마다 같은데 cache_control 적용 안 하면 매번 새로 토큰 비용 발생. 반복 호출 시스템은 tools 마지막 블록에 cache_control 추가.
07 Q&A 자주 묻는 질문 5가지
QTool Use와 MCP의 차이는 무엇인가요?
ATool Use는 Anthropic API의 기본 메커니즘. MCP(Model Context Protocol)는 더 상위 표준으로, 도구 서버를 외부 프로세스로 분리하고 여러 클라이언트(Claude Code·Cursor 등)에서 공유 사용 가능하게 한다. 단일 앱에선 Tool Use, 여러 도구 호스팅이라면 MCP.
QTools 정의가 너무 많으면 안 되나요?
A20개 이상은 Claude가 선택을 혼동할 수 있다. 권장은 5～10개 핵심 도구. 그 이상은 컨텍스트별로 동적으로 tools 배열을 분기해 제공하거나, MCP로 서버 분리.
Qtool_use 응답에 텍스트도 함께 오나요?
A그렇다. content 배열에 text 블록과 tool_use 블록이 함께 들어올 수 있다. "이 정보가 필요하니 X 도구를 호출하겠다" 같은 추론 텍스트 + 실제 tool_use 호출.
Q도구 실행이 실패하면 어떻게 처리하나요?
Atool_result 블록에 "is_error": true 와 에러 메시지를 함께 보내면 Claude가 인지하고 재시도·다른 접근을 모색한다. 단순 무시하면 Claude는 작업 완료로 판단할 수 있어 위험.
QStreaming과 Tool Use를 함께 쓸 수 있나요?
A가능하다. SSE 스트리밍 중 tool_use 블록이 부분적으로 전송되며, 클라이언트는 input_json_delta 이벤트를 누적해 인자를 조립한다. 다만 도구 실행은 input이 완성된 뒤에 시작해야 한다.
결론
Tool Use는 LLM이 단순 텍스트 생성기에서 에이전트로 진화하는 결정적 메커니즘이다.
기본 패턴 — tools 배열 정의 → user message → tool_use 응답 → 실제 함수 실행 → tool_result 반환 → 최종 응답. 이 사이클을 stop_reason="end_turn"까지 반복.
핵심 파라미터 — tool_choice(auto/any/tool/none)로 강제력 제어, disable_parallel_tool_use로 병렬 차단, cache_control로 tools 정의 캐싱.
실전 함정 — description 부실·required 누락·tool_result 형식 오류·무한 루프 가능성·Tools 캐싱 누락. 다섯 가지 모두 사전에 점검.
✅ Tool Use 구현 체크리스트
본 글은 정보 정리·교육 목적이며 Anthropic의 공식 가이드를 갈음하지 않는다. Tool Use API 사양은 수시 변경되므로 구현 직전 platform.claude.com/docs/en/agents-and-tools/tool-use/overview 공식 문서를 확인해야 한다.
#ClaudeToolUse #FunctionCalling #JSONSchema #AgenticLoop #tool_choice #ParallelToolUse #AnthropicAPI #Sonnet4.6 #LLMAgent #stop_reason #tool_result #MCP비교 #에이전트 #ClaudeAPI #ToolDefinition
댓글