Langsung ke konten utama
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.
Pencarian tools diaktifkan secara default. Halaman ini mencakup cara kerjanya, cara mengonfigurasinya, dan cara mengoptimalkan penemuan tools.

​
Cara kerja pencarian tools

Ketika pencarian tools aktif, definisi tools ditahan dari jendela konteks. Agen menerima ringkasan tools yang tersedia dan mencari yang relevan ketika tugas memerlukan kemampuan yang belum dimuat. 3-5 tools paling relevan dimuat ke dalam konteks, di mana mereka tetap tersedia untuk giliran berikutnya. Jika percakapan cukup panjang sehingga SDK mengompres pesan sebelumnya untuk membebaskan ruang, tools yang sebelumnya ditemukan mungkin dihapus, dan agen mencari lagi sesuai kebutuhan. Pencarian tools menambahkan satu putaran ekstra pertama kali Claude menemukan tool (langkah pencarian), tetapi untuk set tools besar ini diimbangi oleh konteks yang lebih kecil pada setiap giliran. Dengan lebih sedikit dari ~10 tools, memuat semuanya di awal biasanya lebih cepat. Untuk detail tentang mekanisme API yang mendasarinya, lihat Pencarian tools dalam API.
Pencarian tools memerlukan Claude Sonnet 4 atau lebih baru, atau Claude Opus 4 atau lebih baru. Model Haiku tidak mendukung pencarian tools.

​
Konfigurasi pencarian tools

Pencarian tools aktif secara default. Ini dinonaktifkan secara default di Vertex AI, di mana didukung untuk Claude Sonnet 4.5 dan lebih baru serta Claude Opus 4.5 dan lebih baru. Ini juga dinonaktifkan ketika ANTHROPIC_BASE_URL menunjuk ke host non-first-party, karena sebagian besar proxy tidak meneruskan blok tool_reference. Anda dapat mengganti salah satu default dengan variabel lingkungan ENABLE_TOOL_SEARCH:
NilaiPerilaku
(tidak diatur)Pencarian tools aktif. Definisi tools ditunda dan ditemukan sesuai permintaan. Kembali ke pemuatan di awal di Vertex AI atau ANTHROPIC_BASE_URL non-first-party.
truePencarian tools selalu aktif. SDK mengirimkan header beta bahkan di Vertex AI dan melalui proxy. Permintaan gagal pada model Vertex AI lebih awal dari Sonnet 4.5 atau Opus 4.5, atau pada proxy yang tidak mendukung blok tool_reference.
autoMemeriksa jumlah token gabungan dari semua definisi tools terhadap jendela konteks model. Jika melebihi 10%, pencarian tools diaktifkan. Jika di bawah 10%, semua tools dimuat ke dalam konteks secara normal.
auto:NSama seperti auto dengan persentase kustom. auto:5 diaktifkan ketika definisi tools melebihi 5% dari jendela konteks. Nilai lebih rendah diaktifkan lebih awal.
falsePencarian tools dimatikan. Semua definisi tools dimuat ke dalam konteks pada setiap giliran.
Pencarian tools berlaku untuk semua tools terdaftar, baik berasal dari server MCP jarak jauh atau server MCP SDK kustom. Saat menggunakan auto, ambang batas didasarkan pada ukuran gabungan semua definisi tools di semua server. Atur nilai dalam opsi env pada query(). Contoh ini terhubung ke server MCP jarak jauh yang mengekspos banyak tools, pra-menyetujui semuanya dengan wildcard, dan menggunakan auto:5 sehingga pencarian tools diaktifkan ketika definisi mereka melebihi 5% dari jendela konteks: 
import { query } from "@anthropic-ai/claude-agent-sdk";

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: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
Mengatur ENABLE_TOOL_SEARCH ke "false" menonaktifkan pencarian tools dan memuat semua definisi tools ke dalam konteks pada setiap giliran. Ini menghilangkan putaran pencarian, yang dapat lebih cepat ketika set tools kecil (lebih sedikit dari ~10 tools) dan definisi cocok dengan nyaman di jendela konteks.

​
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: 
You can search for tools to interact with Slack, GitHub, and Jira.

​
Batas

  • Tools maksimum: 10.000 tools dalam katalog Anda
  • Hasil pencarian: Mengembalikan 3-5 tools paling relevan per pencarian
  • Dukungan model: Claude Sonnet 4 dan lebih baru, Claude Opus 4 dan lebih baru (tidak ada Haiku)

​
Dokumentasi terkait