כוונון הקשר הכלים של סוכן
המדריך הזה עוסק בעבודה המעשית סביב משטח הכלים הדו־שכבתי: לראות מה הרצה שולחת, לשנות אותו, ולאבחן סוכן שהושיט יד לכלי הלא נכון. כדי להבין למה זה עובד כך, קראו את הקשר כלים ומטמון הנחיות.
לראות מה הרצה באמת שולחת
קטע בשם “לראות מה הרצה באמת שולחת”פתחו שיחה והקישו על מחוון השימוש בהקשר בכותרת השיחה. הוא בונה מחדש את המשטח המדויק שהשיגור הבא ישלח, בלי להריץ דבר. הצגת עוד (או הפקודה /context) פותחת את סייר ההקשר המלא, שבו תוכלו לבדוק כל כלי.
שני מקטעים חשובים כאן:
- הגדרות כלים וכלי MCP וכלים דינמיים — הקבוצה התושבת, עם עלות האסימונים האמיתית של כל כלי.
- כלים שנטענים לפי דרישה — מדד הטעינה לפי דרישה. כל רשומה מחויבת רק בשמה, מפני ששם הוא כל מה שהבקשה נושאת; פתיחת רשומה עדיין מציגה את התיאור והסכימה המלאים, כך שתוכלו לראות מה זה היה עולה אילו ההרצה משכה אותו פנימה.
אם המקטע של הטעינה לפי דרישה ריק, הטעינה לפי דרישה כבויה בשרת הזה. בדקו את --tool-deferral בתיעוד ה-CLI של cc_server.
לשנות אילו כלים נטענים מראש
קטע בשם “לשנות אילו כלים נטענים מראש”הקבוצה התושבת היא מדיניות, לא תצורה — היא נמצאת ב־ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) וחלה על כל הרצה:
residentBuiltins— אוצר המילים של קבצים ומעטפת.residentDiscovery—search_toolsו־list_my_tools. אל תסירו אותם; דרכם סוכן מגיע לכל השאר.residentMcpTools— קומץ כלי Control Center ששווים את הסכימה שלהם בכל בקשה.- בלוק לכל מצב, עבור הכלים שמצב נתון משתמש בהם כמעט בכל תור.
שני כללים בעת עריכתה:
הוסיפו כלי רק אם רוב ההרצות משתמשות בו. כל שם עולה את הסכימה שלו בכל בקשה של כל הרצה, לנצח. כלי שחשוב כשהוא בשימוש אבל נדיר בסך הכול שייך לחצי שנטען לפי דרישה — הסוכן עדיין ימצא אותו.
השתמשו בשם האמיתי של הכלי. שם תושב שאינו תואם שום כלי הוא אינרטי: בלי שגיאה, בלי אזהרה, הכלי פשוט נטען לפי דרישה. test/tooling/resident_tool_names_test.dart תופס זאת וגם מחזיק כל מצב מתחת ל־40 כלים תושבים, וזו כל מטרת התרגיל — מעבר לטווח הזה, בחירת הכלים מתדרדרת באופן מדיד.
הפעלים הנדרשים והמוצמדים של מצב מתווספים אוטומטית, כך שלעולם אין צורך לפרט את פועל הפלט של המצב עצמו.
לאבחן בחירה גרועה בכלי
קטע בשם “לאבחן בחירה גרועה בכלי”כשסוכן השתמש בכלי הלא נכון או הצהיר שהוא לא יכול לעשות משהו, בררו מה מבין שלושה דברים קרה.
1. האם הוא חיפש?
קטע בשם “1. האם הוא חיפש?”כל הרצה מתעדת את הכלים שנטענו לפי דרישה ואת מה שהפעיל אותם — קריאה ישירה בשם, או שאילתת search_tools. פתחו את זרם האירועים של ההרצה (הגדרות → סביבת עבודה → סוכנים → הסוכן → יומנים → הצגה) וחפשו [harness] loaded N deferred tool(s).
- לא תועד דבר, והסוכן אמר שהיכולת חסרה — הוא לא חיפש כלל. זו בעיה בהנחיה, לא בעיית שליפה: מדד הטעינה לפי דרישה נמצא בהנחיית המערכת שלו עם הוראה שלא להצהיר שהיכולת חסרה עד שחיפוש חוזר ריק.
- חיפוש תועד, אבל דבר לא נטען — החמצת שליפה אמיתית. עברו לשלב 2.
- כלים נטענו, אבל נעשה שימוש בכלי הלא נכון — הכלים שהוא מצא דומים מדי זה לזה. עברו לשלב 3.
2. לתקן החמצת שליפה
קטע בשם “2. לתקן החמצת שליפה”search_tools מתאים לפי שמות, תיאורים ושמות ארגומנטים. החמצה כמעט תמיד משמעה שהתיאור אינו מכיל את המילים שבהן הסוכן השתמש.
הוסיפו אותן. התיאורים הם מדד השליפה, לכן האריכו אותם במקום לקצץ — כתבו את אוצר המילים שמפעיל באמת היה מקליד („להקצות”, „להעביר הלאה”, „לתת ל־“), ולא רק את שם העצם הפנימי. קיצור תיאור כדי לחסוך אסימונים עולה לכם גם בהצלחת החיפוש וגם בדיוק הבחירה, וחוסך כמעט כלום לעומת הסכימה.
אם הכלי הנכון קיים אבל מדורג נמוך, לשם כך קיים הארגומנט limit; התיאור של הכלי עצמו אומר לסוכן להרחיב חיפוש שנראה קרוב אבל מפספס.
3. לתקן כלים דומים־מראה
קטע בשם “3. לתקן כלים דומים־מראה”אם לשני כלים יש תיאורים שנקראים אותו דבר למי שכבר לא יודע את ההבדל, המודל מנחש. מזגו אותם לכלי אחד עם ארגומנט מבדיל.
ticket_relation ו־ticket_pr_link הולכים לפי התבנית הזו: כל אחד מטפל בקישור ובניתוק קישור דרך ארגומנט מבדיל. בחירה שנעשית בתוך קריאה אחת, עם ההקשר המלא של הבקשה, מהימנה יותר מבחירה בין שני תיאורים דומים־מראה.
השאירו כלים נפרדים כשהם זקוקים לשערי אישור שונים, לביקורת שונה או לרינדור שונה — אלה סיבות שבגללן מיזוג יעלה לכם משהו אמיתי.
לוודא שמטמון ההנחיות עובד
קטע בשם “לוודא שמטמון ההנחיות עובד”שיעור הפגיעות במטמון מופיע בניטור → תובנות בתור שיעור מטמון. שיחה ארוכה בריאה נמצאת גבוה; אם הוא נמוך באופן מתמשך, משהו משכתב את הקידומת בכל תור.
סיבות נפוצות, לפי סדר ההסתברות:
- משהו לא דטרמיניסטי בתחילת ההנחיה. חתימת זמן, מזהה בקשה, או קבוצה שנעברת בסדר משתנה יעשו את זה.
- החלפת מודל או מאמץ באמצע השיחה. שניהם משנים את הקידומת. תת־סוכנים הם מקום שקל במיוחד לטעות בו: הרצת ילדים במאמץ נמוך יותר כדי לחסוך כסף יכולה לעלות יותר באובדן שיתוף המטמון ממה שהיא חוסכת.
- דחיסה תכופה. דחיסה משכתבת היסטוריה מעצם תכנונה, כך שהעלות שלה אמיתית; התיקון הוא לדחוס לעתים נדירות ובעומק, ולא לעתים קרובות וברדידות.
כיבוי הטעינה לפי דרישה עם --tool-deferral=off הוא השוואת A/B תקפה כדי לבודד אם שינוי התנהגות נבע מהמשטח הדו־שכבתי. הוא משחזר בדיוק את הבקשה שלפני הטעינה לפי דרישה, כך שאם ההתנהגות נמשכת כשזה כבוי, המשטח אינו הסיבה.