Claude API 도구 사용 베스트 프랙티스: 정의·에러·병렬 호출 실무

도구 사용(tool use)의 기본 원리를 안다면, 다음 단계는 실제로 안정적으로 동작하게 만드는 것입니다. 이 글은 도구 정의·에러 처리·병렬 호출·결과 포맷에 대한 실무 베스트 프랙티스를 Anthropic 공식 도구 사용 문서 기준으로 정리합니다. (기준 시점: 2026년 6월)

1. 도구 정의를 잘 쓰는 법

도구 사용 품질을 좌우하는 가장 큰 요인은 도구 설명(description)입니다. 무엇을 하는 도구인지, 언제 써야 하고 언제 쓰면 안 되는지를 충분히 길고 구체적으로 적을수록 Claude가 올바르게 선택합니다. 파라미터는 input_schema에 필수·선택, 타입, 형식(예: 날짜 포맷)을 명시합니다.

입력이 어긋나면 실패하는 프로덕션 에이전트라면 도구 정의에 strict: true를 더하세요. 구조화된 출력(structured outputs)이 적용되어 Claude의 도구 입력이 스키마와 정확히 일치하도록 보장합니다(타입 불일치·필드 누락 방지). 모델은 복잡하고 모호한 작업일수록 최신 Opus가 다중 도구를 더 잘 다루고 필요 시 되묻습니다. 단순한 도구엔 Haiku도 좋지만, 누락된 파라미터를 추론할 수 있다는 점에 유의합니다.

2. 에이전트 루프와 에러 처리

도구를 쓰는 대화는 반복 루프입니다. API를 호출하고 → stop_reason을 확인하고 → 도구를 실행하고 → 결과를 메시지에 덧붙이는 과정을, stop_reason == "tool_use"인 동안 반복합니다. 루프는 end_turn·max_tokens·stop_sequence·refusal 같은 다른 종료 이유에서 빠져나옵니다.

도구는 실패할 수 있습니다. 캘린더 API가 참석자 초과로 거절하거나 날짜 형식이 잘못될 수 있죠. 이때 충돌시키지 말고 결과 블록에 is_error: true와 에러 메시지를 담아 돌려주세요. Claude는 에러를 읽고 입력을 고쳐 재시도하거나, 사용자에게 되묻거나, 한계를 설명합니다. 성공 결과와의 유일한 차이는 이 플래그뿐입니다.

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "cat: report.md: No such file or directory"
}

대부분의 SDK에는 이 루프(에러 래핑·결과 포맷·대화 관리)를 자동 처리하는 Tool Runner가 있습니다. 직접 세밀하게 제어할 필요가 없다면 Tool Runner를 쓰는 편이 간단합니다.

3. 병렬 도구 호출 — 결과 포맷 규칙

기본적으로 Claude는 한 턴에 독립적인 여러 도구를 동시에 호출할 수 있습니다. 이때 포맷 규칙을 어기면 병렬 처리가 깨집니다.

• 병렬 호출의 모든 결과는 하나의 user 메시지에 담고, 각 결과는 개별 tool_result 블록으로 넣습니다.
• user 메시지의 content 배열에서 tool_result 블록이 맨 앞에 와야 하며, 어떤 텍스트든 모든 결과 뒤에 와야 합니다.
• tool_result는 대응하는 tool_use 바로 다음에 와야 하고, 그 사이에 다른 메시지를 끼울 수 없습니다.
• 한 턴의 도구 호출은 순서가 없습니다. 동시(예: Promise.all, asyncio.gather)·순차·임의 순서로 실행해도 됩니다.

한 배치 안의 호출이 서로 의존해 실패하면, 의존성을 설명할 필요 없이 그냥 is_error: true와 자연스러운 에러 메시지를 돌려주세요. Claude가 회복해 다시 호출합니다. 병렬을 끄려면 tool_choice가 auto일 때 disable_parallel_tool_use=true로 최대 한 개만, any/tool일 때는 정확히 한 개만 쓰게 할 수 있습니다.

4. 도구가 많아질 때

도구 정의에는 정해진 개수 제한은 없지만, 정의가 많아질수록 컨텍스트를 더 소비합니다. 도구 수가 많은(대략 수십 개 이상) 설정에서는 정의만으로도 상당한 토큰을 쓸 수 있습니다. 이런 경우 공식 문서가 안내하는 Tool Search와 defer_loading 같은 동적 발견 패턴을 적용해, 필요한 도구만 그때그때 불러오도록 설계하는 것이 좋습니다.

함께 보면 좋은 글

도구 사용의 작동 원리는 Tool Use 완벽 가이드, 출력 형식을 JSON 스키마로 강제하는 법은 구조화된 출력에서 다룹니다.