도구 사용

Anthropic Claude 모델을 사용하면 모델이 메시지에 응답하는 데 사용할 수 있는 도구를 지정할 수 있습니다. 예를 들어, 라디오 방송국에서 가장 인기 있는 노래를 가져오는 도구를 지정할 수 있습니다. 사용자가 WZPZ에서 가장 인기 있는 노래는 무엇인가요?라는 메시지를 전달하면 모델은 지정된 도구가 질문에 답변하는 데 도움이 될 수 있다는 판단을 내립니다. 응답에서 모델은 사용자에게 해당 도구를 실행해 달라고 요청합니다. 사용자가 도구를 실행하고 도구 결과를 모델에 전달하면 원래 메시지에 대한 응답이 생성됩니다. 자세한 내용은 Anthropic Claude 설명서의 도구 사용(함수 직접 호출)을 참조하세요.

tools 필드에서 모델이 사용할 수 있게 하려는 도구를 지정합니다. 다음 예제는 라디오 방송국에서 가장 인기 있는 노래를 가져오는 도구입니다.

[
    {
        "name": "top_song",
        "description": "Get the most popular song played on a radio station.",
        "input_schema": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
                }
            },
            "required": [
                "sign"
            ]
        }
    }
]

모델에 메시지에 대한 응답을 생성하는 도구가 필요한 경우, 요청된 도구에 대한 정보와 도구에 대한 입력이 메시지 content 필드에 반환됩니다. 모델은 tool_use에 대한 응답의 중지 이유도 설정합니다.

{
    "id": "msg_bdrk_01USsY5m3XRUF4FCppHP8KBx",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 375,
        "output_tokens": 36
    },
    "content": [
        {
            "type": "tool_use",
            "id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "name": "top_song",
            "input": {
                "sign": "WZPZ"
            }
        }
    ],
    "stop_reason": "tool_use"
}

코드에서 사용자가 도구를 대신하여 도구를 직접 호출합니다. 그런 다음 사용자 메시지의 도구 결과(tool_result)를 모델에 전달합니다.

{
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_bdrk_01SnXQc6YVWD8Dom5jz7KhHy",
            "content": "Elemental Hotel"
        }
    ]
}

응답에서 모델은 도구 결과를 사용하여 원본 메시지에 대한 응답을 생성합니다.

{
    "id": "msg_bdrk_012AaqvTiKuUSc6WadhUkDLP",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "content": [
        {
            "type": "text",
            "text": "According to the tool, the most popular song played on radio station WZPZ is \"Elemental Hotel\"."
        }
    ],
    "stop_reason": "end_turn"
}

세분화된 도구 스트리밍

세분화된 도구 스트리밍은 Claude Sonnet 4.5, Claude Haiku 4.5, Claude Sonnet 4 및 Claude Opus 4에서 사용할 수 있는 Anthropic Claude 모델 기능입니다. Claude 개발자는 세분화된 도구 스트리밍을 통해 버퍼링 또는 JSON 검증 없이 파라미터를 사용하여 도구를 스트리밍하여 대규모 파라미터 수신을 시작하는 지연 시간을 줄일 수 있습니다.

이 기능을 사용하려면 도구 사용 요청에 fine-grained-tool-streaming-2025-05-14 헤더를 추가하기만 하면 됩니다.

다음은 세분화된 도구 스트리밍 헤더를 지정하는 방법의 예입니다.

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 1024,
  "anthropic_beta": ["fine-grained-tool-streaming-2025-05-14"],
  "messages": [
    {
      "role": "user",
      "content": "Can you write a long poem and make a file called poem.txt?"
    }
  ],
  "tools": [
    {
      "name": "make_file",
      "description": "Write text to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The filename to write text to"
          },
          "lines_of_text": {
            "type": "array",
            "description": "An array of lines of text to write to the file"
          }
        },
        "required": [
          "filename",
          "lines_of_text"
        ]
      }
    }
  ]
}

이 예제에서는 세분화된 도구 스트리밍을 통해 Claude는 lines_of_text 파라미터가 유효한 JSON인지 검증하기 위해 버퍼링 없이 긴 시의 라인을 make_file 도구 직접 호출로 스트리밍할 수 있습니다. 즉, 전체 파라미터가 버퍼링되고 검증될 때까지 기다릴 필요 없이 파라미터 스트림이 도착하면 볼 수 있습니다.

세분화된 도구 스트리밍을 사용하면 도구 사용 청크가 스트리밍을 더 빠르게 시작하고, 더 길고 단어 나누기가 적은 경우가 많습니다. 이는 청킹 동작의 차이 때문입니다.

예를 들어 세분화된 스트리밍(15초 지연)이 없는 경우:

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

세분화된 스트리밍(3초 지연):

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

컴퓨터 사용(베타)

컴퓨터 사용은 Claude 3.5 Sonnet v2, Claude Sonnet 4.5, Claude Haiku 4.5, Claude 3.7 Sonnet, Claude Sonnet 4 및 Claude Opus 4에서만 사용할 수 있는 새로운 Anthropic Claude 모델 기능(베타)입니다. 컴퓨터 사용 기능을 사용하면 Claude가 기본 GUI 작업을 통해 작업을 자동화하는 데 도움을 줍니다.

컴퓨터 사용 API는 사용자가 사용할 수 있도록 사전 정의된 여러 컴퓨터 사용 도구를 제공합니다. 그런 다음 “지난 회의의 메모가 포함된 이메일을 Ben에게 전송해 줘” 같은 프롬프트와 스크린샷(필요한 경우)과 같은 프롬프트를 작성할 수 있습니다. 응답에는 JSON 형식의 tool_use 작업 목록이 포함됩니다(예: scroll_down, left_button_press, screenshot). 코드는 컴퓨터 작업을 실행하고, Claude에 요청 시 출력을 보여주는 스크린샷을 제공합니다.

Claude 3.5 v2, 릴리스 이후로, 도구 파라미터가 다형성 도구 유형을 허용하도록 업데이트되었습니다. 이를 구분하기 위해 tool.type 속성이 추가되었습니다. type은 선택 사항이며, 생략된 경우 도구는 사용자 지정 도구로 간주됩니다(이전에 유일하게 지원된 도구 유형). 컴퓨터 사용에 액세스하려면 anthropic_beta 파라미터를 사용 중인 모델 버전에 따라 값이 달라지는 해당 열거형과 함께 사용해야 합니다. 자세한 정보는 다음 표를 참조하세요.

이 파라미터와 열거형으로 이루어진 요청만 컴퓨터 사용 도구를 사용할 수 있습니다. "anthropic_beta": ["computer-use-2025-01-24"]와 같이 지정할 수 있습니다.

자세한 내용은 Anthropic 설명서의 컴퓨터 사용(베타)을 참조하세요.

다음은 Firefox 아이콘이 있는 바탕 화면의 스크린샷이 요청에 포함되어 있다고 가정한 응답 예제입니다.

{
    "id": "msg_123",
    "type": "message",
    "role": "assistant",
    "model": "anthropic.claude-3-5-sonnet-20241022-v2:0",
    "content": [
        {
            "type": "text",
            "text": "I see the Firefox icon. Let me click on it and then navigate to a weather website."
        },
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "computer",
            "input": {
                "action": "mouse_move",
                "coordinate": [
                    708,
                    736
                ]
            }
        },
        {
            "type": "tool_use",
            "id": "toolu_234",
            "name": "computer",
            "input": {
                "action": "left_click"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 3391,
        "output_tokens": 132
    }
}

Anthropic 정의된 도구

Anthropic은 특정 Claude 모델이 컴퓨터를 효과적으로 사용할 수 있도록 일련의 도구를 제공합니다. Anthropic 정의된 도구를 지정할 때 description 및 tool_schema 필드는 필요하거나 허용되지 않습니다. Anthropic 정의된 도구는 Anthropic에서 정의하지만 도구의 결과를 명시적으로 평가하고 tool_results를 Claude에 반환해야 합니다. 다른 도구와 마찬가지로 모델은 도구를 자동으로 실행하지 않습니다. Anthropic 정의된 각 도구에는 특정 모델 Claude 3.5 Sonnet(신규) 및 Claude 3.7 Sonnet에 최적화된 버전이 있습니다.

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_based_edit_tool" 
}

{ 
    "type": "computer_20250124", 
    "name": "computer" 
}

{ 
    "type": "text_editor_20250124", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20250124", 
    "name": "bash" 
}

{ 
    "type": "text_editor_20241022", 
    "name": "str_replace_editor"
}

{ 
    "type": "bash_20241022", 
    "name": "bash"
}

{ 
    "type": "computer_20241022", 
    "name": "computer"
}

type 필드는 검증을 위해 도구와 해당 파라미터를 식별하며, name 필드는 모델에 노출된 도구 이름입니다.

이러한 도구 중 하나를 사용하도록 모델에 프롬프트를 표시하려면 name 필드별로 도구를 명시적으로 참조할 수 있습니다. name 필드는 도구 목록 내에서 고유해야 합니다. 동일한 API 직접 호출에서 Anthropic 정의된 도구와 동일한 name으로 도구를 정의할 수 없습니다.

자동 도구 직접 호출 지우기(베타)

자동 도구 호출 지우기는 Anthropic Claude 모델 기능(베타)입니다. 이 기능을 사용하면 Claude는 토큰 한도에 가까워지면 이전 도구 사용 결과를 자동으로 지울 수 있으므로 멀티턴 도구 사용 시나리오에서 보다 효율적인 컨텍스트 관리를 수행할 수 있습니다. 도구를 사용하려면 anthropic_beta 요청 파라미터의 베타 헤더 목록에 context-management-2025-06-27을 추가해야 합니다. 또한의 사용을 지정clear_tool_uses_20250919하고 다음 구성 옵션 중에서 선택해야 합니다.

다음은 clear_tool_uses_20250919 컨텍스트 관리 전략에 사용할 수 있는 제어입니다. 모두 선택 사항이거나 기본값이 있습니다.

메모리 도구(베타)

Claude Sonnet 4.5에는 고객에게 대화 전반에 걸쳐 메모리를 관리할 수 있는 방법을 제공하는 새로운 메모리 도구가 포함되어 있습니다. 이 기능을 사용하면 고객은 Claude가 로컬 디렉터리에 대한 액세스를 제공하여 컨텍스트 기간 외부에서 정보를 검색하도록 허용할 수 있습니다. 베타 기능으로 사용할 수 있습니다. 이 기능을 사용하려면 context-management-2025-06-27 베타 헤더를 사용해야 합니다.

도구 정의:

{
  "type": "memory_20250818",
  "name": "memory"
}

요청 예시:

{
    "max_tokens": 2048,
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["context-management-2025-06-27"],
    "tools": [{
        "type": "memory_20250818",
        "name": "memory"
    }],
    "messages": [
        {
            "role": "user",
            "content": [{"type": "text", "text": "Remember that my favorite color is blue and I work at Amazon?"}]
        }
    ]
}

응답의 예:

{
    "id": "msg_vrtx_014mQ5ficCRB6PEa5k5sKqHd",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-20250514",
    "content": [
        {
            "type": "text",
            "text": "I'll start by checking your memory directory and then record this important information about you."
        },
        {
            "type": "tool_use",
            "id": "toolu_vrtx_01EU1UrCDigyPMRntr3VYvUB",
            "name": "memory",
            "input": {
                "command": "view",
                "path": "/memories"
            }
        }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 1403,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "output_tokens": 87
    },
    "context_management": {
        "applied_edits": []
    }
}

도구 사용에 대한 비용 고려 사항

도구 사용 요청은 다음 요인에 따라 요금이 책정됩니다.

도구는 다른 모든 Claude API 요청과 가격이 동일하지만 요청당 추가 토큰을 포함합니다. 도구 사용의 추가 토큰은 다음에서 가져옵니다.

도구를 사용하면 Anthropic 모델에는 도구 사용을 활성화하는 특수 시스템 프롬프트가 자동으로 포함됩니다. 각 모델에 필요한 도구 사용 토큰 수는 다음 표에 나와 있습니다. 이 표에는 앞서 설명한 추가 토큰이 제외됩니다. 이 표는 하나 이상의 도구가 제공되었다고 가정합니다. 도구가 제공되지 않은 경우 아무것도 선택하지 않으면 0개의 추가 시스템 프롬프트 토큰이 사용됩니다.

도구 검색 도구(베타)

도구 검색 도구를 사용하면 모든 정의를 컨텍스트 창에 미리 로드하지 않고도 수백 또는 수천 개의 도구를 Claude 사용할 수 있습니다. 모든 도구를 즉시 선언하는 대신 로 표시하고 도구 검색 메커니즘을 통해 필요한 도구만 defer_loading: true Claude 찾아 로드할 수 있습니다.

이 기능에 액세스하려면 베타 헤더를 사용해야 합니다tool-search-tool-2025-10-19. 이 기능은 현재 InvokeModel 및 InvokeModelWithResponseStream APIs.

도구 정의:

{
    "type": "tool_search_tool_regex",
    "name": "tool_search_tool_regex"
}

요청 예:

{
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": [
        "tool-search-tool-2025-10-19"
    ],
    "max_tokens": 4096,
    "tools": [{
            "type": "tool_search_tool_regex",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string"
                    },
                    "file_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": ["query"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather in Seattle?"
    }]
}

응답 예제

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with this task."
        },
        {
            "type": "server_tool_use",
            "id": "srvtoolu_01ABC123",
            "name": "tool_search_tool_regex",
            "input": {
                "pattern": "weather"
            }
        },
        {
            "type": "tool_search_tool_result",
            "tool_use_id": "srvtoolu_01ABC123",
            "content": {
                "type": "tool_search_tool_search_result",
                "tool_references": [{
                    "type": "tool_reference",
                    "tool_name": "get_weather"
                }]
            }
        },
        {
            "type": "text",
            "text": "Now I can check the weather."
        },
        {
            "type": "tool_use",
            "id": "toolu_01XYZ789",
            "name": "get_weather",
            "input": {
                "location": "Seattle",
                "unit": "fahrenheit"
            }
        }
    ],
    "stop_reason": "tool_use"
}

스트리밍 예제

# Event 1: content_block_start(with complete server_tool_use block) {
    "type": "content_block_start",
    "index": 0,
    "content_block": {
        "type": "server_tool_use",
        "id": "srvtoolu_01ABC123",
        "name": "tool_search_tool_regex"
    }
}

# Event 2: content_block_delta(input JSON streamed) {
    "type": "content_block_delta",
    "index": 0,
    "delta": {
        "type": "input_json_delta",
        "partial_json": "{\"regex\": \".*weather.*\"}"
    }
}

# Event 3: content_block_stop(tool_use complete) {
    "type": "content_block_stop",
    "index": 0
}

# Event 4: content_block_start(COMPLETE result in single chunk) {
    "type": "content_block_start",
    "index": 1,
    "content_block": {
        "type": "tool_search_tool_result",
        "tool_use_id": "srvtoolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }
}

# Event 5: content_block_stop(result complete) {
    "type": "content_block_stop",
    "index": 1
}

사용자 지정 도구 검색 도구

tool_reference 블록을 반환하는 도구를 정의하여 사용자 지정 도구 검색 도구(예: 임베딩 사용)를 구현할 수 있습니다. 사용자 지정 도구에는이 있고 defer_loading: false 다른 도구에는이 있어야 합니다defer_loading: true. 자체 도구 검색 도구를 정의할 때 사용Claude하려는 도구를 가리키는 tool_reference 콘텐츠 블록이 포함된 도구 결과를 반환해야 합니다.

예상되는 고객 정의 도구 검색 도구 결과 응답 형식:

{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC123",
    "content": [{
            "type": "tool_reference",
            "tool_name": "get_weather"
        },
        {
            "type": "tool_reference",
            "tool_name": "weather_forecast"
        }
    ]
}

는 요청에 정의된 도구와를 일치해야 tool_name 합니다defer_loading: true. 그러면 Claude는 해당 도구의 전체 스키마에 액세스할 수 있습니다.

사용자 지정 검색 도구 - 세부 예제

tool_reference 블록을 반환하는 도구를 정의하여 사용자 지정 도구 검색 도구(예: 임베딩 또는 의미 검색 사용)를 구현할 수 있습니다. 이를 통해 정규식 일치 이상의 정교한 도구 검색 메커니즘을 사용할 수 있습니다.

사용자 지정 TST를 사용한 요청 예제:

{
    "model": "claude-sonnet-4-5-20250929",
    "anthropic_version": "bedrock-2023-05-31",
    "anthropic_beta": ["tool-search-tool-2025-10-19"],
    "max_tokens": 4096,
    "tools": [{
            "name": "semantic_tool_search",
            "description": "Search for available tools using semantic similarity. Returns the most relevant tools for the given query.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Natural language description of what kind of tool is needed"
                    },
                    "top_k": {
                        "type": "integer",
                        "description": "Number of tools to return (default: 5)"
                    }
                },
                "required": ["query"]
            },
            "defer_loading": false
        },
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            },
            "defer_loading": true
        },
        {
            "name": "search_flights",
            "description": "Search for available flights between locations",
            "input_schema": {
                "type": "object",
                "properties": {
                    "origin": {
                        "type": "string"
                    },
                    "destination": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string"
                    }
                },
                "required": ["origin", "destination", "date"]
            },
            "defer_loading": true
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What's the weather forecast in Seattle for the next 3 days?"
    }]
}

Claude의 응답(사용자 지정 TST 호출):

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I'll search for the appropriate tools to help with weather information."
        },
        {
            "type": "tool_use",
            "id": "toolu_01ABC123",
            "name": "semantic_tool_search",
            "input": {
                "query": "weather forecast multiple days",
                "top_k": 3
            }
        }
    ],
    "stop_reason": "tool_use"
}

고객이 제공한 도구 결과

도구 라이브러리에서 의미 검색을 수행한 후 고객은 일치하는 도구 참조를 반환합니다.

{
    "role": "user",
    "content": [{
        "type": "tool_search_tool_result",
        "tool_use_id": "toolu_01ABC123",
        "content": {
            "type": "tool_search_tool_search_result",
            "tool_references": [{
                "type": "tool_reference",
                "tool_name": "get_weather"
            }]
        }
    }]
}

Claude의 후속 조치(검색된 도구 사용)

{
    "role": "assistant",
    "content": [{
            "type": "text",
            "text": "I found the forecast tool. Let me get the weather forecast for Seattle."
        },
        {
            "type": "tool_use",
            "id": "toolu_01DEF456",
            "name": "get_weather",
            "input": {
                "location": "Seattle, WA"
            }
        }
    ],
    "stop_reason": "tool_use"
}

도구 사용 예제(베타)

Claude Opus 4.5는 Claude의 도구 사용 성능을 높이기 위해 도구 정의에서 사용자가 제공한 예제를 지원합니다. 다른 형식으로 변환할 필요 없이 실제 LLM 출력과 정확히 동일한 형식의 전체 함수 호출로 예제를 제공할 수 있습니다. 이 기능을 사용하려면 베타 헤더를 전달해야 합니다tool-examples-2025-10-29.

도구 정의 예제:

{
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    },
    "input_examples": [{
            "location": "San Francisco, CA",
            "unit": "fahrenheit"
        },
        {
            "location": "Tokyo, Japan",
            "unit": "celsius"
        },
        {
            "location": "New York, NY"
        }
    ]
}

오류 예제:

// Invalid: Example doesn't match schema (missing required field)
{
    "type": "invalid_request_error",
    "message": "Tool 'get_weather' input_examples[0] is invalid: Missing required property 'location'"
}

// Invalid: Example has wrong type for field
{
    "type": "invalid_request_error",
    "message": "Tool 'search_products' input_examples[1] is invalid: Property 'filters.price_range.min' must be a number, got string"
}

// Invalid: input_examples on server-side tool
{
    "type": "invalid_request_error",
    "message": "input_examples is not supported for server-side tool"
}