프롬프트 캐싱을 사용한 도구 사용

이 페이지는 도구 정의에 대한 프롬프트 캐싱을 다룹니다: cache_control 중단점을 배치하는 위치, defer_loading이 캐시를 보존하는 방법, 그리고 캐시를 무효화하는 요소입니다. 일반적인 프롬프트 캐싱에 대해서는 프롬프트 캐싱을 참조하세요.

도구 정의에 대한 cache_control

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

{
  "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)를 따르므로, 한 수준의 변경은 해당 수준과 그 이후의 모든 것을 무효화합니다:

도구별 상호작용 표

다음 단계