Mở rộng lên nhiều tool với tool search

Tool search cho phép agent của bạn làm việc với hàng trăm hoặc hàng nghìn tool bằng cách khám phá và nạp chúng động theo yêu cầu. Thay vì nạp toàn bộ định nghĩa tool vào context window ngay từ đầu, agent tìm kiếm trong danh mục tool của bạn và chỉ nạp những tool nó cần.

Cách tiếp cận này giải quyết hai thách thức khi tập tool mở rộng:

• Hiệu quả context: định nghĩa tool có thể chiếm phần lớn context window (50 tool có thể dùng 10-20K token), để lại ít không gian hơn cho công việc thực sự.
• Độ chính xác khi chọn tool: độ chính xác chọn tool giảm khi có hơn 30-50 tool được nạp cùng lúc.

Tool search được bật mặc định.

Cách tool search hoạt động

Khi tool search hoạt động, định nghĩa tool bị giữ ngoài context window. Agent nhận một bản tóm tắt các tool khả dụng và tìm kiếm tool liên quan khi nhiệm vụ cần một khả năng chưa được nạp. Mặc định, tối đa năm tool liên quan nhất được nạp vào context, và chúng ở lại đó cho các lượt sau. Nếu hội thoại đủ dài để SDK nén (compact) các message trước đó để giải phóng không gian, các tool đã khám phá trước đó có thể bị loại bỏ, và agent tìm kiếm lại khi cần.

Tool search tốn thêm một round-trip lần đầu tiên Claude khám phá một tool (bước tìm kiếm), nhưng với tập tool lớn, chi phí này được bù lại bởi context nhỏ hơn ở mọi lượt. Với ít hơn khoảng 10 tool, nạp mọi thứ ngay từ đầu thường nhanh hơn.

Để biết chi tiết về cơ chế API bên dưới, xem Tool search trong API.

Ghi chú

Tool search được hỗ trợ trên Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5, và các model sau đó; xem khả năng tương thích model trong tài liệu API để biết danh sách hiện tại. Trên Google Cloud’s Agent Platform, model tối thiểu được hỗ trợ là Claude Sonnet 4.5 và Claude Opus 4.5.

Tool search cũng không được hỗ trợ trên các triển khai Microsoft Foundry chạy trên Azure, vì các triển khai này từ chối tính năng này từ phía server: SDK phát hiện việc từ chối và chuyển sang nạp định nghĩa tool ngay từ đầu cho triển khai đó. ENABLE_TOOL_SEARCH không thể ghi đè điều này, vì việc từ chối đến từ chính bên triển khai.

Cấu hình tool search

Tool search được bật mặc định. Nó bị tắt mặc định trên Google Cloud’s Agent Platform, nơi nó được hỗ trợ cho Claude Sonnet 4.5 trở lên và Claude Opus 4.5 trở lên. Nó cũng bị tắt khi ANTHROPIC_BASE_URL trỏ đến một host không phải first-party, vì hầu hết proxy không chuyển tiếp block tool_reference. Bạn có thể ghi đè mặc định bằng biến môi trường ENABLE_TOOL_SEARCH:

Giá trị	Hành vi
(chưa đặt)	Tool search được bật. Định nghĩa tool bị trì hoãn và khám phá theo yêu cầu. Tự động chuyển về nạp ngay từ đầu trên Google Cloud’s Agent Platform, ANTHROPIC_BASE_URL không phải first-party, hoặc triển khai Microsoft Foundry chạy trên Azure.
true	Tool search luôn bật, trừ triển khai Microsoft Foundry chạy trên Azure, nơi việc từ chối phía server vẫn buộc nạp ngay từ đầu. SDK gửi beta header ngay cả trên Google Cloud’s Agent Platform và qua proxy. Request sẽ thất bại trên các model Google Cloud’s Agent Platform cũ hơn Sonnet 4.5 hoặc Opus 4.5, hoặc trên proxy không hỗ trợ block tool_reference.
auto	Kiểm tra tổng số token của mọi định nghĩa tool so với context window của model. Nếu vượt 10%, tool search kích hoạt. Nếu dưới 10%, mọi tool được nạp vào context bình thường.
auto:N	Giống auto nhưng với phần trăm tùy chỉnh. auto:5 kích hoạt khi định nghĩa tool vượt 5% context window. Giá trị càng thấp thì càng kích hoạt sớm.
false	Tool search tắt. Mọi định nghĩa tool được nạp vào context ở mọi lượt.

Đặt CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS sẽ giữ tool search tắt, và ENABLE_TOOL_SEARCH không thể ghi đè điều này. Biến này loại bỏ beta header mà định nghĩa tool defer_loading và block nội dung tool_reference cần.

Tool search áp dụng cho mọi tool đã đăng ký, dù chúng đến từ MCP server từ xa hay SDK MCP server tùy chỉnh. Khi dùng auto, ngưỡng được tính dựa trên tổng kích thước của mọi định nghĩa tool trên tất cả server.

Đặt giá trị trong tùy chọn env của query(). Trong TypeScript, env thay thế toàn bộ môi trường subprocess, nên hãy dùng spread ...process.env để giữ lại các biến kế thừa. Trong Python, env được gộp thêm vào môi trường kế thừa. Ví dụ dưới đây kết nối tới một MCP server từ xa cung cấp nhiều tool, duyệt trước tất cả bằng wildcard, và dùng auto:5 để tool search kích hoạt khi định nghĩa của chúng vượt 5% 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": {
          // Kết nối tới một MCP server từ xa
          type: "http",
          url: "https://tools.example.com/mcp"
        }
      },
      allowedTools: ["mcp__enterprise-tools__*"], // Wildcard duyệt trước mọi tool từ server này
      env: {
        ...process.env, // env thay thế môi trường subprocess, nên giữ lại biến kế thừa
        ENABLE_TOOL_SEARCH: "auto:5" // Kích hoạt tool search khi tool vượt 5% context
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  // query() một lượt sẽ throw sau khi trả về một kết quả lỗi
  console.log(`Session ended with an error: ${error}`);
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "enterprise-tools": {
                "type": "http",
                "url": "https://tools.example.com/mcp",
            }
        },
        allowed_tools=[
            "mcp__enterprise-tools__*"
        ],  # Wildcard duyệt trước mọi tool từ server này
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Kích hoạt tool search khi tool vượt 5% context
        },
    )

    try:
        async for message in query(
            prompt="Find and run the appropriate database query",
            options=options,
        ):
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)
    except Exception as error:
        # query() một lượt sẽ raise sau khi trả về một kết quả lỗi
        print(f"Session ended with an error: {error}")


asyncio.run(main())

Để chạy ví dụ này, thay https://tools.example.com/mcp bằng URL MCP server của riêng bạn. Khi thành công, kết quả sẽ được in ra console.

Vì đây là một lệnh gọi query() một lượt, SDK sẽ raise sau khi trả về một kết quả lỗi, nên ví dụ bọc vòng lặp trong khối try. Để biết vì sao một lần chạy thất bại, kiểm tra subtype của message kết quả, ví dụ error_during_execution, bên trong vòng lặp.

Đặt ENABLE_TOOL_SEARCH thành "false" sẽ tắt tool search và nạp mọi định nghĩa tool vào context ở mọi lượt. Cách này loại bỏ round-trip tìm kiếm, có thể nhanh hơn khi tập tool nhỏ (dưới khoảng 10 tool) và định nghĩa vừa đủ với context window.

Tối ưu hóa việc khám phá tool

Cơ chế tìm kiếm khớp truy vấn với tên và mô tả tool. Tên như search_slack_messages xuất hiện cho nhiều loại yêu cầu hơn query_slack. Mô tả với từ khóa cụ thể (“Search Slack messages by keyword, channel, or date range”) khớp nhiều truy vấn hơn mô tả chung chung (“Query Slack”).

Bạn cũng có thể thêm một đoạn system prompt liệt kê các danh mục tool khả dụng. Điều này cho agent ngữ cảnh về loại tool nào có thể tìm kiếm. Truyền văn bản qua tùy chọn systemPrompt trong TypeScript hoặc system_prompt trong Python, dùng preset claude_code với append, để thêm văn bản của bạn vào prompt của preset thay vì thay thế nó:

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

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "You can search for tools to interact with Slack, GitHub, and Jira.",
    }
)

Để biết đầy đủ các tùy chọn system prompt, xem Chỉnh sửa system prompt.

Giới hạn

• Số tool tối đa: 10.000 tool trong danh mục của bạn
• Kết quả tìm kiếm: trả về tối đa năm tool liên quan nhất mỗi lần tìm kiếm theo mặc định
• Hỗ trợ model: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5, và các model sau đó. Trên Google Cloud’s Agent Platform, Claude Sonnet 4.5 trở lên và Claude Opus 4.5 trở lên.

Tài liệu liên quan

• Tool search trong API: tài liệu API đầy đủ cho tool search, bao gồm cách triển khai tùy chỉnh
• Kết nối MCP server: kết nối tới tool bên ngoài qua MCP server
• Tool tùy chỉnh: xây dựng tool riêng với SDK MCP server

Nguồn

Dịch và biên soạn từ Scale to many tools with tool search.