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

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

Записи наборов инструментов computer use (использование компьютера) и browser use (использование браузера) следуют тому же правилу: разместите cache_control на самой записи набора инструментов, и точка останова окажется после определения набора. Внутри записи configs отдельного участника она не принимается, поскольку участники набора загружаются как одно определение. В рамках пакетного действия маркер cache_control на любом из блоков tool_use или tool_result участников данного хода принимается и вступает в силу в конце этого пакета, поэтому несколько маркеров в одном пакете действуют как одна точка останова. Каждый маркер по-прежнему учитывается в лимите запроса в четыре точки останова, поэтому используйте по одному на ход.

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. Запросы без кэширования подсказок не получают автоматическую точку останова.

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

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