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

이 페이지에서는 도구 정의에 대한 프롬프트 캐싱을 다룹니다: 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가 이를 최종 확장된 도구에 적용합니다.



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 마커가 있는 경우에만 적용됩니다. 프롬프트 캐싱이 없는 요청은 자동 중단점을 받지 않습니다.



도구별 상호작용 표



다음 단계