도구 호출 처리하기
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가 호출하는 멤버 도구이므로, 이러한 블록은 두 필드 모두를 기준으로 디스패치하세요.
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-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블록에 대해 해당 블록이 지정하는 도구를 실행하고, 그input을 전달합니다. - 새 요청에서 이전 메시지를 유지하고 응답의
content를 변경하지 않은 채assistant메시지로 추가합니다. - 해당 콘텐츠의 각
tool_use블록마다tool_result블록 하나씩을 담은user메시지를 추가합니다. 도구가 실패한 경우에도 마찬가지입니다. - 첫 번째 요청과 동일한
tools로 요청을 보냅니다. Claude는 도구 결과를 사용하여 응답을 계속합니다. - 다음 응답의
stop_reason도tool_use이면 이 단계를 반복합니다. 다른 값에 대해서는 중지 이유 빠른 참조를 참조하세요.
이 단계를 완전한 프로그램으로 보려면 튜토리얼: 도구를 사용하는 에이전트 구축하기를 참조하세요.
각 tool_result 블록은 type이 tool_result로 설정되며, 다음 필드를 가집니다.
tool_use_id: 이 결과가 대응하는tool_use블록의id입니다.content(선택 사항): 문자열 또는 콘텐츠 블록 목록 형태의 도구 결과입니다. 이러한 콘텐츠 블록은text,image,document또는search_result타입을 사용할 수 있습니다.is_error(선택 사항): 도구가 실패했거나 호출이 유효하지 않은 경우true로 설정합니다.
예를 들어, 성공적인 도구 결과는 다음과 같습니다.
{
"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 블록 하나를 추가할 수 있습니다(탭 관리 멤버는 해당 블록만 반환합니다).
{
"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..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"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"
}
}
]
}
]
}예를 들어, 다음은 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
]
}서버 도구의 결과 처리하기
Claude는 도구를 내부적으로 실행하고 추가적인 사용자 상호작용 없이 결과를 응답에 직접 반영합니다.
is_error로 오류 처리하기
클라이언트 도구가 실패하거나 호출이 유효하지 않은 경우, is_error를 true로 설정한 tool_result 블록을 보내세요. 그러면 Claude가 새 tool_use 블록으로 도구를 다시 호출할 수 있으므로, 루프에서 허용하는 재시도 횟수를 제한하세요.
도구 자체가 실행 중에 오류를 발생시키는 경우(예: 날씨 데이터를 가져올 때 네트워크 오류), "is_error": true와 함께 content에 오류 메시지를 반환할 수 있습니다.
{
"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는 도구를 다시 호출하거나 사용자에게 무슨 일이 있었는지 알릴 수 있습니다. 예를 들어 Claude는 "죄송합니다. 날씨 서비스 API를 사용할 수 없어 현재 날씨를 가져올 수 없었습니다. 나중에 다시 시도해 주세요."라고 말할 수 있습니다.
Claude의 도구 사용 시도가 유효하지 않은 경우(예: 필수 매개변수 누락), 이는 대개 Claude가 도구를 올바르게 사용하기에 충분한 정보가 없었다는 의미입니다. 개발 중 가장 좋은 방법은 도구 정의에 더 자세한 description 값을 넣어 요청을 다시 시도하는 것입니다.
그러나 오류를 나타내는 tool_result로 대화를 계속 진행할 수도 있습니다.
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}그러면 Claude는 누락된 정보를 채워 도구를 다시 호출할 수 있습니다.
클라이언트 도구와 달리 서버 도구에 대해서는 is_error 결과를 보내지 않습니다. 서버 도구에서 오류가 발생하면(예: 웹 검색 중 네트워크 문제), API는 도구의 결과 블록 안에 오류를 반환합니다. 대부분의 경우 Claude는 이후 다른 접근 방식으로 계속하거나 사용자에게 설명을 제공합니다.
웹 검색 오류 코드에 대해서는 웹 검색 도구 오류를 참조하세요.
다음 단계
Claude가 한 턴에 여러 도구를 호출하는 응답을 처리합니다.
SDK가 tool_use 루프, 결과 포맷, 재시도를 대신 관리하도록 합니다.
Claude를 올바른 도구로 이끄는 스키마와 설명을 작성합니다.
이 페이지가 도움이 되었나요?