SpyBara
Go Premium

agent-sdk/tool-search.md 2026-10-02 22:59 UTC to 2026-10-03 11:02 UTC

This page contains 14 additions and 14 deletions.

2026
Sat 3 12:00

Skalakan ke banyak tools dengan pencarian tools

Skalakan agen Anda ke ribuan tools dengan menemukan dan memuat hanya yang diperlukan, sesuai permintaan.

Pencarian tools memungkinkan agen Anda bekerja dengan ratusan atau ribuan tools dengan secara dinamis menemukan dan memuat mereka sesuai permintaan. Alih-alih memuat semua definisi tools ke dalam jendela konteks di awal, agen mencari katalog tools Anda dan memuat hanya tools yang dibutuhkannya.

Pendekatan ini menyelesaikan dua tantangan saat perpustakaan tools berkembang:

  • Efisiensi konteks: Definisi tools dapat mengonsumsi porsi besar dari jendela konteks (50 tools dapat menggunakan 10-20K tokens), meninggalkan ruang lebih sedikit untuk pekerjaan sebenarnya.
  • Akurasi pemilihan tools: Akurasi pemilihan tools menurun dengan lebih dari 30-50 tools yang dimuat sekaligus.

Cara kerja pencarian tools

Pencarian tools aktif secara default, dengan pengecualian yang tercantum dalam Konfigurasi pencarian tools.

Ketika aktif, definisi tools ditahan dari jendela konteks. Agen menerima ringkasan tools yang tersedia dan mencari yang relevan ketika tugas memerlukan kemampuan yang belum dimuat. Hingga lima tools paling relevan dimuat ke dalam konteks secara default, di mana mereka tetap tersedia untuk giliran berikutnya sampai SDK mengompres pesan tempat agen menemukan mereka. Setelah pemadatan itu, agen mencari tools tersebut lagi ketika mereka membutuhkannya berikutnya.

Pencarian tools menambahkan satu putaran ekstra setiap kali Claude mencari tools, tetapi untuk set tools besar ini diimbangi oleh konteks yang lebih kecil pada setiap giliran. Dengan lebih sedikit dari ~10 tools yang definisinya pas di jendela konteks, memuat semuanya di awal biasanya lebih cepat.

Untuk detail tentang mekanisme API yang mendasarinya, lihat Pencarian tools dalam API.

Pencarian tool aktif secara default. Untuk model pada daftar model yang tidak didukung SDK, SDK memuat definisi tool di awal, dan tidak ada nilai ENABLE_TOOL_SEARCH yang dapat menimpa itu. Di Google Cloud's Agent Platform, SDK memutuskan berdasarkan generasi model:

  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, dan yang lebih baru: pencarian tool aktif secara default.
  • Model Agent Platform sebelumnya: SDK memuat definisi tool di awal, karena stack serving mereka menolak header beta yang diperlukan. ENABLE_TOOL_SEARCH tidak dapat menimpa ini.

Sebelum Claude Code v2.1.221, SDK menonaktifkan pencarian tool untuk semua model di Google Cloud's Agent Platform kecuali Anda menetapkan ENABLE_TOOL_SEARCH.

SDK juga menonaktifkan pencarian tool ketika ANTHROPIC_BASE_URL menunjuk ke host non-first-party, karena sebagian besar proxy tidak meneruskan blok tool_reference. Anda dapat menimpa default itu dengan environment variable ENABLE_TOOL_SEARCH:

Nilai Perilaku
(tidak diatur) Pencarian tool aktif. Definisi tool ditunda dan ditemukan sesuai permintaan. Kembali ke pemuatan di awal pada model Google Cloud's Agent Platform yang lebih awal dari generasi Claude 4.5, ANTHROPIC_BASE_URL non-first-party, atau deployment Microsoft Foundry yang dihosting di Azure.
true Pencarian tool selalu aktif, kecuali pada deployment Microsoft Foundry yang dihosting di Azure, di mana penolakan sisi server masih memaksa pemuatan di awal, dan pada model Google Cloud's Agent Platform yang lebih awal dari generasi Claude 4.5, di mana SDK terus memuat definisi tool di awal. SDK mengirimkan header beta melalui proxy, dan permintaan gagal pada proxy yang tidak mendukung blok tool_reference.
auto Menghitung token dalam definisi tool yang dapat ditunda pencarian tool dan membandingkan total terhadap context window model. Ketika total mencapai 10% dari window, pencarian tool diaktifkan. Di bawah itu, SDK memuat setiap definisi tool ke dalam konteks di awal.
auto:N Sama seperti auto dengan persentase kustom. auto:5 diaktifkan ketika definisi tersebut mencapai 5% dari context window. Nilai lebih rendah diaktifkan lebih awal.
false Pencarian tool dimatikan. Semua definisi tool dimuat ke dalam konteks pada setiap giliran.

Pengaturan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS membuat pencarian tool tetap mati. Anda tidak dapat menimpanya dengan menetapkan ENABLE_TOOL_SEARCH sendiri. Organisasi Anda dapat membuat pencarian tool tetap aktif melalui pengaturan terkelola, pada Claude Code v2.1.227 atau lebih baru. Nonaktifkan kemampuan pra-rilis mencakup di mana override berlaku dan apa yang dihapus variabel tersebut.

Pencarian tool berlaku untuk semua tool terdaftar, baik berasal dari server MCP jarak jauh atau server MCP SDK kustom. Ketika Anda menggunakan auto, SDK menghitung setiap definisi yang dapat ditunda pencarian tool terhadap satu ambang batas gabungan: setiap tool MCP yang tidak ditandai alwaysLoad, dari server apa pun, ditambah tool bawaan yang dimuat sesuai permintaan. SDK memuat tool bawaan inti seperti Bash, Read, dan Edit di awal dan tidak menghitungnya terhadap ambang batas. Sebuah mod di salah satu plugin Anda juga dapat menunda sebuah tool atau memuatnya di awal, yang mengubah hitungan tersebut.

Atur nilai dalam opsi env pada query(). Dalam TypeScript, env menggantikan lingkungan subprocess, jadi sebarkan ...process.env untuk menjaga variabel yang diwariskan. Dalam Python, env digabungkan di atas lingkungan yang diwariskan. Contoh ini terhubung ke server MCP jarak jauh yang mengekspos banyak tool, pra-menyetujui semuanya dengan wildcard, dan menggunakan auto:5 sehingga pencarian tool diaktifkan ketika definisi yang dapat ditundanya mencapai 5% dari context window:

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}`);
}

Untuk menjalankan contoh ini, ganti https://tools.example.com/mcp dengan URL server MCP Anda sendiri. Jika berhasil, teks hasil akan dicetak ke konsol.

Karena ini adalah panggilan query() single-shot, SDK akan melempar setelah menghasilkan hasil kesalahan, jadi contoh membungkus loop dalam blok try. Untuk melihat mengapa jalankan gagal, periksa subtype pesan hasil, seperti error_during_execution, di dalam loop. Untuk informasi lebih lanjut tentang pesan hasil, lihat Menangani hasil.

Optimalkan penemuan tools

Mekanisme pencarian mencocokkan kueri terhadap nama dan deskripsi tools. Nama seperti search_slack_messages muncul untuk berbagai permintaan daripada query_slack. Deskripsi dengan kata kunci spesifik ("Cari pesan Slack berdasarkan kata kunci, saluran, atau rentang tanggal") cocok dengan lebih banyak kueri daripada yang generik ("Kueri Slack").

Anda juga dapat menambahkan bagian prompt sistem yang mencantumkan kategori tools yang tersedia. Ini memberikan agen konteks tentang jenis tools apa yang tersedia untuk dicari. Teruskan teks melalui opsi systemPrompt di TypeScript atau system_prompt di Python, menggunakan preset claude_code dengan append, yang menambahkan teks Anda ke prompt preset daripada menggantinya:

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

Untuk rangkaian lengkap opsi prompt sistem, lihat Memodifikasi prompt sistem.

Batas

  • Tools maksimum: 10.000 tools dalam katalog Anda
  • Hasil pencarian: mengembalikan hingga lima tools paling relevan per pencarian secara default
  • Dukungan model: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5, dan model yang lebih baru; lihat kompatibilitas model dalam dokumentasi API untuk daftar terkini. Hal yang sama berlaku di Agent Platform Google Cloud.