Claude API의 tool_use 구현 시 반드시 걸리는 5가지 함정
요약
본 글은 Anthropic Claude API를 사용하여 사내 문서 처리 에이전트를 구현할 때 개발자들이 흔히 빠지는 5가지 함정과 올바른 구현 패턴을 제시합니다. 특히 `tool_use` (함수 호출) 로직에서 발생하는 오류들을 중심으로, `stop_reason` 체크, 병렬 도구 사용 처리, 그리고 `tool_result`의 에러 플래그 지정 등 핵심적인 개발 가이드를 제공합니다.
핵심 포인트
- Claude는 `stop_reason: "tool_use"`를 반환하므로 반드시 이를 확인해야 합니다.
- 한 번의 응답으로 여러 도구를 호출할 수 있으므로, 단일 도구 전제 코드는 오류가 발생합니다.
- `response.content` 전체를 메시지 배열에 추가하는 것이 핵심입니다.
- 도구 실행 실패 시에는 `tool_result`에 반드시 `is_error: true` 플래그를 지정해야 합니다.
서론
Anthropic이 공개한 금융 업무용 에이전트 템플릿군(KYC, 피치북 생성, 월별 결산 처리 등)이 주목받고 있다. 이를 참고하여 사내 문서 처리 에이전트를 구현하려 할 때, tool_use (함수 호출) 구현 실수로 어려움을 겪는 개발자가 끊이지 않는다.
본고에서는 필자가 실제로 빠졌던 5가지 전형적인 함정과 올바른 구현 패턴을 소개한다. GPT의 function calling과 '대충 비슷하겠지'라는 착각이 사고가 되는 경우가 많다.
stop_reason 체크 누락 (함정 1)
가장 흔한 실수는 stop_reason을 확인하지 않고 응답에서 텍스트를 직접 추출하려는 패턴이다.
// ❌ 안티 패턴
const response = await client.messages.create({ ... });
const text = response.content[0].text; // tool_use 블록이 맨 앞에 오면 undefined가 된다.
Claude는 도구를 호출할 때 stop_reason: "tool_use"를 반환하고, content 배열에 { type: "tool_use", ... } 블록을 포함한다. 만약 content[0]이 tool_use 블록이라면 .text 속성이 존재하지 않아 런타임 에러가 발생한다.
// ✅ 올바른 구현
const response = await client.messages.create({ ... });
if (response.stop_reason === "tool_use") {
...
병렬 tool_use 미지원 (함정 2)
Claude는 한 번의 응답으로 여러 도구를 동시에 호출할 수 있다. 단일 호출을 전제로 한 코드는 반드시 깨진다.
// ❌ 안티 패턴: 단일 도구만 가정
const toolCall = response.content.find(b => b.type === "tool_use");
const result = await executeTool(toolCall!.name, toolCall!.input);
예를 들어
반환한다.```
// ✅ 올바른 구현
const messages: MessageParam[] = [
{
role: "user", content: userPrompt },
...
`response.content`
을 **통째로** `messages`
에 추가하는 것이 핵심이다. 텍스트 블록과 tool_use 블록이 혼재되어 있어도 그대로 넣으면 된다. 이것을 생략하면 API가 `400 Bad Request`
를 반환한다.
##
`tool_result`
처리
함정 5: 에러 발생 시 도구 실행 실패했을 때, 많은 엔지니어들이 에러 메시지를 `content`
에 문자열로 채워 넣기만 한다. 하지만 `is_error: true`
플래그를 지정하지 않으면 모델은 성공한 결과로 간주하고 이상한 추론을 계속한다.
// ❌ 안티 패턴
{
type: "tool_result",
...
// ✅ 올바른 구현: is_error 플래그를 지정
{
type: "tool_result",
...
`is_error: true`
을 지정하면 Claude는 도구 실행 실패를 인지하고, '다른 접근 방식을 시도한다', '사용자에게 에러를 전달한다'와 같은 적절한 판단을 내린다. 플래그가 없으면 'API가 `Error: 404`
라는 데이터를 반환했다'고 해석하여, 그 에러 문자열을 기반으로 다음 추론을 구성해 버린다.
## 요약: 구현 전 체크리스트
| 체크 항목 | 확인 내용 |
|---|---|
`stop_reason` 분기 | `
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기