プロンプトキャッシングを使用したツール使用

このページでは、ツール定義のプロンプトキャッシングについて説明します。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は、strictモードの文法構築からも独立して動作します。どのツールが遅延されているかに関係なく、文法は完全なツールセットから構築されるため、ツールが動的にロードされてもプロンプトキャッシングと文法キャッシュの両方が保持されます。



何がキャッシュを無効化するか

キャッシュはプレフィックス階層（tools → system → messages）に従うため、あるレベルでの変更はそのレベルとそれ以降のすべてを無効化します。



サーバーツールの結果は自動的にキャッシュされる

リクエストでプロンプトキャッシングが有効になっており、Claudeがウェブ検索、ウェブフェッチ、コード実行などのサーバーツールを使用する場合、APIはエージェントループの次のイテレーションを実行する前に、サーバーツールの結果に自動的にキャッシュブレークポイントを配置します。これにより、同じリクエスト内の後続のイテレーションは、増大するプレフィックスを再処理する代わりにキャッシュから読み取ることができます。

この自動ブレークポイントは、独自のcache_controlマーカーに設定したTTLとは無関係に、常にデフォルトの5分間のTTLを使用します。レスポンスのusageでは、これらの書き込みはcache_creation.ephemeral_5m_input_tokensの下に表示されるため、設定したすべてのcache_controlが1時間のTTLを使用している場合でも、5分間のキャッシュ書き込みが表示されることがあります。

この動作は、リクエストに少なくとも1つのcache_controlマーカーがすでに存在する場合にのみ適用されます。プロンプトキャッシングのないリクエストには自動ブレークポイントは適用されません。



ツールごとの相互作用テーブル



次のステップ