--- title: プロンプトキャッシングを使用したツール使用 url: https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-use-with-prompt-caching description: ターンをまたいでツール定義をキャッシュし、何がキャッシュを無効化するかを理解します。 --- このページでは、ツール定義に対する「prompt caching」（プロンプトキャッシング）について説明します。`cache_control` ブレークポイントをどこに配置するか、`defer_loading` がどのようにキャッシュを保持するか、そして何がキャッシュを無効化するかを扱います。一般的なプロンプトキャッシングについては、[プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)を参照してください。 ## ツール定義における cache\_control `tools` 配列の最後のツールに `cache_control: {"type": "ephemeral"}` を配置します。これにより、最初のツールからマークされたブレークポイントまでの、ツール定義プレフィックス全体がキャッシュされます。 ```json { "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がそれを展開後の最後のツールに適用します。 [コンピュータ使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool)および[ブラウザ使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool)のツールセットエントリも同じルールに従います。`cache_control` はツールセットエントリ自体に配置し、ブレークポイントはツールセットの定義の後に配置されます。ツールセットのメンバーは1つの定義として読み込まれるため、メンバーの `configs` エントリ内では受け付けられません。[バッチアクション](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#batch-actions)内では、そのターンのメンバーの `tool_use` または `tool_result` ブロックのいずれかに付けられた `cache_control` マーカーは受け付けられ、そのバッチの終わりで有効になります。そのため、1つのバッチ内の複数のマーカーは単一のブレークポイントとして機能します。各マーカーは依然としてリクエストの[4つのブレークポイント](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching#when-to-use-multiple-breakpoints)という上限にカウントされるため、ターンごとに1つ使用してください。 ## defer\_loading とキャッシュの保持 遅延読み込みされるツールは、システムプロンプトのプレフィックスに含まれません。モデルが[ツール検索](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool)を通じて遅延ツールを発見すると、その定義は会話履歴内に `tool_reference` ブロックとしてインラインで追加されます。プレフィックスは変更されないため、プロンプトキャッシングは保持されます。 つまり、ツール検索を通じてツールを動的に追加しても、キャッシュは壊れません。常に読み込まれる少数のツールセット（キャッシュ済み）で会話を開始し、必要に応じてモデルに追加のツールを発見させ、すべてのターンで同じキャッシュヒットを維持できます。 `defer_loading` は、[strictモード](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/strict-tool-use)のための文法構築とも独立して動作します。文法はどのツールが遅延されているかに関係なく完全なツールセットから構築されるため、ツールが動的に読み込まれる場合でも、プロンプトキャッシングと文法キャッシングの両方が保持されます。 ## 何がキャッシュを無効化するか キャッシュはプレフィックスの階層（`tools` → `system` → `messages`）に従うため、あるレベルでの変更はそのレベルとそれ以降のすべてを無効化します。 | 変更 | 無効化されるもの | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ツール定義の変更 | キャッシュ全体（tools、system、messages） | | ウェブ検索または引用の切り替え | system および messages のキャッシュ | | `tool_choice` の変更 | messages のキャッシュ | | `disable_parallel_tool_use` の変更 | messages のキャッシュ | | 画像の有無の切り替え | messages のキャッシュ | | 思考パラメータの変更 | messages のキャッシュは常に無効化。思考設定をそれらより前にレンダリングするモデルでは、ツールおよび system のキャッシュも無効化（[詳細](https://platform.claude.com/docs/ja/build-with-claude/thinking#thinking-and-prompt-caching)） | | `output_config.effort` の変更 | 思考パラメータと同じ。モデルのデフォルトを明示的に設定することは、省略することと同等 | 会話の途中で `tool_choice` を変更する必要がある場合は、変更ポイントの前にキャッシュブレークポイントを配置することを検討してください。 ## サーバーツールの結果は自動的にキャッシュされる リクエストでプロンプトキャッシングが有効になっており、Claudeがウェブ検索、ウェブフェッチ、コード実行などの[サーバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools)を使用する場合、APIはエージェントループの次のイテレーションを実行する前に、サーバーツールの結果に自動的にキャッシュブレークポイントを配置します。これにより、同じリクエスト内の後続のイテレーションは、増大していくプレフィックスを再処理する代わりにキャッシュから読み取ることができます。 この自動ブレークポイントは、独自の `cache_control` マーカーに設定したTTLとは無関係に、常にデフォルトの5分間のTTLを使用します。レスポンスの `usage` では、これらの書き込みは `cache_creation.ephemeral_5m_input_tokens` の下に表示されるため、設定したすべての `cache_control` が1時間のTTLを使用している場合でも、5分間のキャッシュ書き込みが表示されることがあります。 この動作は、リクエストにすでに少なくとも1つの `cache_control` マーカーがある場合にのみ適用されます。プロンプトキャッシングのないリクエストには、自動ブレークポイントは付与されません。 ## ツールごとの相互作用表 | ツール | キャッシングに関する考慮事項 | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [ウェブ検索](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool) | 有効化または無効化すると、system および messages のキャッシュが無効化される | | [ウェブフェッチ](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-fetch-tool) | 有効化または無効化すると、system および messages のキャッシュが無効化される | | [コード実行](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/code-execution-tool) | コンテナの状態はプロンプトキャッシュとは独立している | | [ツール検索](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool) | 発見されたツールは `tool_reference` ブロックとして読み込まれ、プレフィックスキャッシュが保持される | | [コンピュータ使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool) | スクリーンショットの有無が messages のキャッシュに影響する。`cache_control` はツールセットエントリに配置する（[ツール定義における cache\_control](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions) を参照） | | [ブラウザ使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool) | スクリーンショットの有無が messages のキャッシュに影響する。`cache_control` はツールセットエントリに配置する（[ツール定義における cache\_control](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions) を参照） | | [テキストエディタ](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/text-editor-tool) | 標準のクライアントツール。特別なキャッシングの相互作用はない | | [Bash](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/bash-tool) | 標準のクライアントツール。特別なキャッシングの相互作用はない | | [メモリ](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/memory-tool) | 標準のクライアントツール。特別なキャッシングの相互作用はない | ## 次のステップ TTLや料金を含む、プロンプトキャッシングのモデル全体を学びます。 キャッシュを壊すことなく、オンデマンドでツールを読み込みます。 利用可能なすべてのツールとそのパラメータを参照します。