Claude Platform Docs
Messages도구

도구 호출 처리하기

tool_use 블록을 파싱하고, tool_result 응답을 포맷하며, is_error로 오류를 처리합니다.

Claude의 응답에 tool_use 블록이 포함되어 있으면, 코드에서 각 도구를 실행하고 오류를 포함한 tool_result 블록을 다시 보냅니다. 도구 실행에 대한 사용자 정의 제어가 필요한 경우 이 코드를 직접 작성하세요. 그렇지 않은 경우 도구를 실행하고 결과를 대신 보내 주는 SDK의 도구 러너를 사용하세요.

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

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

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

  • id: 이 특정 도구 사용 블록의 고유 식별자입니다. 나중에 도구 결과를 매칭하는 데 사용됩니다.
  • name: 사용 중인 도구의 이름입니다.
  • input: 도구의 input_schema를 따르며 도구에 전달되는 입력을 담고 있는 객체입니다.

컴퓨터 사용 또는 브라우저 사용 도구 세트의 멤버에 대한 tool_use 블록은 toolset_name 필드("computer" 또는 "browser")도 함께 전달합니다. 이 블록의 name은 screenshot이나 navigate처럼 Claude가 호출하는 멤버 도구이므로, 이러한 블록은 두 필드 모두를 기준으로 디스패치하세요.

클라이언트 도구에 대한 도구 사용 응답을 받으면 다음 단계를 따르세요.

  1. 각 tool_use 블록에 대해 해당 블록이 지정하는 도구를 실행하고, 그 input을 전달합니다.
  2. 새 요청에서 이전 메시지를 유지하고 응답의 content를 변경하지 않은 채 assistant 메시지로 추가합니다.
  3. 해당 콘텐츠의 각 tool_use 블록마다 tool_result 블록 하나씩을 담은 user 메시지를 추가합니다. 도구가 실패한 경우에도 마찬가지입니다.
  4. 첫 번째 요청과 동일한 tools로 요청을 보냅니다. Claude는 도구 결과를 사용하여 응답을 계속합니다.
  5. 다음 응답의 stop_reason도 tool_use이면 이 단계를 반복합니다. 다른 값에 대해서는 중지 이유 빠른 참조를 참조하세요.

이 단계를 완전한 프로그램으로 보려면 튜토리얼: 도구를 사용하는 에이전트 구축하기를 참조하세요.

각 tool_result 블록은 type이 tool_result로 설정되며, 다음 필드를 가집니다.

  • tool_use_id: 이 결과가 대응하는 tool_use 블록의 id입니다.
  • content (선택 사항): 문자열 또는 콘텐츠 블록 목록 형태의 도구 결과입니다. 이러한 콘텐츠 블록은 text, image, document 또는 search_result 타입을 사용할 수 있습니다.
  • is_error (선택 사항): 도구가 실패했거나 호출이 유효하지 않은 경우 true로 설정합니다.

예를 들어, 성공적인 도구 결과는 다음과 같습니다.

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

컴퓨터 사용 또는 브라우저 사용 멤버 블록에 응답하는 tool_result는 tool_use 블록과 동일한 toolset_name 값도 그대로 반환해야 합니다. 이를 생략한 멤버 결과는 거부됩니다. content도 더 제한적입니다. 멤버 결과는 text 및 image 블록만 포함할 수 있으며, 브라우저 사용 결과는 browser_state 블록 하나를 추가할 수 있습니다(탭 관리 멤버는 해당 블록만 반환합니다).

서버 도구의 결과 처리하기

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

is_error로 오류 처리하기

클라이언트 도구가 실패하거나 호출이 유효하지 않은 경우, is_error를 true로 설정한 tool_result 블록을 보내세요. 그러면 Claude가 새 tool_use 블록으로 도구를 다시 호출할 수 있으므로, 루프에서 허용하는 재시도 횟수를 제한하세요.

다음 단계

Claude가 한 턴에 여러 도구를 호출하는 응답을 처리합니다.

SDK가 tool_use 루프, 결과 포맷, 재시도를 대신 관리하도록 합니다.

Claude를 올바른 도구로 이끄는 스키마와 설명을 작성합니다.

이 페이지가 도움이 되었나요?