도구 레퍼런스

도구 레퍼런스 (Tool reference)

이 페이지는 Anthropic이 제공하는 도구들과 모든 도구 정의에 설정할 수 있는 선택 속성들에 대한 레퍼런스예요. 도구 사용의 개념적 소개는 Claude에서의 도구 사용을, 애플리케이션에 도구 사용을 구현하는 안내는 도구 정의하기를 참고하세요.

출처: 문서

본문

이 페이지는 Anthropic이 제공하는 도구들 그리고 어떤 도구 정의에도 설정할 수 있는 선택 속성들에 대한 레퍼런스예요. 도구 사용의 개념적 소개는 Claude에서의 도구 사용을, 애플리케이션에 도구 사용 구현에 대한 안내는 도구 정의하기를 참고하세요.

Anthropic 제공 도구 (Anthropic-provided tools)

Anthropic은 두 종류의 도구를 제공해요. 서버 도구는 Anthropic의 인프라에서 실행되고, 클라이언트 도구는 Anthropic이 스키마를 정의하지만 실행은 우리 애플리케이션이 처리해요. 두 종류 모두 요청의 tools 배열에 사용자 정의 도구와 함께 나타나요.

모델 호환성은 각 도구의 페이지를 참고하세요. 지원 모델은 도구와 도구 버전에 따라 달라져요.

도구 버전 관리 (Tool versioning)

대부분의 Anthropic 제공 도구는 type 문자열에 _YYYYMMDD 접미사를 가져요. 도구의 동작, 스키마, 모델 지원이 바뀌면 새 버전이 출시돼요. 기존 통합이 계속 동작하도록 이전 버전도 사용 가능하게 남아 있어요.

도구가 여러 활성 버전을 가질 때 그 관계는 다양해요:

• 기능 키(Keyed): web_search_20260209와 web_fetch_20260209는 이전 버전에 동적 콘텐츠 필터링을 추가해요. web_fetch_20260309는 캐시 우회 옵션을, web_search_20260318과 web_fetch_20260318은 응답 포함 제어를 추가해요. code_execution_20260120은 샌드박스 안에서 프로그래매틱 도구 호출을 추가하고, code_execution_20260521은 셀별 시간 제한을 도구 설명에 공개해요. 각 경우 새 버전과 이전 버전 모두 현재 상태이고, 새 기능이 필요한지에 따라 어느 것을 쓸지 정해요.
• 모델 키(Keyed): 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 헤더로 전달돼요.

클라이언트 툴셋 (Client toolsets)

컴퓨터 사용 도구와 브라우저 사용 도구는 Anthropic 정의 클라이언트 툴셋이에요. tools의 한 항목이 멤버 도구의 고정 세트를 선언하고, 그 이름·설명·입력 스키마는 Anthropic이 정의하며, 우리 애플리케이션이 모든 호출을 실행해요. 날짜가 붙은 type이 멤버 이름을 고정하므로 항목은 name을 받지 않아요. configs, cache_control, allowed_callers(["direct"]만 허용)는 선택 사항이에요.

클라이언트 툴셋은 Messages API 도구예요. 자체 내장 에이전트 툴셋, MCP 툴셋, 커스텀 도구를 제공하는 Claude Managed Agents에서는 현재 에이전트 도구로 사용할 수 없어요.

{
  "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라는 도구처럼요. 두 툴셋은 함께 선언할 수 있어요.

도구 정의 속성 (Tool definition properties)

tools 배열의 모든 도구(사용자 정의 도구 포함)는 도구가 어떻게 로드되는지, 누가 호출할 수 있는지, 입력이 어떻게 검증되는지 제어하는 선택 속성을 받아요. 이 속성들은 합쳐져요. 같은 도구에 defer_loading과 cache_control과 strict를 모두 설정할 수 있어요.

allowed_callers 값 (allowed_callers values)

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 and prompt caching)

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

따라서 defer_loading: true는 프롬프트 캐시를 보존해요. 기존 캐시 항목을 무효화하지 않고 요청에 지연된 도구를 추가할 수 있고, 도구가 발견되는 턴과 호출되는 턴에 걸쳐 캐시가 유효하게 유지돼요.

defer_loading을 cache_control 중단점과 결합하는 방법은 도구 검색 도구 프롬프트 캐싱 안내를 참고하세요.

더 알아보기 (Learn more)

• Claude에서의 도구 사용 개요
• 도구 정의하기
• 도구 검색 (Tool search)