Alat pencarian alat

Tool search tool memungkinkan Haijun bekerja dengan ratusan atau ribuan alat dengan menemukan dan memuatnya sesuai permintaan. Alih-alih memuat semua definisi alat ke dalam jendela konteks di awal, Haijun mencari katalog alat Anda (termasuk nama alat, deskripsi, nama argumen, dan deskripsi argumen) dan memuat hanya alat yang dibutuhkannya.

Memuat setiap definisi alat di awal menyebabkan dua masalah seiring bertumbuhnya pustaka alat:

Pembengkakan konteks: Pengaturan multiserver yang umum (GitHub, Slack, Sentry, Grafana, dan Splunk) dapat mengonsumsi \~55k token dalam definisi sebelum Haijun melakukan pekerjaan apa pun. Tool search biasanya mengurangi ini lebih dari 85 persen, memuat hanya 3–5 alat yang dibutuhkan Haijun untuk permintaan tertentu.

Akurasi pemilihan alat: Kemampuan Haijun untuk memilih alat yang tepat menurun setelah Anda melampaui 30–50 alat yang tersedia. Karena tool search memuat hanya sekumpulan alat relevan yang terfokus sesuai permintaan, akurasi pemilihan tetap tinggi bahkan di seluruh ribuan alat.

Untuk model yang mendukung tool search, lihat Kompatibilitas model.

Tip: Untuk latar belakang tentang tantangan penskalaan yang dipecahkan oleh tool search, lihat Advanced tool use. Pemuatan sesuai permintaan dari tool search juga merupakan contoh dari prinsip pengambilan just-in-time yang lebih luas yang dijelaskan dalam Effective context engineering.

Tool search berjalan sebagai alat sisi server, tetapi Anda juga dapat mengimplementasikan tool search sisi klien Anda sendiri. Lihat Implementasi tool search kustom untuk detailnya.

Note: Bagikan umpan balik tentang fitur ini melalui formulir umpan balik.

Note: Untuk mempelajari bagaimana "zero data retention" (retensi data nol), atau ZDR, berlaku untuk fitur ini, lihat API dan retensi data.

Warning: Di Amazon Bedrock, tool search sisi server hanya tersedia melalui InvokeModel API, bukan Converse API.

Note: Di Haijun Platform on AWS, tool search sisi server bekerja secara identik dengan Haijun API. Haijun Platform on AWS menggunakan Juglow Messages API secara langsung, sehingga tidak ada perbedaan InvokeModel atau Converse.

Kompatibilitas model

Kedua varian tool search tersedia pada model berikut:

Model	Versi alat
Haijun Fable 5.1 (haijun-fable-5-1)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Mythos 5.1 (haijun-mythos-5-1)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Fable 5 (haijun-fable-5)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Mythos 5 (haijun-mythos-5)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Opus 5.5 (haijun-opus-5-5)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Opus 5 (haijun-opus-5)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Opus 4.8 (haijun-opus-4-8)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Opus 4.7 (haijun-opus-4-7)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Opus 4.6 (haijun-opus-4-6)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Sonnet 4.6 (haijun-sonnet-4-6)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Opus 4.5 (haijun-opus-4-5-20251101)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Sonnet 4.5 (haijun-sonnet-4-5-20250929)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`
Haijun Haiku 4.5 (haijun-haiku-4-5-20251001)	`tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119`

Haijun Opus 4.1 dan model sebelumnya tidak mendukung tool search tool.

Cara kerja pencarian alat

Ada dua varian tool search:

Regex (tool_search_tool_regex_20251119): Haijun membangun pola regex untuk mencari alat.

BM25 (tool_search_tool_bm25_20251119): Haijun menggunakan kueri bahasa alami untuk mencari alat.

Ketika Anda mengaktifkan tool search tool:

Anda menyertakan tool search tool (misalnya, tool_search_tool_regex_20251119 atau tool_search_tool_bm25_20251119) dalam daftar tools Anda.

Anda menyediakan setiap definisi alat dalam array tools dan mengatur defer_loading: true pada alat yang tidak boleh dimuat di awal. Setidaknya satu alat, biasanya tool search tool itu sendiri, harus tetap non-deferred.

Awalnya, konteks Haijun hanya berisi tool search tool dan alat non-deferred apa pun.

Ketika Haijun membutuhkan alat tambahan, ia mencari menggunakan tool search tool.

API menjalankan pencarian dan mengembalikan alat yang cocok sebagai blok tool_reference (hingga 5 secara default; Haijun dapat mengatur limit dalam input pencariannya).

API secara otomatis memperluas referensi ini menjadi definisi alat lengkap.

Haijun memilih dari alat yang ditemukan dan memanggilnya.

Mulai cepat

Contoh berikut menyertakan tool search tool dan dua alat deferred:

bash

  curl https://haijun.my.id/v1/messages \
      -H "x-api-key: $JUGLOW_API_KEY" \
      -H "juglow-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
          "model": "haijun-opus-5-5",
          "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
              }
          ]
      }'

bash

  ant messages create <<'YAML'
  model: haijun-opus-5-5
  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
  YAML

python

  client = juglow.Juglow()

  response = client.messages.create(
      model="haijun-opus-5-5",
      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,
          },
      ],
  )

  print(response)

typescript

  const client = new Juglow();

  const response = await client.messages.create({
    model: "haijun-opus-5-5",
    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" as const,
          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" as const,
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  });

  console.log(response);

csharp

  JuglowClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.HaijunOpus5_5,
      MaxTokens = 2048,
      Messages = [
          new() {
              Role = Role.User,
              Content = "What is the weather in San Francisco?"
          }
      ],
      Tools = [
          new ToolUnion(new ToolSearchToolRegex20251119
          {
              Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119
          }),
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the weather at a specific location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }),
                  },
                  Required = ["location"],
              },
              DeferLoading = true,
          }),
          new ToolUnion(new Tool()
          {
              Name = "search_files",
              Description = "Search through files in the workspace",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["query"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["file_types"] = JsonSerializer.SerializeToElement(new { type = "array", items = new { type = "string" } }),
                  },
                  Required = ["query"],
              },
              DeferLoading = true,
          }),
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);

  client := juglow.NewClient()

  response, err := client.Messages.New(context.TODO(), juglow.MessageNewParams{
  	Model:     juglow.ModelHaijunOpus5_5,
  	MaxTokens: 2048,
  	Messages: []juglow.MessageParam{
  		juglow.NewUserMessage(juglow.NewTextBlock("What is the weather in San Francisco?")),
  	},
  	Tools: []juglow.ToolUnionParam{
  		{OfToolSearchToolRegex20251119: &juglow.ToolSearchToolRegex20251119Param{
  			Type: juglow.ToolSearchToolRegex20251119TypeToolSearchToolRegex20251119,
  		}},
  		{OfTool: &juglow.ToolParam{
  			Name:        "get_weather",
  			Description: juglow.String("Get the weather at a specific location"),
  			InputSchema: juglow.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{"type": "string"},
  					"unit": map[string]any{
  						"type": "string",
  						"enum": []string{"celsius", "fahrenheit"},
  					},
  				},
  				Required: []string{"location"},
  			},
  			DeferLoading: juglow.Bool(true),
  		}},
  		{OfTool: &juglow.ToolParam{
  			Name:        "search_files",
  			Description: juglow.String("Search through files in the workspace"),
  			InputSchema: juglow.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"query":      map[string]any{"type": "string"},
  					"file_types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
  				},
  				Required: []string{"query"},
  			},
  			DeferLoading: juglow.Bool(true),
  		}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())

java

  import com.juglow.models.messages.ToolSearchToolRegex20251119;

  void main() {
      JuglowClient client = JuglowOkHttpClient.fromEnv();

      InputSchema weatherSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "location", Map.of("type", "string"),
              "unit", Map.of(
                  "type", "string",
                  "enum", List.of("celsius", "fahrenheit")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("location")))
          .build();

      InputSchema searchSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "query", Map.of("type", "string"),
              "file_types", Map.of(
                  "type", "array",
                  "items", Map.of("type", "string")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("query")))
          .build();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.HAIJUN_OPUS_5_5)
          .maxTokens(2048L)
          .addUserMessage("What is the weather in San Francisco?")
          .addTool(ToolSearchToolRegex20251119.builder()
              .type(ToolSearchToolRegex20251119.Type.TOOL_SEARCH_TOOL_REGEX_20251119)
              .build())
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the weather at a specific location")
              .inputSchema(weatherSchema)
              .deferLoading(true)
              .build())
          .addTool(Tool.builder()
              .name("search_files")
              .description("Search through files in the workspace")
              .inputSchema(searchSchema)
              .deferLoading(true)
              .build())
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }

php

  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 2048,
      messages: [
          ['role' => 'user', 'content' => 'What is the weather in San Francisco?'],
      ],
      model: 'haijun-opus-5-5',
      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,
          ],
      ],
  );

  echo $message;

ruby

  client = Juglow::Client.new

  message = client.messages.create(
    model: "haijun-opus-5-5",
    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
      }
    ]
  )

  puts message

Haijun mencari katalog, menemukan get_weather, dan memanggilnya. Respons berakhir dengan stop_reason: "tool_use". Jalankan alat yang ditemukan dan kembalikan tool_result seperti dalam Menangani panggilan alat. Format respons menunjukkan blok yang Anda dapatkan kembali dan apa yang harus dikirim selanjutnya.

Definisi alat

Tool search tool memiliki dua varian:

json

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

json

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

Warning: Format kueri varian regex: regex Python, bukan bahasa alami Dengan tool_search_tool_regex_20251119, Haijun menulis pola re.search() Python, bukan kueri bahasa alami. Pencocokan tidak peka huruf besar-kecil. Pola umum meliputi berikut ini: * "weather": cocok dengan nama alat dan deskripsi yang mengandung "weather" * "get_._data": cocok dengan alat seperti get_user_data dan get_weather_data "database.query|query.database": cocok dengan urutan kata mana pun Panjang pola maksimum: 200 karakter

Note: Format kueri varian BM25: bahasa alami Dengan tool_search_tool_bm25_20251119, Haijun mencari dengan kueri bahasa alami. Panjang kueri maksimum: 500 karakter.

Pemuatan alat deferred

Tandai alat untuk pemuatan sesuai permintaan dengan menambahkan defer_loading: true:

json

{
  "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
}

defer_loading mengontrol apa yang masuk ke jendela konteks, bukan apa yang Anda kirim dalam permintaan:

Anda tetap mengirim definisi lengkap setiap alat dalam array tools pada setiap permintaan, termasuk yang deferred. API membutuhkannya di sisi server untuk menjalankan pencarian dan memperluas blok tool_reference.

Alat tanpa defer_loading dimuat ke dalam konteks segera.

Alat dengan defer_loading: true dimuat hanya ketika Haijun menemukannya melalui pencarian.

Jangan pernah mengatur defer_loading: true pada tool search tool itu sendiri.

Jaga agar 3–5 alat yang paling sering digunakan tetap non-deferred sehingga Haijun dapat memanggilnya tanpa mencari terlebih dahulu.

Toolset computer use dan browser use (computer_toolset_20260801 dan browser_toolset_20260801) mengambil defer_loading per alat anggota di dalam objek configs entri, bukan pada entri itu sendiri; permintaan yang mengaturnya di tingkat entri akan ditolak. Karena toolset menunda dan memperluas sebagai satu unit, defer_loading harus menghasilkan nilai yang sama pada setiap anggota yang diaktifkan, dan ketika Haijun menemukan toolset melalui pencarian, setiap anggota yang diaktifkan dimuat sekaligus. Lihat Client toolsets untuk format configs.

Kedua varian tool search (regex dan bm25) mencari nama alat, deskripsi, nama argumen, dan deskripsi argumen.

Secara internal, API mengecualikan alat deferred dari prefiks prompt sistem. Ketika Haijun menemukan alat deferred melalui tool search, API menambahkan blok tool_reference secara inline dalam percakapan, lalu memperluasnya menjadi definisi alat lengkap sebelum meneruskannya ke Haijun. Prefiks tidak tersentuh, sehingga caching prompt dipertahankan. Tata bahasa untuk mode ketat (aturan yang membatasi output panggilan alat agar cocok dengan skema Anda) dibangun dari toolset lengkap, sehingga defer_loading dan mode ketat disusun tanpa kompilasi ulang tata bahasa.

Format respons

Ketika Haijun menggunakan tool search tool, respons menyertakan jenis blok berikut:

json

{
  "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": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "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"
}

Memahami respons

server_tool_use: Panggilan Haijun ke tool search tool. Pencarian berjalan di server Juglow. Jangan pernah mengembalikan tool_result untuk ID srvtoolu_...-nya. input menyimpan pencarian (pattern untuk varian regex, query untuk BM25) dan dapat menyertakan limit opsional, sebuah integer dari 1 hingga 10.000 yang membatasi berapa banyak alat yang cocok yang dikembalikan pencarian (default: 5).

tool_search_tool_result: hasil pencarian, dalam objek tool_search_tool_search_result bersarang. Simpan apa adanya dalam riwayat pesan.

tool_references: sebuah array objek tool_reference yang menunjuk ke alat yang ditemukan. API memperluasnya untuk Haijun. Anda tidak pernah memperluasnya sendiri.

tool_use: Panggilan Haijun ke alat yang ditemukan. Jalankan dan kembalikan tool_result persis seperti dalam penggunaan alat standar.

API secara otomatis memperluas blok tool_reference menjadi definisi alat lengkap sebelum menampilkannya ke Haijun. Anda tidak perlu menangani perluasan ini sendiri, selama Anda menyediakan semua definisi alat yang cocok dalam parameter tools.

Melanjutkan percakapan

Pada permintaan berikutnya, teruskan konten asisten kembali tanpa perubahan, termasuk blok server_tool_use dan tool_search_tool_result. Tambahkan tool_result Anda untuk alat yang ditemukan dalam pesan pengguna, dan kirim array tools yang sama: alat pencarian ditambah setiap definisi deferred. Jangan mengembalikan tool_result untuk ID srvtoolu_...: API menolak permintaan tersebut. API memperluas blok tool_reference di seluruh riwayat percakapan, sehingga Haijun dapat menggunakan kembali alat yang ditemukan di giliran berikutnya tanpa mencari ulang. Pencarian yang tidak cocok dengan apa pun mengembalikan tool_search_tool_search_result dengan array tool_references kosong, bukan kesalahan.

Integrasi MCP

Jika alat Anda berasal dari server MCP melalui MCP connector, Anda tidak mengatur defer_loading pada definisi alat individual. Sebaliknya, atur sekali pada default_config entri mcp_toolset untuk seluruh server, atau per alat dalam configs-nya. Lihat Konfigurasi MCP toolset.

Implementasi pencarian alat kustom

Anda dapat mengimplementasikan logika tool search Anda sendiri (misalnya, menggunakan embedding atau pencarian semantik) dengan mengembalikan blok tool_reference dari alat kustom. Ketika Haijun memanggil alat pencarian kustom Anda, kembalikan tool_result standar dengan blok tool_reference dalam array konten:

json

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Setiap alat yang direferensikan harus memiliki definisi alat yang sesuai dalam parameter tools tingkat atas, biasanya dengan defer_loading: true. Ini memungkinkan Anda menggunakan metode pencarian yang tidak disediakan oleh varian bawaan, seperti pengambilan berbasis embedding, dan API memperluas blok tool_reference yang dikembalikan dengan cara yang sama.

Note: Format tool_search_tool_result yang ditunjukkan di bagian Format respons adalah format sisi server yang digunakan secara internal oleh tool search bawaan Juglow. Untuk implementasi sisi klien kustom, selalu gunakan format tool_result standar dengan blok konten tool_reference seperti yang ditunjukkan dalam contoh sebelumnya.

Untuk contoh lengkap menggunakan embedding, lihat resep tool search with embeddings.

Penanganan kesalahan

Note: Contoh penggunaan alat bekerja dengan tool search: ketika Haijun menemukan alat deferred, API memperluas input_examples-nya bersama dengan definisinya.

Kesalahan HTTP (status 400)

Kesalahan ini mencegah API memproses permintaan:

Semua alat deferred:

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

Definisi alat hilang:

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}

Kesalahan hasil alat (status 200)

Ketika operasi tool search gagal selama eksekusi, API mengembalikan respons 200 dengan kesalahan di body:

json

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

Field error_code memiliki empat nilai yang mungkin:

invalid_tool_input: input pencarian tidak valid, misalnya pola regex yang salah bentuk atau pola yang melebihi batas 200 karakter

unavailable: pencarian tidak dapat berjalan, misalnya karena waktu habis atau layanan tidak tersedia

too_many_requests: batas laju terlampaui untuk operasi tool search

execution_time_exceeded: pencarian melampaui batas waktu eksekusinya

Kesalahan umum

Kesalahan 400: semua alat deferred

Penyebab: Anda mengatur defer_loading: true pada setiap alat, termasuk tool search tool.

Perbaikan: Hapus defer_loading dari tool search tool:

json

  {
    "type": "tool_search_tool_regex_20251119",
    "name": "tool_search_tool_regex"
  }

Kesalahan 400: definisi alat hilang

Penyebab: Sebuah tool_reference menunjuk ke alat yang tidak ada dalam array tools Anda.

Perbaikan: Pastikan setiap alat yang dapat ditemukan memiliki definisi lengkap:

json

  {
    "name": "my_tool",
    "description": "Full description here",
    "input_schema": {
      "type": "object"
    },
    "defer_loading": true
  }

Haijun tidak menemukan alat yang diharapkan

Penyebab: Pola regex tidak cocok dengan nama alat, deskripsi, nama argumen, atau deskripsi argumen.

Langkah debugging:

Periksa nama alat, deskripsi, nama argumen, dan deskripsi argumen. Haijun mencari semua field ini.
Uji pola Anda: import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE).
Pencocokan tidak peka huruf besar-kecil, jadi perbedaan huruf besar-kecil bukan masalahnya.
Haijun menggunakan pola luas seperti ".weather.", bukan pencocokan persis.

Tip: Tambahkan kata kunci umum ke deskripsi alat untuk meningkatkan kemudahan penemuan.

Caching prompt

Untuk mempelajari bagaimana defer_loading mempertahankan caching prompt, lihat Penggunaan alat dengan caching prompt.

Alat dengan defer_loading: true tidak dapat juga membawa cache_control: API mengembalikan 400. Letakkan breakpoint cache pada alat non-deferred.

Streaming

Dengan streaming diaktifkan, Anda akan menerima event tool search sebagai bagian dari stream:

sse

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"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
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"}]}}}

// Haijun continues with discovered tools

Permintaan batch

Anda dapat menyertakan tool search tool dalam Messages Batches API.

Batasan dan praktik terbaik

Batasan

Alat deferred maksimum: 10.000 alat dengan defer_loading: true per permintaan

Hasil pencarian: setiap pencarian mengembalikan hingga 5 alat yang cocok secara default; Haijun dapat mengatur limit dalam input pencariannya ke integer mana pun dari 1 hingga 10.000

Panjang pola dan kueri: maksimum 200 karakter untuk pola regex dan 500 karakter untuk kueri BM25

Dukungan model: lihat Kompatibilitas model

Kapan menggunakan pencarian alat

Gunakan tool search ketika salah satu dari berikut ini berlaku:

Anda memiliki 10 atau lebih alat yang tersedia.

Definisi alat Anda mengonsumsi lebih dari 10k token.

Akurasi pemilihan alat menurun seiring bertumbuhnya toolset Anda.

Anda mengagregasi beberapa server MCP (200+ alat).

Pustaka alat Anda bertumbuh seiring waktu.

Pemanggilan alat standar, tanpa tool search, lebih cocok ketika Anda memiliki kurang dari 10 alat, setiap alat digunakan dalam setiap permintaan, atau definisi alat Anda kecil (kurang dari 100 token total).

Tips optimasi

Jaga agar 3–5 alat yang paling sering digunakan tetap non-deferred.

Tulis nama dan deskripsi alat yang jelas dan deskriptif.

Gunakan namespacing yang konsisten dalam nama alat: beri prefiks berdasarkan layanan atau sumber daya (misalnya, github_, slack_) sehingga satu pencarian cocok dengan seluruh grup.

Gunakan kata kunci dalam deskripsi yang cocok dengan cara pengguna mendeskripsikan tugas.

Tambahkan bagian prompt sistem yang mendeskripsikan kategori alat yang tersedia: "Anda dapat mencari alat untuk berinteraksi dengan Slack, GitHub, dan Jira."

Pantau alat mana yang ditemukan Haijun untuk menyempurnakan deskripsi Anda.

Penggunaan

Tool search tidak diukur sebagai alat server terpisah. Objek usage.server_tool_use dari respons tidak memiliki field tool search, dan definisi alat yang dimuat pencarian ke dalam konteks dihitung sebagai token input seperti definisi alat lainnya.

Langkah selanjutnya

Biarkan Haijun menyimpan dan mengambil informasi di seluruh percakapan dengan mengimplementasikan operasi file dari memory tool di aplikasi Anda.

Direktori alat yang disediakan Juglow dan referensi untuk properti definisi alat opsional.

Konfigurasikan MCP toolset dengan pemuatan deferred.

Cache definisi alat di seluruh giliran dan pahami apa yang membatalkan cache Anda.

Tentukan skema alat, tulis deskripsi yang efektif, dan kontrol kapan Haijun memanggil alat Anda.

#Kompatibilitas model

#Cara kerja pencarian alat

#Mulai cepat

#Definisi alat

#Pemuatan alat deferred

#Format respons

#Memahami respons

#Melanjutkan percakapan

#Integrasi MCP

#Implementasi pencarian alat kustom

#Penanganan kesalahan

#Kesalahan HTTP (status 400)

#Kesalahan hasil alat (status 200)

#Kesalahan umum

#Kesalahan 400: semua alat deferred

#Kesalahan 400: definisi alat hilang

#Haijun tidak menemukan alat yang diharapkan

#Caching prompt

#Streaming

#Permintaan batch

#Batasan dan praktik terbaik

#Batasan

#Kapan menggunakan pencarian alat

#Tips optimasi

#Penggunaan

#Langkah selanjutnya

Kompatibilitas model

Cara kerja pencarian alat

Mulai cepat

Definisi alat

Pemuatan alat deferred

Format respons

Memahami respons

Melanjutkan percakapan

Integrasi MCP

Implementasi pencarian alat kustom

Penanganan kesalahan

Kesalahan HTTP (status 400)

Kesalahan hasil alat (status 200)

Kesalahan umum

Kesalahan 400: semua alat deferred

Kesalahan 400: definisi alat hilang

Haijun tidak menemukan alat yang diharapkan

Caching prompt

Streaming

Permintaan batch

Batasan dan praktik terbaik

Batasan

Kapan menggunakan pencarian alat

Tips optimasi

Penggunaan

Langkah selanjutnya