Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Alat pencarian alat memungkinkan Claude untuk bekerja dengan ratusan atau ribuan alat dengan menemukan dan memuat mereka secara dinamis sesuai permintaan. Alih-alih memuat semua definisi alat ke jendela konteks di awal, Claude mencari katalog alat Anda—termasuk nama alat, deskripsi, nama argumen, dan deskripsi argumen—dan memuat hanya alat yang dibutuhkannya.
Pendekatan ini mengatasi dua tantangan kritis saat perpustakaan alat berkembang:
Meskipun ini disediakan sebagai alat sisi server, Anda juga dapat menerapkan fungsionalitas pencarian alat sisi klien Anda sendiri. Lihat Implementasi pencarian alat khusus untuk detail.
Alat pencarian alat saat ini dalam beta publik. Sertakan header beta yang sesuai untuk penyedia Anda:
| Penyedia | Header beta | Model yang didukung |
|---|---|---|
| Claude API Microsoft Foundry | advanced-tool-use-2025-11-20 | Claude Opus 4.5 Claude Sonnet 4.5 |
| Google Cloud's Vertex AI |
tool-search-tool-2025-10-19 |
| Claude Opus 4.5 Claude Sonnet 4.5 |
| Amazon Bedrock | tool-search-tool-2025-10-19 | Claude Opus 4.5 |
Di Amazon Bedrock, pencarian alat sisi server hanya tersedia melalui API invoke, bukan API converse.
Anda juga dapat menerapkan pencarian alat sisi klien dengan mengembalikan blok tool_reference dari implementasi pencarian Anda sendiri.
Ada dua varian pencarian alat:
tool_search_tool_regex_20251119): Claude membuat pola regex untuk mencari alattool_search_tool_bm25_20251119): Claude menggunakan kueri bahasa alami untuk mencari alatKetika Anda mengaktifkan alat pencarian alat:
tool_search_tool_regex_20251119 atau tool_search_tool_bm25_20251119) dalam daftar alat Andadefer_loading: true untuk alat yang tidak boleh dimuat segeratool_reference paling relevanIni menjaga jendela konteks Anda tetap efisien sambil mempertahankan akurasi pemilihan alat yang tinggi.
Berikut adalah contoh sederhana dengan alat yang ditangguhkan:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 2048,
"messages": [
{
"role": "user",
"content": "What is the weather in San Francisco?"
}
],
"tools": [
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get the weather at a specific location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
},
"defer_loading": true
},
{
"name": "search_files",
"description": "Search through files in the workspace",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"file_types": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["query"]
},
"defer_loading": true
}
]
}'Alat pencarian alat memiliki dua varian:
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}{
"type": "tool_search_tool_bm25_20251119",
"name": "tool_search_tool_bm25"
}Format kueri varian Regex: Regex Python, BUKAN bahasa alami
Saat menggunakan tool_search_tool_regex_20251119, Claude membuat pola regex menggunakan sintaks re.search() Python, bukan kueri bahasa alami. Pola umum:
"weather" - cocok dengan nama alat/deskripsi yang berisi "weather""get_.*_data" - cocok dengan alat seperti get_user_data, get_weather_data"database.*query|query.*database" - pola OR untuk fleksibilitas"(?i)slack" - pencarian tidak peka huruf besar-kecilPanjang kueri maksimal: 200 karakter
Format kueri varian BM25: Bahasa alami
Saat menggunakan tool_search_tool_bm25_20251119, Claude menggunakan kueri bahasa alami untuk mencari alat.
Tandai alat untuk pemuatan sesuai permintaan dengan menambahkan defer_loading: true:
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["location"]
},
"defer_loading": true
}Poin kunci:
defer_loading dimuat ke konteks segeradefer_loading: true hanya dimuat ketika Claude menemukannya melalui pencariandefer_loading: trueKedua varian pencarian alat (regex dan bm25) mencari nama alat, deskripsi, nama argumen, dan deskripsi argumen.
Ketika Claude menggunakan alat pencarian alat, respons mencakup tipe blok baru:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll search for tools to help with the weather information."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01ABC123",
"name": "tool_search_tool_regex",
"input": {
"query": "weather"
}
},
{
"type": "tool_search_tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_search_result",
"tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
}
},
{
"type": "text",
"text": "I found a weather tool. Let me get the weather for San Francisco."
},
{
"type": "tool_use",
"id": "toolu_01XYZ789",
"name": "get_weather",
"input": { "location": "San Francisco", "unit": "fahrenheit" }
}
],
"stop_reason": "tool_use"
}server_tool_use: Menunjukkan Claude menjalankan alat pencarian alattool_search_tool_result: Berisi hasil pencarian dengan objek tool_search_tool_search_result bersarangtool_references: Array objek tool_reference yang menunjuk ke alat yang ditemukantool_use: Claude menjalankan alat yang ditemukanBlok tool_reference secara otomatis diperluas menjadi definisi alat lengkap sebelum ditampilkan kepada Claude. Anda tidak perlu menangani ekspansi ini sendiri. Ini terjadi secara otomatis di API selama Anda menyediakan semua definisi alat yang cocok dalam parameter tools.
Alat pencarian alat bekerja dengan server MCP. Tambahkan header beta "mcp-client-2025-11-20" ke permintaan API Anda, kemudian gunakan mcp_toolset dengan default_config untuk menunda pemuatan alat MCP:
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 2048,
"mcp_servers": [
{
"type": "url",
"name": "database-server",
"url": "https://mcp-db.example.com"
}
],
"tools": [
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"type": "mcp_toolset",
"mcp_server_name": "database-server",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"defer_loading": false
}
}
}
],
"messages": [
{
"role": "user",
"content": "What events are in my database?"
}
]
}'Opsi konfigurasi MCP:
default_config.defer_loading: Tetapkan default untuk semua alat dari server MCPconfigs: Ganti default untuk alat tertentu berdasarkan namaAnda dapat menerapkan logika pencarian alat Anda sendiri (misalnya, menggunakan embedding atau pencarian semantik) dengan mengembalikan blok tool_reference dari alat khusus:
{
"type": "tool_search_tool_result",
"tool_use_id": "toolu_custom_search",
"content": {
"type": "tool_search_tool_search_result",
"tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
}Setiap alat yang direferensikan harus memiliki definisi alat yang sesuai dalam parameter tools tingkat atas dengan defer_loading: true. Pendekatan ini memungkinkan Anda menggunakan algoritma pencarian yang lebih canggih sambil mempertahankan kompatibilitas dengan sistem pencarian alat.
Untuk contoh lengkap menggunakan embedding, lihat buku resep pencarian alat dengan embedding kami.
Alat pencarian alat tidak kompatibel dengan contoh penggunaan alat. Jika Anda perlu memberikan contoh penggunaan alat, gunakan pemanggilan alat standar tanpa pencarian alat.
Kesalahan ini mencegah permintaan diproses:
Semua alat ditangguhkan:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "All tools have defer_loading set. At least one tool must be non-deferred."
}
}Definisi alat yang hilang:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Tool reference 'unknown_tool' has no corresponding tool definition"
}
}Kesalahan selama eksekusi alat mengembalikan respons 200 dengan informasi kesalahan di badan:
{
"type": "tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_result_error",
"error_code": "invalid_pattern"
}
}Kode kesalahan:
too_many_requests: Batas laju terlampaui untuk operasi pencarian alatinvalid_pattern: Pola regex yang salah formatpattern_too_long: Pola melebihi batas 200 karakterunavailable: Layanan pencarian alat sementara tidak tersediaPencarian alat bekerja dengan caching prompt. Tambahkan titik henti cache_control untuk mengoptimalkan percakapan multi-putaran:
import anthropic
client = anthropic.Anthropic()
# Permintaan pertama dengan pencarian alat
messages = [
{
"role": "user",
"content": "What's the weather in Seattle?"
}
]
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
max_tokens=2048,
messages=messages,
tools=[
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"defer_loading": True
}
]
)
# Tambahkan respons Claude ke percakapan
messages.append({
"role": "assistant",
"content": response1.content
})
# Permintaan kedua dengan titik henti cache
messages.append({
"role": "user",
"content": "What about New York?",
"cache_control": {"type": "ephemeral"}
})
response2 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
max_tokens=2048,
messages=messages,
tools=[
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"defer_loading": True
}
]
)
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")Sistem secara otomatis memperluas blok tool_reference di seluruh riwayat percakapan lengkap, sehingga Claude dapat menggunakan kembali alat yang ditemukan dalam putaran berikutnya tanpa pencarian ulang.
Dengan streaming diaktifkan, Anda akan menerima peristiwa pencarian alat sebagai bagian dari aliran:
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}
// Kueri pencarian dialirkan
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}
// Jeda saat pencarian dieksekusi
// Hasil pencarian dialirkan
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}
// Claude melanjutkan dengan alat yang ditemukanAnda dapat menyertakan alat pencarian alat dalam Messages Batches API. Operasi pencarian alat melalui Messages Batches API dihargai sama dengan yang ada di permintaan Messages API reguler.
Kasus penggunaan yang baik:
Kapan pemanggilan alat tradisional mungkin lebih baik:
Penggunaan alat pencarian alat dilacak dalam objek penggunaan respons:
{
"usage": {
"input_tokens": 1024,
"output_tokens": 256,
"server_tool_use": {
"tool_search_requests": 2
}
}
}