📘 תיעוד 139

התרחבות למספר רב של כלים באמצעות חיפוש כלים

הרחב את הסוכן שלך לאלפי כלים על ידי גילוי וטעינה של מה שנחוץ בלבד, לפי דרישה.

חיפוש כלים מאפשר לסוכן שלך לעבוד עם מאות או אלפי כלים על ידי גילוי וטעינה דינמיים שלהם לפי דרישה. במקום לטעון מראש את כל הגדרות הכלים אל חלון ההקשר, הסוכן מחפש בקטלוג הכלים שלך וטוען רק את הכלים הדרושים לו.

גישה זו פותרת שני אתגרים ככל שספריות הכלים גדלות:

• יעילות ההקשר: הגדרות כלים עלולות לצרוך חלקים גדולים מחלון ההקשר (50 כלים יכולים להשתמש ב-10 עד 20 אלף אסימונים), מה שמשאיר פחות מקום לעבודה בפועל.
• דיוק בבחירת כלים: הדיוק בבחירת כלים יורד כאשר נטענים יותר מ-30 עד 50 כלים בבת אחת.

#כיצד פועל חיפוש כלים

חיפוש כלים מופעל כברירת מחדל, למעט החריגים המפורטים תחת הגדרת חיפוש כלים.

כאשר הוא פעיל, הגדרות הכלים אינן נכללות בחלון ההקשר. הסוכן מקבל סיכום של הכלים הזמינים ומחפש כלים רלוונטיים כאשר המשימה דורשת יכולת שטרם נטענה. כברירת מחדל, עד חמישה מהכלים הרלוונטיים ביותר נטענים אל ההקשר, ושם הם נשארים זמינים לסבבים הבאים עד שה-SDK דוחס את ההודעות שבהן הסוכן גילה אותם. לאחר דחיסה זו, הסוכן יחפש שוב את אותם כלים בפעם הבאה שיזדקק להם.

חיפוש כלים מוסיף סבב תקשורת נוסף בכל פעם ש-Claude מחפש כלים, אך עבור מערכי כלים גדולים הדבר מתקזז בזכות הקשר קטן יותר בכל סבב. כאשר מדובר בפחות מכ-10 כלים שהגדרותיהם נכנסות בנוחות בחלון ההקשר, טעינת הכל מראש היא בדרך כלל מהירה יותר.

לפרטים על מנגנון ה-API הבסיסי, ראה חיפוש כלים ב-API.

הערה: חיפוש כלים אינו נתמך בפריסות Microsoft Foundry המתארחות ב-Azure, אשר דוחות אותו בצד השרת: ה-SDK מזהה את הדחייה וטוען את הגדרות הכלים מראש עבור אותה פריסה במקום זאת. המשתנה ENABLE_TOOL_SEARCH אינו יכול לעקוף זאת, מכיוון שהדחייה מגיעה מהפריסה עצמה.

#הגדרת חיפוש כלים

חיפוש כלים מופעל כברירת מחדל. עבור דגמים הנמצאים ברשימת הדגמים שאינם נתמכים של ה-SDK, ה-SDK טוען את הגדרות הכלים מראש במקום זאת, ושום ערך של ENABLE_TOOL_SEARCH אינו עוקף זאת. ב-Agent Platform של Google Cloud, ה-SDK קובע לפי דור הדגם:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 ודגמים מאוחרים יותר: חיפוש כלים מופעל כברירת מחדל.
• דגמי Agent Platform מוקדמים יותר: ה-SDK טוען את הגדרות הכלים מראש, מכיוון שמערכי ההגשה שלהם דוחים את כותרת ה-beta הנדרשת. המשתנה ENABLE_TOOL_SEARCH אינו יכול לעקוף זאת.

לפני Claude Code גרסה v2.1.221, ה-SDK השבית את חיפוש הכלים עבור כל הדגמים ב-Agent Platform של Google Cloud, אלא אם הגדרת את ENABLE_TOOL_SEARCH.

ה-SDK משבית את חיפוש הכלים גם כאשר ANTHROPIC_BASE_URL מצביע על מארח שאינו צד ראשון, מכיוון שרוב שרתי הפרוקסי אינם מעבירים בלוקים מסוג tool_reference. באפשרותך לעקוף ברירת מחדל זו באמצעות משתנה הסביבה ENABLE_TOOL_SEARCH:

הגדרת CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS שומרת על חיפוש כלים במצב כבוי. אינך יכול לעקוף זאת על ידי הגדרת ENABLE_TOOL_SEARCH בעצמך. הארגון שלך יכול להשאיר את חיפוש הכלים מופעל באמצעות הגדרות מנוהלות, ב-Claude Code גרסה v2.1.227 ומעלה. הסעיף השבתת יכולות טרום הפצה מפרט היכן העקיפה חלה ומה המשתנה מסיר.

חיפוש כלים חל על כל הכלים הרשומים, בין אם הם מגיעים משרתי MCP מרוחקים ובין אם משרתי MCP מותאמים אישית של ה-SDK. כאשר אתה משתמש ב-auto, ה-SDK סופר כל הגדרה שחיפוש כלים יכול להשהות לצורך סף משולב אחד: כל כלי MCP שאינו מסומן כ-alwaysLoad, מכל שרת שהוא, בתוספת הכלים המובנים שנטענים לפי דרישה. ה-SDK תמיד טוען מראש כלי ליבה מובנים כמו Bash, Read ו-Edit, ואינו סופר אותם כחלק מהסף.

הגדר את הערך באפשרות env של הפונקציה query(). ב-TypeScript, המאפיין env מחליף את סביבת תהליך המשנה, לכן יש לפרוס את ...process.env כדי לשמור על משתנים שהתקבלו בירושה. ב-Python, המאפיין env ממוזג על גבי הסביבה שהתקבלה בירושה. דוגמה זו מתחברת לשרת MCP מרוחק שחושף כלים רבים, מאשרת מראש את כולם בעזרת תו כללי (wildcard), ומשתמשת ב-auto:5 כך שחיפוש כלים מופעל כאשר ההגדרות שניתן להשהות מגיעות ל-5% מחלון ההקשר:

#TypeScript

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": {
          // 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: {
        ...process.env, // env replaces the subprocess environment, so keep inherited variables
        ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result
  console.log(`Session ended with an error: ${error}`);
}

#Python

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 deferrable definitions reach 5% of 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:
        
# A single-shot query() raises after yielding an error result
        print(f"Session ended with an error: {error}")


asyncio.run(main())

כדי להריץ דוגמה זו, החלף את https://tools.example.com/mcp בכתובת ה-URL של שרת ה-MCP שלך. במקרה של הצלחה, טקסט התוצאה יודפס לקונסולה.

מכיוון שזוהי קריאת query() חד פעמית, ה-SDK משליך שגיאה לאחר הפקת תוצאת שגיאה, ולכן הדוגמה עוטפת את הלולאה בבלוק try. כדי לראות מדוע ריצה נכשלה, בדוק בתוך הלולאה את ה-subtype של הודעת התוצאה, כגון error_during_execution. למידע נוסף על הודעות תוצאה, ראה טיפול בתוצאה.

#אופטימיזציה של גילוי כלים

מנגנון החיפוש מתאים שאילתות לשמות כלים ולתיאורים שלהם. שמות כמו search_slack_messages צצים עבור מגוון רחב יותר של בקשות מאשר query_slack. תיאורים עם מילות מפתח ספציפיות ("Search Slack messages by keyword, channel, or date range") מתאימים ליותר שאילתות מאשר תיאורים כלליים ("Query Slack").

באפשרותך גם להוסיף סעיף בהנחיית המערכת (system prompt) המפרט קטגוריות של כלים זמינים. הדבר מספק לסוכן הקשר לגבי סוגי הכלים שזמינים לחיפוש. העבר את הטקסט דרך האפשרות systemPrompt ב-TypeScript או system_prompt ב-Python, תוך שימוש בערך המוגדר מראש claude_code יחד עם append, המוסיף את הטקסט שלך להנחיית ברירת המחדל במקום להחליף אותה:

#TypeScript

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

#Python

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

לערכת האפשרויות המלאה של הנחיות מערכת, ראה שינוי הנחיות מערכת.

#מגבלות

• מספר כלים מרבי: 10,000 כלים בקטלוג שלך
• תוצאות חיפוש: מחזיר כברירת מחדל עד חמישה מהכלים הרלוונטיים ביותר לכל חיפוש
• תמיכה בדגמים: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 ודגמים מאוחרים יותר. ראה תאימות דגמים בתיעוד ה-API לרשימה הנוכחית. אותם תנאי מינימום חלים גם ב-Agent Platform של Google Cloud.

#תיעוד קשור

• חיפוש כלים ב-API: תיעוד API מלא עבור חיפוש כלים, כולל מימושים מותאמים אישית
• חיבור שרתי MCP: התחברות לכלים חיצוניים דרך שרתי MCP
• כלים מותאמים אישית: בניית כלים משלך עם שרתי MCP של ה-SDK
• הפניה ל-TypeScript SDK: תיעוד API מלא
• הפניה ל-Python SDK: תיעוד API מלא