프롬프트 캐싱과 함께하는 도구 사용

프롬프트 캐싱과 함께하는 도구 사용 (Tool use with prompt caching)

이 페이지는 도구 정의에 대한 프롬프트 캐싱을 다뤄요. cache_control 중단점을 어디에 둘지, defer_loading이 캐시를 어떻게 보존하는지, 무엇이 캐시를 무효화하는지를 다뤄요. 일반적인 프롬프트 캐싱은 프롬프트 캐싱을 참고하세요.

출처: 문서

본문

이 페이지는 도구 정의에 대한 프롬프트 캐싱을 다뤄요. cache_control 중단점을 어디에 둘지, defer_loading이 캐시를 어떻게 보존하는지, 무엇이 캐시를 무효화하는지 알아보아요. 일반적인 프롬프트 캐싱은 프롬프트 캐싱을 참고하세요.

도구 정의의 cache_control (cache_control on tool definitions)

tools 배열의 마지막 도구에 cache_control: {"type": "ephemeral"}을 두세요. 이렇게 하면 첫 도구부터 표시된 중단점까지 전체 도구 정의 접두사가 캐시돼요:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": {
          "timezone": { "type": "string" }
        },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

mcp_toolset의 경우 cache_control 중단점은 세트의 마지막 도구에 찍혀요. MCP 툴셋 안에서는 도구 순서를 제어할 수 없으니, mcp_toolset 항목 자체에 중단점을 두면 API가 최종 확장된 도구에 적용해요.

컴퓨터 사용과 브라우저 사용 툴셋 항목도 같은 규칙을 따라요. 툴셋 항목 자체에 cache_control을 두면 중단점이 툴셋 정의 뒤에 찍혀요. 툴셋의 멤버가 하나의 정의로 로드되므로 멤버의 configs 항목 안에서는 받지 않아요. 배치 동작 안에서는 턴의 멤버 tool_use나 tool_result 블록 중 하나에 있는 cache_control 마커가 허용되고 그 배치 끝에 적용되므로, 한 배치의 여러 마커가 단일 중단점처럼 동작해요. 각 마커는 여전히 요청의 4개 중단점 한도에 계산되니, 턴당 하나를 쓰세요.

defer_loading과 캐시 보존 (defer_loading and cache preservation)

지연된 도구는 시스템 프롬프트 접두사에 포함되지 않아요. 모델이 도구 검색으로 지연된 도구를 발견하면 정의가 대화 기록에 tool_reference 블록으로 인라인 추가돼요. 접두사는 건드리지 않으므로 프롬프트 캐싱이 보존돼요.

즉, 도구 검색으로 도구를 동적으로 추가해도 캐시가 깨지지 않아요. 항상 로드되는 작은 도구 세트(캐시됨)로 대화를 시작하고, 모델이 필요에 따라 추가 도구를 발견하게 하며, 매 턴 같은 캐시 히트를 유지할 수 있어요.

defer_loading은 엄격 모드의 문법 구성과도 독립적으로 동작해요. 문법은 어떤 도구가 지연되는지와 무관하게 전체 툴셋에서 구축되므로, 도구가 동적으로 로드돼도 프롬프트 캐싱과 문법 캐싱이 모두 보존돼요.

무엇이 캐시를 무효화하는가 (What invalidates your cache)

캐시는 접두사 계층(tools → system → messages)을 따르므로, 한 수준의 변경은 그 수준과 그 뒤의 모든 것을 무효화해요:

서버 도구 결과는 자동으로 캐시된다 (Server tool results are cached automatically)

요청에 프롬프트 캐싱이 활성화되어 있고 Claude가 웹 검색, 웹 페치, 코드 실행 같은 서버 도구를 사용하면, API가 에이전틱 루프의 다음 반복을 실행하기 전에 서버 도구 결과에 자동으로 캐시 중단점을 둬요. 이렇게 하면 같은 요청 안의 이후 반복이 커지는 접두사를 다시 처리하는 대신 캐시에서 읽을 수 있어요.

이 자동 중단점은 항상 기본 5분 TTL을 사용하고, 우리가 설정한 cache_control 마커의 어떤 TTL과도 무관해요. 응답 usage에서 이 기록은 cache_creation.ephemeral_5m_input_tokens 아래 나타나므로, 우리가 설정한 모든 cache_control이 1시간 TTL을 써도 5분 캐시 기록이 보일 수 있어요.

이 동작은 요청에 이미 cache_control 마커가 하나 이상 있을 때만 적용돼요. 프롬프트 캐싱이 없는 요청은 자동 중단점을 받지 않아요.

도구별 상호작용 표 (Per-tool interaction table)

더 알아보기 (Learn more)

• 프롬프트 캐싱
• 도구 검색
• 도구 레퍼런스