---
title: 도구 호출 처리하기
url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/handle-tool-calls
description: tool_use 블록을 파싱하고, tool_result 응답을 포맷하며, is_error로 오류를 처리합니다.
---
이 페이지는 도구 호출 수명 주기를 다룹니다. Claude의 응답에서 `tool_use` 블록을 읽고, 회신에서 `tool_result` 블록을 포맷하며, 오류를 알리는 방법을 설명합니다. 이를 자동으로 처리하는 SDK 추상화에 대해서는 [Tool Runner](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)를 참조하세요.
**Tool Runner로 더 간단하게:** 이 페이지에서 설명하는 수동 도구 처리는 [Tool Runner](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-runner)가 자동으로 관리합니다. 도구 실행에 대한 사용자 정의 제어가 필요한 경우 이 페이지를 사용하세요.
Claude의 응답은 [클라이언트 도구 또는 서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview#how-tool-use-works) 중 어느 것을 사용하는지에 따라 달라집니다.
## 클라이언트 도구의 결과 처리하기
응답은 `tool_use`의 `stop_reason`과 다음을 포함하는 하나 이상의 `tool_use` 콘텐츠 블록을 갖습니다.
* `id`: 이 특정 도구 사용 블록의 고유 식별자입니다. 나중에 도구 결과를 매칭하는 데 사용됩니다.
* `name`: 사용 중인 도구의 이름입니다.
* `input`: 도구의 `input_schema`를 따르며 도구에 전달되는 입력을 담고 있는 객체입니다.
[컴퓨터 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool) 또는 [브라우저 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool) 도구 세트의 멤버에 대한 `tool_use` 블록은 `toolset_name` 필드(`"computer"` 또는 `"browser"`)도 함께 전달합니다. 이 블록의 `name`은 `screenshot`이나 `navigate`처럼 Claude가 호출하는 멤버 도구이므로, 이러한 블록은 두 필드 모두를 기준으로 디스패치하세요.
```json JSON
{
"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" }
}
]
}
```
클라이언트 도구에 대한 도구 사용 응답을 받으면 다음을 수행해야 합니다.
1. `tool_use` 블록에서 `name`, `id`, `input`을 추출합니다.
2. 해당 도구 이름에 대응하는 코드베이스의 실제 도구를 실행하고, 도구 `input`을 전달합니다.
3. `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`](https://platform.claude.com/docs/ko/build-with-claude/search-results) 타입을 사용할 수 있습니다.
* `is_error` (선택 사항): 도구 실행 결과 오류가 발생한 경우 `true`로 설정합니다.
컴퓨터 사용 또는 브라우저 사용 멤버 블록에 응답하는 `tool_result`는 `tool_use` 블록과 동일한 `toolset_name` 값도 그대로 반환해야 합니다. 이를 생략한 멤버 결과는 거부됩니다. `content`도 더 제한적입니다. 멤버 결과는 `text` 및 `image` 블록만 포함할 수 있으며, 브라우저 사용 결과는 [`browser_state`](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) 블록 하나를 추가할 수 있습니다([탭 관리 멤버](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool#tab-management-results)는 해당 블록만 반환합니다).
**중요한 포맷 요구 사항:**
* 도구 결과 블록은 메시지 기록에서 대응하는 도구 사용 블록 바로 뒤에 와야 합니다. 어시스턴트의 도구 사용 메시지와 사용자의 도구 결과 메시지 사이에 어떤 메시지도 포함할 수 없습니다.
* 도구 결과를 담은 사용자 메시지에서 tool\_result 블록은 content 배열의 맨 앞에 와야 합니다. 모든 텍스트는 모든 도구 결과 뒤에 와야 합니다.
* 어시스턴트 턴이 아직 결과 블록이 없는 [서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)도 호출한 경우, 사용자 메시지는 `tool_result` 블록만 포함해야 합니다. 결과 뒤에 텍스트가 오면 턴이 조기에 종료됩니다. Claude가 직접 호출한 서버 도구의 경우, 요청은 해결되지 않은 서버 도구의 이름을 명시하는 400 오류와 함께 실패합니다. [중지 이유 및 폴백](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#tool-use)을 참조하세요.
예를 들어, 다음은 400 오류를 발생시킵니다.
```json
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}
```
어시스턴트 턴이 클라이언트 도구만 호출하는 경우 다음이 올바릅니다.
```json
{
"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"와 같은 오류를 받으면 도구 결과가 올바르게 포맷되었는지 확인하세요.
도구 결과는 웹 페이지, 수신 이메일, 사용자 업로드, 서드파티 API 등 여러분이 제어할 수 없는 소스의 콘텐츠를 담고 있는 경우가 많습니다. 이러한 콘텐츠는 신뢰할 수 없는 것으로 취급하세요. 이에 영향을 미칠 수 있는 공격자는 Claude의 방향을 바꾸려는 지시를 삽입할 수 있습니다(간접 프롬프트 인젝션). 신뢰할 수 없는 콘텐츠는 `system` 프롬프트나 일반 사용자 `text` 블록이 아닌 `tool_result` 블록 안에 두고, 추가적인 강화 방법은 [탈옥 및 프롬프트 인젝션 완화](https://platform.claude.com/docs/ko/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection)를 참조하세요.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json 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 JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json 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는 도구를 내부적으로 실행하고 추가적인 사용자 상호작용 없이 결과를 응답에 직접 통합합니다.
응답에는 클라이언트 `tool_use` 블록과 결과 블록이 없는 `server_tool_use` 블록이 모두 포함될 수 있습니다. 해당 서버 도구 호출은 아직 완료되지 않은 것이며, 그 결과 블록은 이후 응답에서 도착합니다. 클라이언트 도구에 대한 `tool_result` 블록만 포함하는 사용자 메시지로 회신하고 동일한 `tools` 배열을 유지하세요. Claude가 직접 호출한 서버 도구의 경우, API는 해당 요청에서 이를 실행하며 다음 응답은 그 결과 블록으로 시작합니다. [중지 이유 및 폴백](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#tool-use)을 참조하세요.
**다른 API와의 차이점**
도구 사용을 분리하거나 `tool` 또는 `function`과 같은 특수 역할을 사용하는 API와 달리, Claude API는 도구를 `user` 및 `assistant` 메시지 구조에 직접 통합합니다.
메시지는 `text`, `image`, `tool_use`, `tool_result` 블록의 배열을 포함합니다. `user` 메시지는 클라이언트 콘텐츠와 `tool_result`를 포함하고, `assistant` 메시지는 AI가 생성한 콘텐츠와 `tool_use`를 포함합니다.
## is\_error로 오류 처리하기
Claude와 함께 도구를 사용할 때 발생할 수 있는 오류에는 몇 가지 유형이 있습니다.
도구 자체가 실행 중에 오류를 발생시키는 경우(예: 날씨 데이터를 가져올 때 네트워크 오류), `"is_error": true`와 함께 `content`에 오류 메시지를 반환할 수 있습니다.
```json 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를 사용할 수 없어 현재 날씨를 가져올 수 없었습니다. 나중에 다시 시도해 주세요."
유익한 오류 메시지를 작성하세요. `"failed"`와 같은 일반적인 오류 대신, 무엇이 잘못되었고 Claude가 다음에 무엇을 시도해야 하는지 포함하세요(예: `"Rate limit exceeded. Retry after 60 seconds."`). 이렇게 하면 Claude가 추측 없이 복구하거나 적응하는 데 필요한 컨텍스트를 얻을 수 있습니다.
Claude의 도구 사용 시도가 유효하지 않은 경우(예: 필수 매개변수 누락), 이는 보통 Claude가 도구를 올바르게 사용하기에 정보가 충분하지 않았음을 의미합니다. 개발 중 가장 좋은 방법은 도구 정의에 더 자세한 `description` 값을 넣어 요청을 다시 시도하는 것입니다.
그러나 오류를 나타내는 `tool_result`로 대화를 계속 진행할 수도 있으며, 그러면 Claude는 누락된 정보를 채워 도구를 다시 사용하려고 시도합니다.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
도구 요청이 유효하지 않거나 매개변수가 누락된 경우, Claude는 사용자에게 사과하기 전에 수정하여 2\~3회 재시도합니다.
잘못된 도구 호출을 완전히 없애려면 도구 정의에 `strict: true`를 설정하여 [엄격한 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/strict-tool-use)을 사용하세요. 이렇게 하면 도구 입력이 항상 스키마와 정확히 일치하도록 보장되어 매개변수 누락과 타입 불일치를 방지합니다.
서버 도구에 오류가 발생하면(예: 웹 검색의 네트워크 문제), Claude는 이러한 오류를 투명하게 처리하고 사용자에게 대안적인 응답이나 설명을 제공하려고 시도합니다. 클라이언트 도구와 달리, 서버 도구에 대해서는 `is_error` 결과를 처리할 필요가 없습니다.
특히 웹 검색의 경우 가능한 오류 코드는 다음과 같습니다.
* `too_many_requests`: 속도 제한 초과
* `invalid_input`: 잘못된 검색 쿼리 매개변수
* `max_uses_exceeded`: 웹 검색 도구 최대 사용 횟수 초과
* `query_too_long`: 쿼리가 최대 길이를 초과함
* `unavailable`: 내부 오류 발생
## 다음 단계
Claude가 한 턴에 여러 도구를 호출하는 응답을 처리합니다.
SDK가 `tool_use` 루프, 결과 포맷, 재시도를 대신 관리하도록 합니다.
Claude를 올바른 도구로 이끄는 스키마와 설명을 작성합니다.