도구 레퍼런스

이 페이지는 Anthropic이 제공하는 도구와 모든 도구 정의에 설정할 수 있는 선택적 속성에 대한 레퍼런스입니다. "tool use"(도구 사용)에 대한 개념적 소개는 Claude와 함께하는 도구 사용을 참조하세요. 애플리케이션에서 도구 사용을 구현하는 방법에 대한 안내는 도구 정의하기를 참조하세요.

Anthropic 제공 도구

Anthropic은 두 가지 종류의 도구를 제공합니다. Anthropic의 인프라에서 실행되는 서버 도구와, Anthropic이 스키마를 정의하지만 실행은 여러분의 애플리케이션이 처리하는 클라이언트 도구입니다. 두 종류 모두 사용자 정의 도구와 함께 요청의 tools 배열에 포함됩니다.

모델 호환성은 각 도구의 페이지를 참조하세요. 지원되는 모델은 도구 및 도구 버전에 따라 다릅니다.

도구 버전 관리

대부분의 Anthropic 제공 도구는 type 문자열에 _YYYYMMDD 접미사를 가집니다. 도구의 동작, 스키마 또는 모델 지원이 변경되면 새 버전이 릴리스됩니다. 기존 통합이 계속 작동하도록 이전 버전도 계속 사용할 수 있습니다.

도구에 여러 활성 버전이 있는 경우, 버전 간의 관계는 다양합니다.

• 기능 기반: web_search_20260209와 web_fetch_20260209는 이전 버전에 비해 동적 콘텐츠 필터링을 추가합니다. web_fetch_20260309는 캐시 우회 옵션을 추가하고, web_search_20260318과 web_fetch_20260318은 응답 포함 제어를 추가합니다. code_execution_20260120은 샌드박스 내에서의 프로그래매틱 도구 호출을 추가하고, code_execution_20260521은 도구 설명에 셀당 시간 제한을 명시합니다. 각 경우 새 버전과 이전 버전 모두 현재 버전이며, 어떤 버전을 사용할지는 새 기능이 필요한지 여부에 따라 달라집니다.
• 모델 기반: text_editor_20250728은 Claude 4 이상 모델용이고 text_editor_20250124는 이전 모델용입니다. 사용할 버전은 대상 모델에 따라 달라집니다.
• 버전이 아닌 변형: tool_search_tool_regex_20251119와 tool_search_tool_bm25_20251119는 함께 출시된 두 가지 검색 알고리즘입니다. 어느 쪽도 다른 쪽을 대체하지 않습니다.
• 레거시: code_execution_20250522는 Python만 지원합니다. code_execution_20250825는 Bash 및 파일 작업을 추가합니다.
• 후속 버전: computer_toolset_20260801은 베타 버전인 computer_20251124 및 computer_20250124의 안정적인 후속 버전이며, 이 베타 버전들은 이전 도구 버전에 나열된 모델에서 계속 사용할 수 있습니다. browser_toolset_20260801은 브라우저 사용 도구의 첫 번째 버전입니다. 둘 다 클라이언트 도구 세트입니다.

mcp_toolset 타입은 날짜로 버전이 지정되지 않으며, 대신 anthropic-beta 헤더로 버전이 관리됩니다.

클라이언트 도구 세트

컴퓨터 사용 도구와 브라우저 사용 도구는 Anthropic이 정의한 "client toolsets"(클라이언트 도구 세트)입니다. tools의 항목 하나가 Anthropic이 이름, 설명, 입력 스키마를 정의한 고정된 멤버 도구 집합을 선언하며, 모든 호출은 여러분의 애플리케이션이 실행합니다. 날짜가 지정된 type이 멤버 이름을 고정하므로 이 항목은 name을 받지 않습니다. configs, cache_control, allowed_callers(["direct"]만 허용)는 선택 사항입니다.

클라이언트 도구 세트는 Messages API 도구입니다. 현재 Claude Managed Agents에서는 에이전트 도구로 사용할 수 없으며, Claude Managed Agents는 자체 내장 에이전트 도구 세트, MCP 도구 세트, 커스텀 도구를 제공합니다.

{
  "type": "browser_toolset_20260801",
  "configs": {
    "javascript_exec": { "enabled": true }
  },
  "cache_control": { "type": "ephemeral" }
}

configs는 개별 멤버를 조정합니다.

• 키는 멤버 이름이며, 각 값은 enabled와 defer_loading만 허용합니다.
• 생략한 멤버는 기본값을 유지합니다. 값이 없는 경우, {}, 기본값을 다시 명시한 경우는 모두 동일합니다.
• 알 수 없는 멤버 이름이나 멤버 값의 다른 필드는 거부되며, 모든 멤버를 비활성화하는 configs도 거부됩니다(대신 항목을 생략하세요).
• 비활성화된 멤버는 Claude가 보는 도구에서 제거됩니다. Claude가 여전히 해당 멤버를 지정하면 오류 tool_result를 반환하세요.

defer_loading은 항목이 아닌 멤버별로 설정하고, 활성화된 모든 멤버에 동일한 값을 지정하세요. 도구 검색에서 도구 세트는 하나의 정의로 로드되고 확장됩니다. 활성화된 모든 멤버가 지연 로드되는 경우, 자체적으로 지연되지 않은 도구 검색 도구만이 도구 세트를 노출할 수 있으므로 같은 요청에 하나를 선언하세요. 멤버가 지연 로드되는 도구 세트 항목에는 cache_control을 두지 마세요. 지연된 정의는 캐시된 접두사의 일부가 아니므로, 대신 지연되지 않은 도구에 중단점을 설정하세요.

cache_control은 항목에만 설정합니다. 배치 액션 내부의 마커를 포함하여 중단점이 어디에 위치하는지 알아보려면 프롬프트 캐싱과 함께하는 도구 사용을 참조하세요.

멤버 도구 호출 처리. Claude는 name이 멤버 이름이고 toolset_name이 computer 또는 browser인 tool_use 블록으로 멤버를 호출합니다. input에는 해당 멤버의 매개변수가 담기며 action 필드는 없습니다. 커스텀 도구가 멤버와 이름을 공유할 수 있고 두 도구 세트가 screenshot 같은 이름을 공유하므로, toolset_name과 name 쌍을 기준으로 디스패치하세요. 멤버 결과만 toolset_name을 되돌려 줍니다. 한 턴에서 여러 멤버 호출은 순서대로 실행하는 배치 액션을 형성합니다(컴퓨터 사용, 브라우저 사용). 새 멤버는 새로운 날짜의 type과 함께만 추가됩니다.

도구 세트 항목에서 지원되지 않는 사항. API는 다음 각각을 invalid_request_error로 거부합니다.

• strict: true 또는 input_examples.
• 항목에 설정된 defer_loading, 또는 defer_loading 값이 서로 다른 활성화된 멤버들(configs에서 멤버별로, 모두 같은 값으로 설정하세요).
• allowed_callers의 코드 실행 호출자(프로그래매틱 도구 호출 불가).
• 레거시 fine-grained-tool-streaming-2025-05-14 베타 헤더. 스트리밍 시 각 멤버의 input은 하나의 완전한 input_json_delta로 도착합니다.
• 도구 세트나 멤버를 지정하는 tool 타입의 tool_choice(auto, any 또는 none을 사용하세요).
• 동일한 도구 세트의 항목 두 개, 또는 해당 도구 세트의 이름을 가진 다른 도구: computer_toolset_20260801과 함께 computer라는 이름의 도구, 또는 browser_toolset_20260801과 함께 browser라는 이름의 도구. 두 도구 세트는 함께 선언할 수 있습니다.

도구 정의 속성

사용자 정의 도구를 포함하여 tools 배열의 모든 도구는 도구가 로드되는 방식, 호출할 수 있는 주체, 입력 검증 방식을 제어하는 선택적 속성을 허용합니다. 이러한 속성은 조합할 수 있습니다. 같은 도구에 defer_loading, cache_control, strict를 함께 설정할 수 있습니다.

allowed_callers 값

allowed_callers는 다음의 임의 조합을 허용하는 배열입니다.

"code_execution_20260120"과 "code_execution_20260521" 모두 allowed_callers에서 허용되며 서로 교환 가능합니다. 어느 코드 실행 도구 버전을 사용하는 요청이든 어느 호출자를 나열한 도구든 충족합니다. 응답 블록은 요청이 선언한 버전과 관계없이 항상 호출자를 code_execution_20260120으로 태그합니다.

배열에서 "direct"를 생략하면(예: "allowed_callers": ["code_execution_20260120"]) Claude가 코드 실행 내부에서만 도구를 호출하도록 유도합니다. 응답의 tool_use 블록에는 어떤 호출자가 도구를 호출했는지 식별하는 caller 필드가 포함됩니다. caller 응답 형태와 오류 동작을 포함한 전체 내용은 프로그래매틱 도구 호출을 참조하세요.

defer_loading과 프롬프트 캐싱

defer_loading: true인 도구는 캐시 키가 계산되기 전에 렌더링된 도구 섹션에서 제거됩니다. 시스템 프롬프트 접두사에 전혀 나타나지 않습니다. 도구 검색이 지연된 도구를 발견하고 해당 도구에 대한 tool_reference를 반환하면, 도구의 전체 정의는 접두사가 아닌 대화 본문의 해당 지점에서 인라인으로 확장됩니다.

이는 defer_loading: true가 프롬프트 캐시를 보존한다는 것을 의미합니다. 기존 캐시 항목을 무효화하지 않고 요청에 지연된 도구를 추가할 수 있으며, 도구가 발견되는 턴과 호출되는 턴에 걸쳐 캐시가 유효하게 유지됩니다.

defer_loading을 cache_control 중단점과 결합하는 방법을 알아보려면 도구 검색 도구 프롬프트 캐싱 안내를 참조하세요.