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

このページでは、ツール定義のプロンプトキャッシングについて説明します。具体的には、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 分間のキャッシュ書き込みが表示されることがあります。

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



ツールごとの相互作用表



次のステップ