SpyBara
Go Premium

agent-sdk/tool-search.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 30 additions and 25 deletions.

2026
Wed 9 22:58

多くのツールにスケーリングするツール検索

必要なものだけをオンデマンドで検出して読み込むことで、エージェントを数千のツールにスケーリングします。

ツール検索により、エージェントは数百または数千のツールを動的に検出し、オンデマンドで読み込むことで、それらと連携できます。すべてのツール定義をコンテキストウィンドウに事前に読み込む代わりに、エージェントはツールカタログを検索し、必要なツールのみを読み込みます。

このアプローチは、ツールライブラリがスケーリングするにつれて、2 つの課題を解決します。

  • コンテキスト効率： ツール定義はコンテキストウィンドウの大部分を消費する可能性があります（50 個のツールは 10～20K トークンを使用できます）。実際の作業用のスペースが減少します。
  • ツール選択精度： 30～50 個以上のツールが一度に読み込まれると、ツール選択精度が低下します。

ツール検索の仕組み

ツール検索はデフォルトでオンになっており、ツール検索の設定に記載されている例外があります。

ツール検索がアクティブな場合、ツール定義はコンテキストウィンドウから保留されます。エージェントは利用可能なツールの概要を受け取り、タスクが既に読み込まれていない機能を必要とする場合、関連するツールを検索します。最も関連性の高い 5 個までのツールがデフォルトでコンテキストに読み込まれ、その後のターンで利用可能なままになります。SDK がエージェントがツールを検出したメッセージをコンパクト化した後、エージェントは次にそれらのツールが必要になったときに再度検索します。

ツール検索は Claude がツールを検索するたびに 1 つの追加ラウンドトリップを追加しますが、大規模なツールセットの場合、これはすべてのターンでより小さいコンテキストによってオフセットされます。定義がコンテキストウィンドウに快適に収まる約 10 個未満のツールの場合、すべてを事前に読み込む方が通常は高速です。

基盤となる API メカニズムの詳細については、API のツール検索を参照してください。

ツール検索はデフォルトでオンです。SDK のサポートされていないモデルリストに含まれるモデルの場合、SDK はツール定義を事前に読み込み、ENABLE_TOOL_SEARCH 値はそれをオーバーライドしません。Google Cloud の Agent Platform では、SDK はモデル世代によって決定します。

  • Claude Opus 4.5、Sonnet 4.5、Haiku 4.5、およびそれ以降: ツール検索はデフォルトでオンです。
  • 以前の Agent Platform モデル: SDK はツール定義を事前に読み込みます。これは、それらのサービングスタックが必要なベータヘッダーを拒否するためです。ENABLE_TOOL_SEARCH はこれをオーバーライドできません。

Claude Code v2.1.221 より前は、ENABLE_TOOL_SEARCH を設定しない限り、SDK は Google Cloud の Agent Platform 上のすべてのモデルに対してツール検索を無効にしていました。

SDK は、ANTHROPIC_BASE_URL が非ファーストパーティホストを指す場合もツール検索を無効にします。ほとんどのプロキシは tool_reference ブロックを転送しないためです。ENABLE_TOOL_SEARCH 環境変数でそのデフォルトをオーバーライドできます。

値 動作
（未設定） ツール検索はオンです。ツール定義は遅延され、オンデマンドで検出されます。Google Cloud の Agent Platform の Claude 4.5 世代より前のモデル、非ファーストパーティ ANTHROPIC_BASE_URL、または Microsoft Foundry デプロイメント（Azure でホストされている場合）では、事前読み込みにフォールバックします。
true ツール検索は常にオンです。ただし、Microsoft Foundry デプロイメント（Azure でホストされている場合）ではサーバー側の拒否により事前読み込みが強制され、Google Cloud の Agent Platform の Claude 4.5 世代より前のモデルでは SDK がツール定義を事前に読み込み続けます。SDK はプロキシ経由でベータヘッダーを送信し、tool_reference ブロックをサポートしないプロキシではリクエストが失敗します。
auto ツール検索が遅延できるツール定義のトークン数をカウントし、合計をモデルのコンテキストウィンドウと比較します。合計がウィンドウの 10% に達すると、ツール検索がアクティブになります。それ以下の場合、SDK はすべてのツール定義をコンテキストに事前読み込みします。
auto:N カスタム割合を使用した auto と同じです。auto:5 はそれらの定義がコンテキストウィンドウの 5% に達するとアクティブになります。値が低いほど、より早くアクティブになります。
false ツール検索はオフです。すべてのツール定義がすべてのターンでコンテキストに読み込まれます。

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定するとツール検索がオフになります。ENABLE_TOOL_SEARCH を自分で設定してそれをオーバーライドすることはできません。組織は 管理設定を通じてツール検索をオンに保つことができます。Claude Code v2.1.227 以降で可能です。プレリリース機能を無効にするは、オーバーライドが適用される場所と変数が削除する内容をカバーしています。

ツール検索は、リモート MCP サーバーから来るか、カスタム SDK MCP サーバーから来るかに関わらず、すべての登録ツールに適用されます。auto を使用する場合、SDK はツール検索が遅延できるすべての定義をカウントして、1 つの結合された閾値に向かってカウントします。alwaysLoadとマークされていない各 MCP ツール（任意のサーバーから）、およびオンデマンドで読み込まれる組み込みツール。SDK は常に Bash、Read、Edit などのコア組み込みツールを事前に読み込み、閾値に向かってカウントしません。

query() の env オプションで値を設定します。TypeScript では、env はサブプロセス環境を置き換えるため、継承された変数を保持するために ...process.env を展開します。Python では、env は継承された環境の上にマージされます。この例は、多くのツールを公開するリモート MCP サーバーに接続し、ワイルドカードですべてのツールを事前承認し、auto:5 を使用して、ツール検索が遅延できる定義がコンテキストウィンドウの 5% に達するとツール検索をアクティブにします。

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({
prompt: "Find and run the appropriate database query",
options: {
mcpServers: {
"enterprise-tools": {
// Connect to a remote MCP server
type: "http",
url: "https://tools.example.com/mcp"
}
},
allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
env: {
...process.env, // env replaces the subprocess environment, so keep inherited variables
ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result
console.log(`Session ended with an error: ${error}`);
}

この例を実行するには、https://tools.example.com/mcp を独自の MCP サーバーの URL に置き換えてください。成功時に、結果テキストがコンソールに出力されます。

これは単一ショットの query() 呼び出しであるため、SDK はエラー結果を生成した後に発生するため、この例はループを try ブロックでラップします。実行が失敗した理由を確認するには、ループ内の結果メッセージの subtype（error_during_execution など）を確認してください。結果メッセージの詳細については、結果を処理するを参照してください。

ツール検出を最適化する

検索メカニズムは、ツール名と説明に対してクエリを照合します。search_slack_messages のような名前は、query_slack よりも広い範囲のリクエストに対して表示されます。「キーワード、チャネル、または日付範囲で Slack メッセージを検索」などの具体的なキーワードを含む説明は、「Slack をクエリ」などの一般的な説明よりも多くのクエリに一致します。

利用可能なツールカテゴリをリストするシステムプロンプトセクションを追加することもできます。これにより、エージェントは検索対象のツールの種類に関するコンテキストを取得します。TypeScript では systemPrompt オプション、Python では system_prompt を使用してテキストを渡します。claude_code プリセットで append を使用すると、プリセットのプロンプトを置き換えるのではなく、テキストを追加します。

options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You can search for tools to interact with Slack, GitHub, and Jira."
}
}

システムプロンプトオプションの完全なセットについては、システムプロンプトの変更を参照してください。

制限

  • 最大ツール数： カタログ内の 10,000 個のツール
  • 検索結果： デフォルトでは検索ごとに最も関連性の高い 5 つのツールを返します
  • モデルサポート： Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5、およびそれ以降のモデル。現在のリストについては、API ドキュメントのモデル互換性を参照してください。Google Cloud の Agent Platform でも同じ最小要件が適用されます。