مقیاس‌پذیری با جست‌وجوی ابزار

جست‌وجوی ابزار به ایجنتت امکان می‌دهد با صدها یا هزاران ابزار کار کند، با کشف و بارگذاریِ پویای آن‌ها به‌محضِ نیاز. به‌جای بارگذاریِ همه‌ی تعاریفِ ابزار در پنجره‌ی کانتکست از همان ابتدا، ایجنت در کاتالوگِ ابزارهایت جست‌وجو می‌کند و فقط ابزارهایی را که لازم دارد بارگذاری می‌کند.

این رویکرد دو چالش را با مقیاس‌پذیریِ کتابخانه‌های ابزار حل می‌کند:

کارایی کانتکست: تعاریفِ ابزار می‌توانند بخش‌های بزرگی از پنجره‌ی کانتکست را مصرف کنند (۵۰ ابزار می‌تواند ۱۰ تا ۲۰ هزار توکن استفاده کند) و فضای کمتری برای کارِ واقعی باقی بگذارند.
دقت انتخاب ابزار: دقتِ انتخابِ ابزار با بارگذاریِ هم‌زمانِ بیش از ۳۰ تا ۵۰ ابزار افت می‌کند.

جست‌وجوی ابزار به‌صورت پیش‌فرض فعال است. این صفحه نحوه‌ی کارکردِ آن، پیکربندیِ آن و بهینه‌سازیِ کشفِ ابزار را پوشش می‌دهد.

جست‌وجوی ابزار چطور کار می‌کند

وقتی جست‌وجوی ابزار فعال است، تعاریفِ ابزار از پنجره‌ی کانتکست کنار گذاشته می‌شوند. ایجنت یک خلاصه از ابزارهای موجود دریافت می‌کند و وقتی کار به قابلیتی نیاز دارد که از پیش بارگذاری نشده، به‌دنبالِ ابزارهای مرتبط می‌گردد. ۳ تا ۵ ابزارِ مرتبط‌ترین در کانتکست بارگذاری می‌شوند و آنجا برای نوبت‌های بعدی در دسترس می‌مانند. اگر مکالمه آن‌قدر طولانی باشد که SDK برای آزادکردنِ فضا پیام‌های قدیمی‌تر را فشرده کند، ممکن است ابزارهای کشف‌شده‌ی قبلی حذف شوند و ایجنت در صورت نیاز دوباره جست‌وجو کند.

جست‌وجوی ابزار اولین باری که Claude یک ابزار را کشف می‌کند یک رفت‌وبرگشتِ اضافی (گامِ جست‌وجو) اضافه می‌کند، اما برای مجموعه‌های بزرگِ ابزار، این با کانتکستِ کوچک‌ترِ در هر نوبت جبران می‌شود. با کمتر از حدودِ ۱۰ ابزار، بارگذاریِ همه‌چیز از ابتدا معمولاً سریع‌تر است.

برای جزئیاتِ سازوکارِ زیرینِ API، به جست‌وجوی ابزار در API نگاه کن.

پیکربندی جست‌وجوی ابزار

جست‌وجوی ابزار به‌صورت پیش‌فرض روشن است. روی Vertex AI به‌صورت پیش‌فرض غیرفعال است، جایی که برای Claude Sonnet 4.5 و بالاتر و Claude Opus 4.5 و بالاتر پشتیبانی می‌شود. همچنین وقتی ANTHROPIC_BASE_URL به یک میزبانِ غیراصلی (non-first-party) اشاره می‌کند غیرفعال است، چون بیشترِ پراکسی‌ها بلاک‌های tool_reference را فوروارد نمی‌کنند. می‌توانی هر کدام از این پیش‌فرض‌ها را با متغیرِ محیطیِ ENABLE_TOOL_SEARCH بازنویسی کنی:

مقدار	رفتار
(تنظیم‌نشده)	جست‌وجوی ابزار روشن است. تعاریفِ ابزار به تعویق می‌افتند و به‌محضِ نیاز کشف می‌شوند. روی Vertex AI یا با `ANTHROPIC_BASE_URL`ِ غیراصلی، به بارگذاریِ از ابتدا برمی‌گردد.
`true`	جست‌وجوی ابزار همیشه روشن است. SDK حتی روی Vertex AI و از طریق پراکسی‌ها هدرِ beta را ارسال می‌کند. درخواست‌ها روی مدل‌های Vertex AIِ قدیمی‌تر از Sonnet 4.5 یا Opus 4.5، یا روی پراکسی‌هایی که از بلاک‌های `tool_reference` پشتیبانی نمی‌کنند، شکست می‌خورند.
`auto`	تعدادِ کلِ توکن‌های همه‌ی تعاریفِ ابزار را در برابر پنجره‌ی کانتکستِ مدل بررسی می‌کند. اگر از ۱۰٪ بیشتر شوند، جست‌وجوی ابزار فعال می‌شود. اگر زیر ۱۰٪ باشند، همه‌ی ابزارها به‌صورت عادی در کانتکست بارگذاری می‌شوند.
`auto:N`	مثل `auto` با درصدِ سفارشی. `auto:5` وقتی تعاریفِ ابزار از ۵٪ پنجره‌ی کانتکست بیشتر شوند فعال می‌شود. مقادیرِ کمتر زودتر فعال می‌شوند.
`false`	جست‌وجوی ابزار خاموش است. همه‌ی تعاریفِ ابزار در هر نوبت در کانتکست بارگذاری می‌شوند.

جست‌وجوی ابزار روی همه‌ی ابزارهای ثبت‌شده اعمال می‌شود، چه از سرورهای راه‌دورِ MCP بیایند چه از سرورهای MCPِ سفارشیِ SDK. هنگام استفاده از auto، آستانه بر اساس اندازه‌ی کلیِ همه‌ی تعاریفِ ابزار در همه‌ی سرورهاست.

مقدار را در گزینه‌ی env در query() تنظیم کن. این مثال به یک سرور راه‌دورِ MCP که ابزارهای زیادی نمایش می‌دهد متصل می‌شود، همه‌ی آن‌ها را با یک wildcard از پیش تأیید می‌کند، و از auto:5 استفاده می‌کند تا وقتی تعاریفشان از ۵٪ پنجره‌ی کانتکست بیشتر شد، جست‌وجوی ابزار فعال شود:

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

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 pre-approves all tools from this server
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when tools exceed 5% of context
        },
    )

    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)


asyncio.run(main())

تنظیمِ ENABLE_TOOL_SEARCH روی "false" جست‌وجوی ابزار را غیرفعال می‌کند و همه‌ی تعاریفِ ابزار را در هر نوبت در کانتکست بارگذاری می‌کند. این کار رفت‌وبرگشتِ جست‌وجو را حذف می‌کند، که وقتی مجموعه‌ی ابزار کوچک است (کمتر از حدودِ ۱۰ ابزار) و تعاریف به‌راحتی در پنجره‌ی کانتکست جا می‌شوند، می‌تواند سریع‌تر باشد.

بهینه‌سازی کشف ابزار

سازوکارِ جست‌وجو کوئری‌ها را با نام‌ها و توصیف‌های ابزار تطبیق می‌دهد. نام‌هایی مثل search_slack_messages برای دامنه‌ی گسترده‌تری از درخواست‌ها ظاهر می‌شوند تا query_slack. توصیف‌هایی با کلمات کلیدیِ مشخص («Search Slack messages by keyword, channel, or date range») با کوئری‌های بیشتری تطبیق می‌یابند تا توصیف‌های کلی («Query Slack»).

همچنین می‌توانی یک بخشِ پرامپتِ سیستمی اضافه کنی که دسته‌های ابزارِ موجود را فهرست می‌کند. این کار به ایجنت کانتکستی درباره‌ی انواعِ ابزارهایی که می‌تواند جست‌وجو کند می‌دهد:

You can search for tools to interact with Slack, GitHub, and Jira.

محدودیت‌ها

بیشینه‌ی ابزارها: ۱۰٬۰۰۰ ابزار در کاتالوگت
نتایج جست‌وجو: ۳ تا ۵ ابزارِ مرتبط‌ترین را در هر جست‌وجو برمی‌گرداند
پشتیبانی مدل: هر مدلِ Claude به‌جز Haiku

مستندات مرتبط

جست‌وجوی ابزار در API: مستندات کاملِ API برای جست‌وجوی ابزار، شامل پیاده‌سازی‌های سفارشی
اتصال سرورهای MCP: از طریق سرورهای MCP به ابزارهای بیرونی متصل شو
ابزارهای سفارشی: ابزارهای خودت را با سرورهای MCPِ SDK بساز
مرجع TypeScript SDK: مرجع کاملِ API
مرجع Python SDK: مرجع کاملِ API