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

이 페이지는 도구 정의에 대한 "prompt caching"(프롬프트 캐싱)을 다룹니다. cache_control 중단점을 어디에 배치할지, defer_loading이 어떻게 캐시를 보존하는지, 그리고 무엇이 캐시를 무효화하는지를 설명합니다. 일반적인 프롬프트 캐싱에 대해서는 프롬프트 캐싱을 참조하세요.



도구 정의의 cache_control

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 마커를 배치할 수 있으며, 이는 해당 배치의 끝에서 효력을 발휘합니다. 따라서 하나의 배치에 여러 마커가 있어도 단일 중단점으로 작동합니다. 각 마커는 여전히 요청당 네 개의 중단점 제한에 포함되므로, 턴당 하나만 사용하세요.



defer_loading과 캐시 보존

지연 로드된 도구는 시스템 프롬프트 접두사에 포함되지 않습니다. 모델이 도구 검색을 통해 지연 로드된 도구를 발견하면, 해당 정의는 대화 기록에 tool_reference 블록으로 인라인 추가됩니다. 접두사는 변경되지 않으므로 프롬프트 캐싱이 보존됩니다.

즉, 도구 검색을 통해 도구를 동적으로 추가해도 캐시가 깨지지 않습니다. 항상 로드되는 소규모 도구 세트(캐시됨)로 대화를 시작하고, 모델이 필요에 따라 추가 도구를 발견하도록 하면서, 모든 턴에 걸쳐 동일한 캐시 히트를 유지할 수 있습니다.

defer_loading은 또한 엄격 모드의 문법 구성과 독립적으로 작동합니다. 문법은 어떤 도구가 지연 로드되는지와 관계없이 전체 도구 세트로부터 구축되므로, 도구가 동적으로 로드될 때 프롬프트 캐싱과 문법 캐싱이 모두 보존됩니다.



캐시를 무효화하는 요소

캐시는 접두사 계층 구조(tools → system → messages)를 따르므로, 한 수준에서의 변경은 해당 수준과 그 이후의 모든 것을 무효화합니다:



서버 도구 결과는 자동으로 캐시됩니다

요청에 프롬프트 캐싱이 활성화되어 있고 Claude가 웹 검색, 웹 가져오기, 코드 실행과 같은 서버 도구를 사용하는 경우, API는 에이전트 루프의 다음 반복을 실행하기 전에 서버 도구 결과에 자동으로 캐시 중단점을 배치합니다. 이를 통해 동일한 요청 내의 이후 반복에서 점점 커지는 접두사를 다시 처리하는 대신 캐시에서 읽을 수 있습니다.

이 자동 중단점은 사용자가 자신의 cache_control 마커에 설정한 TTL과 관계없이 항상 기본 5분 TTL을 사용합니다. 응답의 usage에서 이러한 쓰기는 cache_creation.ephemeral_5m_input_tokens 아래에 표시되므로, 설정한 모든 cache_control이 1시간 TTL을 사용하더라도 5분 캐시 쓰기가 표시될 수 있습니다.

이 동작은 요청에 이미 하나 이상의 cache_control 마커가 있는 경우에만 적용됩니다. 프롬프트 캐싱이 없는 요청에는 자동 중단점이 적용되지 않습니다.



도구별 상호작용 표



다음 단계