도구 호출 처리하기

이 페이지는 도구 호출 라이프사이클을 다룹니다: Claude의 응답에서 tool_use 블록을 읽고, 회신에서 tool_result 블록을 포맷하며, 오류를 알리는 방법입니다. 이를 자동으로 처리하는 SDK 추상화에 대해서는 Tool Runner를 참조하세요.

Claude의 응답은 클라이언트 도구 또는 서버 도구를 사용하는지에 따라 달라집니다.



클라이언트 도구의 결과 처리하기

응답에는 tool_use의 stop_reason과 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록이 있습니다:

• id: 이 특정 도구 사용 블록의 고유 식별자입니다. 나중에 도구 결과를 매칭하는 데 사용됩니다.
• name: 사용 중인 도구의 이름입니다.
• input: 도구에 전달되는 입력을 포함하는 객체로, 도구의 input_schema를 준수합니다.

클라이언트 도구에 대한 도구 사용 응답을 받으면 다음을 수행해야 합니다:

1. tool_use 블록에서 name, id, input을 추출합니다.
2. 해당 도구 이름에 해당하는 코드베이스의 실제 도구를 실행하고 도구 input을 전달합니다.
3. user의 role과 tool_result 타입 및 다음 정보를 포함하는 content 블록으로 새 메시지를 보내 대화를 계속합니다:
   • tool_use_id: 이 결과가 해당하는 도구 사용 요청의 id입니다.
   • content (선택 사항): 도구의 결과로, 문자열(예: "content": "15 degrees"), 중첩된 콘텐츠 블록 목록(예: "content": [{"type": "text", "text": "15 degrees"}]), 또는 문서 블록 목록(예: "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}])입니다. 이러한 콘텐츠 블록은 text, image, document 또는 search_result 타입을 사용할 수 있습니다.
   • is_error (선택 사항): 도구 실행이 오류로 끝난 경우 true로 설정합니다.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

도구 결과를 받은 후, Claude는 해당 정보를 사용하여 원래 사용자 프롬프트에 대한 응답을 계속 생성합니다.



서버 도구의 결과 처리하기

Claude는 도구를 내부적으로 실행하고 추가 사용자 상호작용 없이 결과를 응답에 직접 통합합니다.



is_error로 오류 처리하기

Claude와 함께 도구를 사용할 때 발생할 수 있는 몇 가지 유형의 오류가 있습니다:



다음 단계