Skip to main content

Scale ไปยัง tools จำนวนมากด้วย tool search

Scale agent ของคุณไปยัง tools หลายพัน รายการโดยค้นพบและโหลดเฉพาะที่จำเป็น ตามความต้องการ

Tool search ช่วยให้ agent ของคุณทำงานกับ tools หลายร้อยหรือหลายพันรายการโดยค้นพบและโหลดมันตามความต้องการแบบ dynamic แทนที่จะโหลด tool definitions ทั้งหมดลงใน context window ล่วงหน้า agent จะค้นหา tool catalog ของคุณและโหลดเฉพาะ tools ที่ต้องการ

แนวทางนี้แก้ปัญหาสองอย่างเมื่อ tool libraries ขยายใหญ่ขึ้น:

  • Context efficiency: Tool definitions สามารถใช้ส่วนใหญ่ของ context window (50 tools สามารถใช้ 10-20K tokens) ทำให้มีพื้นที่น้อยลงสำหรับงานจริง
  • Tool selection accuracy: ความแม่นยำของ tool selection ลดลงเมื่อโหลด tools มากกว่า 30-50 รายการพร้อมกัน

Tool search เปิดใช้งานโดยค่าเริ่มต้น หน้านี้ครอบคลุม วิธีการทำงาน, วิธี configure มัน, และวิธี optimize การค้นพบ tool

วิธีที่ Tool Search ทำงาน​

เมื่อ tool search ทำงาน tool definitions จะถูก withhold จาก context window agent จะได้รับสรุปของ tools ที่พร้อมใช้งานและค้นหา tools ที่เกี่ยวข้องเมื่องานต้องการ capability ที่ยังไม่โหลด tools 3-5 รายการที่เกี่ยวข้องที่สุดจะถูกโหลดเข้า context ซึ่งจะพร้อมใช้งานสำหรับ turns ถัดไป

Tool search เพิ่มการ round-trip พิเศษหนึ่งครั้งในครั้งแรกที่ Claude ค้นพบ tool (ขั้นตอนการค้นหา) แต่สำหรับ tool sets ขนาดใหญ่ สิ่งนี้จะถูกชดเชยด้วย context ที่เล็กลงในทุก turn

note

Tool search รองรับในทุก Claude model ยกเว้น Haiku

Tool search เปิดอยู่โดยค่าเริ่มต้น มันถูกปิดโดยค่าเริ่มต้นบน Vertex AI ซึ่งรองรับสำหรับ Claude Sonnet 4.5 และใหม่กว่า และ Claude Opus 4.5 และใหม่กว่า มันยังถูกปิดเมื่อ ANTHROPIC_BASE_URL ชี้ไปยัง non-first-party host คุณสามารถ override ค่าเริ่มต้นทั้งสองด้วยตัวแปรสภาพแวดล้อม ENABLE_TOOL_SEARCH:

ค่าพฤติกรรม
(ไม่ได้ตั้งค่า)Tool search เปิดอยู่ Tool definitions ถูก deferred และค้นพบตามความต้องการ
trueTool search เปิดอยู่เสมอ SDK ส่ง beta header แม้บน Vertex AI
autoตรวจสอบจำนวน token รวมของ tool definitions ทั้งหมดกับ context window ของ model ถ้าเกิน 10% tool search จะทำงาน
auto:Nเหมือน auto ด้วย percentage แบบ custom auto:5 ทำงานเมื่อ tool definitions เกิน 5% ของ context window
falseTool search ปิดอยู่ Tool definitions ทั้งหมดโหลดเข้า context ในทุก turn

ตั้งค่าใน option env บน query() ตัวอย่างนี้เชื่อมต่อกับ remote MCP server ที่ expose tools จำนวนมาก pre-approve ทั้งหมดด้วย wildcard และใช้ auto:5 เพื่อให้ tool search ทำงานเมื่อ tool definitions เกิน 5% ของ context window:

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" ปิด tool search และโหลด tool definitions ทั้งหมดเข้า context ในทุก turn สิ่งนี้ลบ search round-trip ซึ่งอาจเร็วกว่าเมื่อ tool set มีขนาดเล็ก (น้อยกว่า ~10 tools)

Optimize Tool Discovery​

กลไกการค้นหา match queries กับชื่อและคำอธิบาย tools ชื่อเช่น search_slack_messages จะ surface สำหรับคำขอที่หลากหลายกว่า query_slack คำอธิบายที่มี keywords เฉพาะ ("Search Slack messages by keyword, channel, or date range") match กับ queries มากกว่าคำอธิบายทั่วไป ("Query Slack")

คุณยังสามารถเพิ่ม system prompt section ที่แสดงรายการ tool categories ที่พร้อมใช้งาน:

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

ขีดจำกัด​

  • Tools สูงสุด: 10,000 tools ใน catalog ของคุณ
  • ผลการค้นหา: คืนค่า tools ที่เกี่ยวข้องที่สุด 3-5 รายการต่อการค้นหา
  • รองรับ model: ทุก Claude model ยกเว้น Haiku

เอกสารที่เกี่ยวข้อง​