Использование инструментов с кэшированием подсказок

На этой странице рассматривается кэширование подсказок для определений инструментов: где размещать точки останова 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), поэтому изменение на одном уровне инвалидирует этот уровень и всё, что следует за ним:



Результаты серверных инструментов кэшируются автоматически

Когда в вашем запросе включено кэширование подсказок и Claude использует серверный инструмент, такой как веб-поиск, веб-загрузка или выполнение кода, API автоматически размещает точку останова кэша на результате серверного инструмента перед запуском следующей итерации агентного цикла. Это позволяет последующим итерациям в рамках того же запроса читать растущий префикс из кэша вместо его повторной обработки.

Эта автоматическая точка останова всегда использует TTL по умолчанию в 5 минут, независимо от любого TTL, который вы установили на собственных маркерах cache_control. В поле usage ответа эти записи отображаются в cache_creation.ephemeral_5m_input_tokens, поэтому вы можете увидеть записи в 5-минутный кэш, даже если каждый установленный вами cache_control использует TTL в 1 час.

Это поведение применяется только тогда, когда в вашем запросе уже есть хотя бы один маркер cache_control. Запросы без кэширования подсказок не получают автоматическую точку останова.



Таблица взаимодействия по инструментам



Следующие шаги