מדריך קלוד קוד בעברית
לאתר הראשי כל המדריכים קלאודפלייר קלוד דסקטופ גרוק CLI גרוק בוט MCP קרסור וואטסאפ OpenClaw n8n בענן n8n בהתקנה עצמית

תיעוד 180

הרחבה להרבה כלים עם חיפוש כלים

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

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

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

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

#איך חיפוש כלים עובד

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

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

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

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

[!NOTE]

חיפוש כלים אינו נתמך בפריסות 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 טוען את הגדרות הכלים מראש, כי סטאקי ההגשה שלהם דוחים את כותרת הבטא הנדרשת. ENABLE_TOOL_SEARCH לא יכול לעקוף את זה.

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

[!NOTE]

חיפוש כלים פעיל כברירת מחדל מאחורי שער ANTHROPIC_BASE_URL, בלי שום דבר להגדיר. אם השער דוחה אותו, ראו חיפוש כלים דרך שער LLM. לפני Claude Code v2.1.304, ה-SDK השבית את חיפוש הכלים מאחורי שער כזה אלא אם ENABLE_TOOL_SEARCH היה true, auto, או auto:N.

אתם שולטים אם ומתי הגדרות הכלים נדחות באמצעות משתנה הסביבה ENABLE_TOOL_SEARCH, שמקבל את הערכים האלה:

ערךהתנהגות
(לא מוגדר)חיפוש כלים פעיל, עם הגדרות כלים שנדחות ומתגלות לפי דרישה. נופל חזרה לטעינה מראש במודלים מוקדמים מ-Opus 4 ומ-Sonnet 4, במודלים המוקדמים יותר של Agent Platform, ובפריסות Microsoft Foundry שמתארחות ב-Azure.
trueחיפוש כלים פעיל, עם אותם מצבי נפילה כמו (לא מוגדר).
autoחיפוש כלים כבוי, והגדרות הכלים נטענות מראש, עד שההגדרות שהוא יכול לדחות מגיעות ל-10% מחלון ההקשר של המודל. אז חיפוש הכלים מופעל, ויכול להישאר פעיל באותה שיחה גם אם ההגדרות האלה יורדות אחר כך מתחת ל-10%.
auto:Nכמו auto עם אחוז מותאם. auto:5 מופעל כשההגדרות האלה מגיעות ל-5% מחלון ההקשר. ערכים נמוכים יותר מפעילים מוקדם יותר.
falseחיפוש כלים כבוי. כל הגדרות הכלים נטענות להקשר בכל תור.

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

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

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

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}`);
}
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 בכתובת של שרת ה-MCP שלכם. בהצלחה טקסט התוצאה מודפס לקונסולה.

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

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

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

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

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.",
    }
)

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

#מגבלות

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

#תיעוד קשור