도구 호출 처리하기

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

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

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

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

응답은 tool_use의 stop_reason과 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록을 갖습니다.

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

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

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA", "unit": "celsius" }
    }
  ]
}

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

tool_use 블록에서 name, id, input을 추출합니다.
해당 도구 이름에 대응하는 코드베이스의 실제 도구를 실행하고, 도구 input을 전달합니다.
role이 user이고, 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로 설정합니다.

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

중요한 포맷 요구 사항:

도구 결과 블록은 메시지 기록에서 대응하는 도구 사용 블록 바로 뒤에 와야 합니다. 어시스턴트의 도구 사용 메시지와 사용자의 도구 결과 메시지 사이에 어떤 메시지도 포함할 수 없습니다.
도구 결과를 담은 사용자 메시지에서 tool_result 블록은 content 배열의 맨 앞에 와야 합니다. 모든 텍스트는 모든 도구 결과 뒤에 와야 합니다.
어시스턴트 턴이 아직 결과 블록이 없는 서버 도구도 호출한 경우, 사용자 메시지는 tool_result 블록만 포함해야 합니다. 결과 뒤에 텍스트가 오면 턴이 조기에 종료됩니다. Claude가 직접 호출한 서버 도구의 경우, 요청은 해결되지 않은 서버 도구의 이름을 명시하는 400 오류와 함께 실패합니다. 중지 이유 및 폴백을 참조하세요.

예를 들어, 다음은 400 오류를 발생시킵니다.

{
  "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
  ]
}

"tool_use ids were found without tool_result blocks immediately after"와 같은 오류를 받으면 도구 결과가 올바르게 포맷되었는지 확인하세요.

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        { "type": "text", "text": "15 degrees" },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg..."
          }
        }
      ]
    }
  ]
}

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        { "type": "text", "text": "The weather is" },
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}

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

서버 도구의 결과 처리하기

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

is_error로 오류 처리하기

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

도구 자체가 실행 중에 오류를 발생시키는 경우(예: 날씨 데이터를 가져올 때 네트워크 오류), "is_error": true와 함께 content에 오류 메시지를 반환할 수 있습니다.

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

그러면 Claude는 이 오류를 사용자에 대한 응답에 통합합니다. 예: "죄송합니다. 날씨 서비스 API를 사용할 수 없어 현재 날씨를 가져올 수 없었습니다. 나중에 다시 시도해 주세요."

Claude의 도구 사용 시도가 유효하지 않은 경우(예: 필수 매개변수 누락), 이는 보통 Claude가 도구를 올바르게 사용하기에 정보가 충분하지 않았음을 의미합니다. 개발 중 가장 좋은 방법은 도구 정의에 더 자세한 description 값을 넣어 요청을 다시 시도하는 것입니다.

그러나 오류를 나타내는 tool_result로 대화를 계속 진행할 수도 있으며, 그러면 Claude는 누락된 정보를 채워 도구를 다시 사용하려고 시도합니다.

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

도구 요청이 유효하지 않거나 매개변수가 누락된 경우, Claude는 사용자에게 사과하기 전에 수정하여 2~3회 재시도합니다.

다음 단계

병렬 도구 사용

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

Tool Runner (SDK)

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

도구 정의하기

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

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

`tool_use` 콘텐츠 블록이 포함된 API 응답 예시

성공적인 도구 결과 예시

이미지가 포함된 도구 결과 예시

빈 도구 결과 예시

문서가 포함된 도구 결과 예시

서버 도구의 결과 처리하기

is_error로 오류 처리하기

도구 실행 오류

잘못된 도구 이름

서버 도구 오류

다음 단계

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

서버 도구의 결과 처리하기

is_error로 오류 처리하기

다음 단계