AI 에이전트 개발

Claude API Tool Use 완전 가이드 — AI가 외부 함수를 직접 호출하는 법

Tool Use(도구 사용, 함수 호출)는 Claude가 텍스트만 생성하는 단계를 넘어 실제 코드, 검색 엔진, 데이터베이스와 상호작용하게 만드는 Anthropic의 핵심 기능입니다. 자율 에이전트를 만들려면 반드시 이해해야 할 개념을 처음부터 끝까지 정리합니다.

2026년 6월 1일 AI 에이전트 개발

Tool Use란 무엇인가

일반적인 LLM 호출은 텍스트 입력 → 텍스트 출력으로 끝납니다. 하지만 현실의 AI 애플리케이션은 이것만으로 부족합니다. 최신 주가를 조회하거나, 파일을 읽거나, 외부 API를 호출해야 할 때 단순한 텍스트 생성은 한계에 부딪힙니다.

Tool Use(도구 사용)는 Claude가 개발자가 미리 정의해둔 함수의 이름과 인수를 JSON 형태로 출력하게 하는 기능입니다. 실제 함수 실행은 여전히 개발자 코드가 담당하고, Claude는 "어떤 함수를 어떤 인수로 호출해야 하는지" 결정을 내립니다.

한 줄 정의

Tool Use = Claude가 스스로 필요한 함수를 결정하고 호출 인수를 생성 → 개발자 코드가 실행 → 결과를 Claude에게 다시 전달하는 반복 루프

OpenAI의 Function Calling과 동일한 개념이며, Anthropic에서는 이를 Tool Use라고 부릅니다. MCP(Model Context Protocol)도 내부적으로 이 메커니즘 위에서 동작합니다.

요청·응답 흐름 4단계

Tool Use는 단순한 단방향 호출이 아니라 Claude와 개발자 코드가 번갈아가며 대화하는 멀티턴 루프입니다.

  1. 도구 정의 전달: API 요청 시 tools 배열에 사용 가능한 함수 목록을 JSON Schema로 전달합니다. Claude는 이 목록을 보고 어떤 도구를 쓸 수 있는지 파악합니다.
  2. Claude의 도구 호출 결정: Claude가 응답을 생성할 때 도구 호출이 필요하다고 판단하면 stop_reason: "tool_use"와 함께 tool_use 블록을 반환합니다. 이 블록에는 함수명과 인수가 담겨 있습니다.
  3. 개발자 코드 실행: 응답에서 tool_use 블록을 파싱하고, 해당 함수를 직접 실행합니다. 결과를 tool_result 블록으로 만들어 다음 메시지에 담습니다.
  4. 최종 응답 수신: 도구 결과를 받은 Claude가 최종 텍스트 응답을 생성합니다. 필요하면 2~4단계를 반복합니다.
흐름 요약 (Python 의사 코드)

while True:
  response = client.messages.create(tools=tools, messages=messages)
  if response.stop_reason != "tool_use": break
  result = run_tool(response) # 개발자 코드
  messages.append(tool_result_message(result))

도구 정의 방법

각 도구는 name, description, input_schema 세 가지 필드로 구성됩니다. 특히 description은 Claude가 "이 도구를 언제 써야 하는지" 판단하는 핵심 단서가 되므로 명확하게 작성해야 합니다.

기본 도구 정의 예시 (Python)

Python — tools 배열 정의

tools = [
  {
    "name": "get_weather",
    "description": "특정 도시의 현재 날씨와 기온을 조회합니다.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {"type": "string", "description": "도시 이름 (예: 서울, 도쿄)"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
      },
      "required": ["city"]
    }
  }
]

input_schema는 JSON Schema Draft 2020-12 형식을 따릅니다. required 배열에 필수 파라미터를 지정하고, enum으로 허용 값을 제한하면 Claude가 잘못된 인수를 만들 가능성이 줄어듭니다.

도구 결과 전달 방법

Python — tool_result 메시지 구성

tool_use_block = response.content[0] # stop_reason == "tool_use"

result = get_weather(tool_use_block.input["city"])

messages.append({
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": tool_use_block.id,
    "content": str(result)
  }]
})

tool_use_id는 Claude가 반환한 tool_use 블록의 id 값과 반드시 일치해야 합니다. 복수의 도구를 병렬 호출할 때 각 결과를 올바른 호출에 대응시키는 데 사용됩니다.

tool_choice 옵션

기본적으로 Claude는 도구를 사용할지 여부를 스스로 결정합니다. tool_choice 파라미터로 이 동작을 제어할 수 있습니다.

값 동작 사용 시점
{"type": "auto"} Claude가 도구 사용 여부 자체 결정 (기본값) 일반적인 에이전트 루프
{"type": "any"} 반드시 도구 중 하나를 호출 도구 호출이 필수인 파이프라인
{"type": "tool", "name": "X"} 지정한 도구만 호출 특정 함수의 인수 추출(JSON 파싱 대체)
{"type": "none"} (미지원) 도구 정의는 전달하되 호출 금지 tools 배열을 빼면 동일 효과
활용 팁 — JSON 파싱 대체

tool_choice: {"type": "tool", "name": "extract_data"}로 특정 도구를 강제 호출하면, Claude의 응답이 항상 해당 도구의 input_schema에 맞는 JSON이 됩니다. 별도 파싱 코드 없이 구조화된 데이터 추출에 활용할 수 있습니다.

병렬 Tool Use

Claude는 한 번의 응답에서 여러 개의 도구를 동시에 호출할 수 있습니다. 예를 들어 "서울과 도쿄 날씨를 동시에 알려줘"라고 요청하면 tool_use 블록 두 개가 한꺼번에 반환됩니다.

개발자는 이 블록들을 병렬로 처리한 뒤, 결과를 같은 user 메시지의 content 배열에 모두 담아 한 번에 전달하면 됩니다.

병렬 처리 패턴 (Python)

tool_uses = [b for b in response.content if b.type == "tool_use"]

results = []
for tu in tool_uses:
  result = dispatch_tool(tu.name, tu.input)
  results.append({"type": "tool_result", "tool_use_id": tu.id, "content": str(result)})

messages.append({"role": "user", "content": results})

병렬 Tool Use는 독립적인 정보를 동시에 조회할 때 응답 지연을 크게 줄입니다. 실제로 asyncio나 ThreadPoolExecutor와 함께 사용해 진짜 병렬 실행으로 구현하면 성능이 더욱 향상됩니다.

실전 패턴 4가지

패턴 1 — 웹 검색 에이전트

사용자가 최신 정보를 요청할 때 Claude가 직접 검색 쿼리를 생성하고 결과를 요약합니다. search(query: str) → str 도구 하나만으로 기본 RAG 없이 실시간 정보를 다룰 수 있습니다.

주의: 검색 결과를 그대로 신뢰하지 말고, 신뢰도가 낮은 소스는 도구 결과에 명시해 Claude가 할루시네이션을 줄이도록 유도하세요.

패턴 2 — 코드 실행 샌드박스

Claude가 Python 코드를 작성하면 샌드박스에서 실행하고 결과를 돌려주는 루프입니다. 데이터 분석, 수학 계산, 차트 생성 등 계산 집약적 작업에 적합합니다. E2B, Jupyter Kernel 등 격리된 환경과 함께 사용하세요.

패턴 3 — 구조화된 데이터 추출

tool_choice: {"type": "tool", "name": "extract"}와 상세한 input_schema를 조합하면 Claude를 정밀한 JSON 파서로 사용할 수 있습니다. 비정형 텍스트(이메일, 계약서, 뉴스 기사)에서 특정 필드를 추출하는 파이프라인에 유용합니다.

패턴 4 — 멀티 스텝 에이전트

검색 → 분석 → 저장 같이 순차 또는 조건 분기가 있는 워크플로를 구현합니다. 루프 탈출 조건(stop_reason == "end_turn")과 최대 반복 횟수를 반드시 설정해 무한 루프를 방지하세요.

⚠️ 무한 루프 방지
  • 루프에 max_iterations = 10 같은 상한선을 항상 설정하세요.
  • stop_reason == "end_turn"이 되면 루프를 즉시 종료합니다.
  • 도구 실행 실패 시 tool_result의 is_error: true 플래그를 사용해 Claude가 오류 상황을 인식하도록 합니다.

보안 주의사항

Tool Use는 강력한 만큼 잘못 구현하면 보안 취약점이 생깁니다. 아래 항목을 반드시 점검하세요.

  1. 입력 검증 필수: Claude가 생성한 input 값을 그대로 함수에 전달하지 마세요. 특히 파일 경로, SQL 쿼리, 셸 명령처럼 주입 공격에 취약한 인수는 서버 측에서 반드시 재검증합니다.
  2. 최소 권한 원칙: 각 도구가 접근하는 리소스를 최소화합니다. 검색 도구가 DB 삭제 권한을 가질 이유는 없습니다.
  3. Prompt Injection 방어: 외부 데이터(웹 검색 결과, 사용자 파일)가 도구 결과로 반환될 때 그 안에 악의적인 지시가 포함될 수 있습니다. 신뢰할 수 없는 소스의 결과는 별도 샌드박스에서 처리하거나 명시적으로 표시하세요.
  4. 비가역 작업 확인: 이메일 발송, DB 삭제, 결제처럼 되돌릴 수 없는 작업은 실행 전 사용자 확인 단계를 코드로 구현하세요. Claude의 판단에만 의존하지 마세요.

도입 체크리스트

  1. 도구 분리: 각 도구는 단 하나의 책임만 갖도록 설계합니다. 복잡한 도구 하나보다 단순한 도구 여러 개가 Claude의 호출 정확도를 높입니다.
  2. description 품질: 언제 이 도구를 써야 하는지, 어떤 제약이 있는지 description에 명시합니다. Claude는 이 설명을 보고 도구 선택을 결정합니다.
  3. 오류 처리: 도구 실행 실패 시 빈 문자열 대신 오류 메시지를 tool_result에 담아 Claude가 재시도하거나 대안을 찾도록 합니다.
  4. 토큰 최적화: 도구 정의가 길면 입력 토큰이 많아집니다. 프롬프트 캐싱(cache_control: ephemeral)을 도구 정의에 적용해 반복 비용을 줄이세요.
  5. 로깅: 어떤 도구가 어떤 인수로 호출됐는지 기록해 디버깅과 품질 모니터링에 활용합니다.

텍스트를 넘어 행동하는 AI를 만드세요

Tool Use는 Claude를 단순한 대화 상대에서 실제 작업을 수행하는 자율 에이전트로 바꾸는 핵심입니다. 도구 정의를 잘 설계하고 보안 원칙을 지키면, 검색·분석·실행을 자동화하는 강력한 AI 워크플로를 구축할 수 있습니다.

Claude API Tool Use Function Calling AI 에이전트 Anthropic