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

このページでは、ツール定義に対する「prompt caching」（プロンプトキャッシング）について説明します。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がそれを展開後の最後のツールに適用します。

コンピュータ使用およびブラウザ使用のツールセットエントリも同じルールに従います。cache_control はツールセットエントリ自体に配置し、ブレークポイントはツールセットの定義の後に配置されます。ツールセットのメンバーは1つの定義として読み込まれるため、メンバーの configs エントリ内では受け付けられません。バッチアクション内では、そのターンのメンバーの tool_use または tool_result ブロックのいずれかに付けられた cache_control マーカーは受け付けられ、そのバッチの終わりで有効になります。そのため、1つのバッチ内の複数のマーカーは単一のブレークポイントとして機能します。各マーカーは依然としてリクエストの4つのブレークポイントという上限にカウントされるため、ターンごとに1つ使用してください。

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 マーカーがある場合にのみ適用されます。プロンプトキャッシングのないリクエストには、自動ブレークポイントは付与されません。

ツールごとの相互作用表

次のステップ