📘 תיעוד 40

תת-סוכנים ופרסונות

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

תת-סוכנים מופעלים כברירת מחדל.

#סוכנים מול פרסונות

סוכנים ופרסונות שניהם מתאימים אישית התנהגות, אך הם פועלים ברמות שונות:

סוכן מגדיר את ההפעלה עצמה. פרסונה מעצבת את האופן שבו תת-סוכן מתנהג בתוך הפעלה. תת-סוכן רץ תמיד כסוג סוכן (למשל, general-purpose), ויישוב יכול להוסיף שכבת פרסונה מעל.

נהל את שניהם במודאל הסוכנים. פתח אותו באמצעות /config-agents (כינוי /agents), או פתח את לשונית הפרסונות ישירות באמצעות /personas. למודאל שתי לשוניות: Agents ו-Personas.

#השבתת תת-סוכנים

השבת תת-סוכנים באמצעות משתנה סביבה או קובץ ההגדרות:

export GROK_SUBAGENTS=0              
# Environment variable

# ~/.grok/config.toml
[subagents]
enabled = false

#כיצד תת-סוכנים עובדים

כאשר הסוכן הראשי מזהה עבודה להאצלה, הוא קורא לכלי spawn_subagent כדי להתחיל הפעלת צאצא. הצאצא רץ עם:

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

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

#סוגי סוכנים מובנים

הכלי spawn_subagent מקבל פרמטר subagent_type שבוחר את תפקיד הצאצא:

סוכנים המוגדרים על ידי הפרויקט או המשתמש יכולים להוסיף סוגים חדשים או לדרוס (shadow) את המובנים הללו לפי שם.

#פרסונות

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

הגדר פרסונות ב-config.toml או בקבצי .toml:

[subagents.personas.researcher]
instructions = "You are a thorough researcher. Always cite specific file paths."
description = "Deep investigator."

Grok Build מגלה פרסונות מבוססות קבצים ממיקומים אלה, לפי סדר עדיפות:

• .grok/personas/*.toml (פרויקט)
• ~/.grok/personas/*.toml (משתמש)
• ספריית הפרסונות המצורפות מראש (העדיפות הנמוכה ביותר)

כל קובץ מגדיר פרסונה אחת, ושם הקובץ (ללא הסיומת) הופך לשם הפרסונה. פרסונות inline בתוך config.toml מקבלות עדיפות על פני קבצים. רק קבצי .toml מתגלים.

נהל פרסונות בלשונית Personas של מודאל הסוכנים (/personas). פרסונות מצורפות מראש הן לקריאה בלבד, פרסונות שאתה מגדיר ניתנות לעריכה.

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

#שדות פרסונה

#חוזי קלט ופלט

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

[[subagents.personas.reviewer.inputs]]
name = "review_file"
io_type = "file"
required = true
description = "Path to the code under review"

[[subagents.personas.reviewer.outputs]]
name = "summary_file"
io_type = "file"
required = false
description = "Path to write review notes"

לכל שדה יש name, סוג io_type (ברירת המחדל היא file), דגל required, ו-description.

#יישוב פרסונה

כאשר פרסונה חלה, Grok Build מיישב את המודל האפקטיבי ומאמץ החשיבה בסדר זה, מהעדיפות הגבוהה לנמוכה:

1. דריסה מפורשת בזמן ה-spawn
2. ברירת מחדל של התפקיד
3. ברירת מחדל של הפרסונה
4. הפעלת ההורה

בידוד פועל לפי אותו סדר עבור שלושת השלבים הראשונים, אך ברירת המחדל שלו היא none (ללא worktree) במקום לרשת מהפעלת ההורה.

אם מתבקשת פרסונה אך לא ניתן ליישב אותה: היא לא נמצאה, אין לה הוראות, או שקובץ ה-instructions_file שלה אינו קריא, ה-spawn נכשל.

#יצירת תת-סוכנים (Spawning)

הסוכן הראשי קורא לכלי spawn_subagent. הפרמטרים שלו:

כאשר אתה מריץ תת-סוכן ברקע, אחזר את התוצאה שלו מאוחר יותר באמצעות get_command_or_subagent_output.

#שליחת הודעות לתת-סוכנים

הכלי send_subagent_message כבוי כברירת מחדל. הפעל אותו באמצעות GROK_ACTIVE_AGENT_MESSAGES או [features] active_agent_messages.

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

• subagent_id: "parent" פונה לתת-סוכן ההורה הפעיל של אותו צאצא.
• מזהה סוכן עמיד פונה לתת-סוכן מקומי אחר. תת-סוכן שהסתיים ועומד בתנאים מתחדש עם אותה זהות.

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

שולחי צאצא מוגבלים: 4 הודעות בתהליך (in-flight) לכל זוג שולח-יעד, ו-32 הודעות יוצאות לכל ניסיון שליחה. שליחה מעבר למגבלה מחזירה QuotaExceeded.

תת-סוכן לא פעיל תמיד מתעורר עם ההודעה כתור הבא שלו. עבור תת-סוכן פעיל, הפרמטר האופציונלי delivery שולט באופן שבו ההודעה נוחתת:

• steer (ברירת המחדל) מצטרף לתור הנוכחי בנקודה הבטוחה הבאה שלו.
• queue ממתין כתור מאוחר מוגן במקום להיכנס לתור הפעיל.
• interject הוא דחוף: הוא נמסר לפני steers ממתינים בנקודה הבטוחה המוקדמת ביותר, והוא קוטע תת-סוכן שחסום בהמתנה לעבודת רקע, כך שתת-הסוכן קורא את ההודעה מיד. רק קריאת ההמתנה מסתיימת מוקדם. עבודת הרקע ממשיכה לרוץ.

אם תת-הסוכן פעיל אך נמצא בין תורות, steer ו-interject הופכים כל אחד לתור מוגן אחד בתור ותת-הסוכן מתחיל לעבוד עליו. הדגל הישן queue: true עדיין מתקבל ומשמעותו delivery: "queue". כאשר שניהם קיימים, delivery קובע.

התמליל מציג כל שליחה כשורה אחת של Message: פועל עבור התוצאה, לאחר מכן התווית של תת-הסוכן (הסוג, הפרסונה או התפקיד שלו) והתיאור שלו במירכאות מסולסלות, כפי ששורת הגלילה לאחור Subagent …: “…” שלו מצטטת אותו, מקוצר לשורה הראשונה ול-40 תווים. הפועל נושא את אופן המסירה, כך ש-steer נשאר ללא סימון:

• Message sent to Explore “find callers” (steer)
• Message queued for Explore “find callers” / Message interjected to Explore “find callers”
• Message sending to … עם תבליט מונפש בזמן שהשליחה בתהליך
• Message rejected · Explore “find callers” עבור שליחה שסורבה, Message unconfirmed · Explore “find callers” עבור שליחה שהמעטפת לא יכלה לאשר
• Message sent to parent כאשר צאצא שולח הודעה להורה שלו

השורה המכווצת לעולם אינה מציגה את ההודעה או את הסיבה. מקש חץ ימינה (או l/e במצב vim) מרחיב את השורה כדי להציג את המסירה המבוקשת, את טקסט ההודעה המלא ואת הסיבה לשליחה שסורבה או לא אושרה, מקש חץ שמאלה (או h) מכווץ אותה שוב. מקש Enter, Ctrl+F, או לחיצה כפולה על השורה פותחים את התצוגה של אותו תת-סוכן, בדיוק כמו בשורת ה-Subagent שלו (ימינה/שמאלה עדיין מקפלים אותה). אם תת-הסוכן מעולם לא נוצר בהפעלה זו (grok export ללא ממשק, או מזהה מהפעלה אחרת), השורה מכנה אותו subagent …xxxxxxxx מ-8 התווים האחרונים של המזהה שלו, מציגה את ה-Subagent ID: הגולמי כשהיא מורחבת, ואינה יכולה לפתוח אותו.

#מצבי יכולת (Capability Modes)

מצב יכולת אינו ארגומנט של spawn. הכלים של הצאצא מגיעים מ-סוג הסוכן שלו ומכל ברירת מחדל של תפקיד / הגדרה. הסוג general-purpose אינו מוגבל (all). הסוגים המובנים explore ו-plan קוראים, מחפשים ומריצים פקודות מעטפת, אך אינם יכולים לערוך קבצים.

#ירושת הקשר

#resume_from

הפרמטר resume_from מאפשר לתת-סוכן חדש להמשיך מהמקום שבו תת-סוכן שהסתיים עצר, דבר שימושי לתהליכי עבודה מרובי שלבים:

1. יצירת תת-סוכן מחקר כדי לחקור בעיה.
2. יצירת תת-סוכן שני עם resume_from מוגדר למזהה של תת-הסוכן הראשון, כדי שימשיך עם הקשר המחקר המלא.

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

#ירושת MCP

תת-סוכנים יורשים את שרתי ה-MCP של הפעלת ההורה ש-כבר מחוברים כברירת מחדל. זה כולל שרתי stdio/HTTP מקומיים וסוכנים שמקורם בתוספים (למשל my-plugin:reviewer). הצאצא מגלה וקורא לכלים אלה באמצעות search_tool / use_tool באותו אופן שבו ההורה עושה זאת.

שלוט בירושה באמצעות ה-frontmatter של הסוכן mcpInheritance:

דוגמה:

---
name: research-only
description: Read MCP tools but not internal connectors
tools: search_tool, use_tool, Read
mcpInheritance:
  except:
    - internal-tools
---

סוכני תוספים יורשים את ה-MCP של ההורה באותו אופן. מטעמי אבטחה הם עדיין אינם יכולים:

• להצהיר על mcpServers משלהם ב-frontmatter של הסוכן (מתעלמים עם אזהרה)
• להצהיר על hooks ב-frontmatter של הסוכן
• להגדיר permissionMode: bypassPermissions

שרתי MCP המצורפים לתוסף (קובץ .mcp.json של התוסף) עדיין מתחברים אל ההורה/ההפעלה לאחר שניתן אמון בתוסף: הם אינם הצהרת frontmatter המיועדת לצאצא בלבד. ראה תוספים ו-שרתי MCP.

#בידוד: מצב Worktree

עבור משימות שמשנות קבצים, הרץ תת-סוכן בתוך git worktree מבודד באמצעות isolation: worktree. זה מונע מעריכות הצאצא להתנגש עם אלה של ההורה:

• תת-הסוכן עובד בעותק משלו של עץ העבודה.
• השינויים שלו נשארים מבודדים מההורה עד שאתה ממזג אותם.
• התוצאה של תת-הסוכן כוללת את נתיב ה-worktree.

Grok Build מנהל סביבות worktree דרך מתודות ההרחבה x.ai/git/worktree/*, כולל פעולת apply שממזגת שינויים בחזרה לספריית העבודה הראשית.

#הגדרות

#מתגים ודריסות מודל לפי סוג

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

[subagents.toggle]
explore = true                       
# default -- omit to keep enabled
plan = false                         
# disable the plan subagent

[subagents.models]
explore = "grok-4.6"                 
# route explore to a specific model

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

#תפקידים ופרסונות מותאמים אישית

הגדר תפקידים מותאמים אישית עם ברירות מחדל משלהם ליכולות ולמודל:

[subagents.roles.researcher]
description = "Deep research agent"
default_capability_mode = "read-only"
model = "grok-4.6"
prompt_file = ".grok/prompts/researcher.md"

הגדר פרסונות מותאמות אישית עם הוראות התנהגותיות:

[subagents.personas.concise]
instructions = "Be concise. No filler words."
# instructions_file = ".grok/personas/concise.md"  
# or load from a file

Grok Build מגלה גם תפקידים מתוך .grok/roles/*.toml ופרסונות מתוך .grok/personas/*.toml. הגדרות inline ב-config.toml מקבלות עדיפות על פני קבצים.

#חלונית המשימות (TUI)

Grok Build מציג עבודה שרצה ועבודה שהסתיימה בחלוניות צדדיות במסך הסוכן:

• לחץ על Ctrl+G כדי להציג או להסתיר את חלונית המשימות, המפרטת תת-סוכנים פעילים וכאלה שהסתיימו ופקודות רקע עם הסטטוס שלהם.
• לחץ על Ctrl+T כדי להציג או להסתיר את חלונית המטלות הנפרדת.

כדי לצפות בסוגי הסוכנים ובפרסונות הזמינים, פתח את לוח הפקודות באמצעות Ctrl+P ובחר Manage Agents (/config-agents).

תת-סוכנים מופיעים בראש חלונית המשימות בקבוצת "Subagents" מתקפלת משלהם.

#צפייה בתת-סוכנים ב-TUI

תת-סוכנים מופיעים במספר מקומות ב-TUI האינטראקטיבי:

#גלילה לאחור (היסטוריית שיחת ההורה)

כאשר נוצר תת-סוכן, בלוק מחזור חיים קומפקטי מתווסף לגלילה לאחור של ההורה:

• Subagent running: "do the thing" (Implementer · grok-4.6) · Thinking
• או עבור תת-סוכני רקע: Subagent started: "..."

בזמן ריצה, הבלוק מציג סיומת פעילות חיה (למשל "Running: cargo test", "Compacting", "Retrying (2/3)") שנמשכת ממעקב התורות של הצאצא. התבליט מונפש (או צבוע) בהתאם למצב.

לחץ על Enter (או Ctrl-F) על הבלוק כדי לפתוח את התמליל המלא של תת-הסוכן.

עבור תת-סוכנים חוסמים, הרשומה הבודדת מעדכנת את צבע התבליט שלה כאשר הצאצא מסיים. עבור אלה שברקע, מתווסף בלוק המשך Subagent completed/failed/cancelled in Xs: "...".

#חלונית המשימות (Ctrl+G)

כפי שצוין לעיל: מקובצים תחת "Subagents", עם ספינרים, זמנים שחלפו וגישה מהירה להפסקה (kill) או בדיקה. לחץ על h כדי להחליף בין הסתרת מה שהסתיים לבין הצגת הכל.

#מעגן (כאשר מופעל)

המעגן שמעל ההנחיה מפרט תת-סוכנים. כאשר המעגן בפוקוס, h מחליף בין הסתרת מה שהסתיים לבין הצגת הכל (אותו סינון כמו בחלונית המשימות). מקשי חץ שמאלה / ימינה מכווצים ומרחיבים כותרת מקטע.

#תצוגה ממוסגרת במסך מלא (תמליל הצאצא)

כאשר אתה פותח תת-סוכן (מבלוק גלילה לאחור, מחלונית המשימות או משורת לוח בקרה), מסגרת עם גבול מחליפה את תצוגת ההורה ומציגה את התמליל המלא של הצאצא:

• שורת כותרת בתוך המסגרת: סמל סטטוס (ספינר / ✓ / ✗), תווית + תיאור מודגש + מודל, תג אופציונלי "resumed"/"forked", פעילות חיה · זמן שחלף, וכפתור סגירה [✗].
• הגלילה לאחור, החשיבה וקריאות הכלים של הצאצא עצמו מתרנדרים בתוך המסגרת.
• חלונית המשימות, חלונית המטלות, המעגן והקטלוג של ההורה מוסתרים למשך זמן התצוגה.

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

מה שעדיין עובד

• גלילה, קיפול, העתקה, פתיחת קישורים ופתיחת מציג הבלוקים (block viewer) בתמליל הצאצא.
• Ctrl+C מבטל את התור של צאצא זה. הוא אינו מבטל את ההורה.
• Ctrl+. / Ctrl+X פותח את דף הקיצורים עבור המקשים של הצאצא.
• פקדי לוח הבקרה בכותרת ההשתלטות ([Dashboard], ‹ / ›) עדיין פועלים על ההורה.
• מקש Enter במצב סרק ב-block viewer מצטט את השורה שנבחרה לתוך ה-composer של ההורה וסוגר את התצוגה.

מה שלא עושה דבר (נכשל במצב סגור)

צירופי מקשים של השורש בלבד לעולם אינם מופעלים במשטח זה. הם אינם פותחים מודאל על הצאצא, ואינם דולפים להורה:

• לוח הפקודות (Ctrl+P), בורר המודלים (Ctrl+M), בורר ההפעלות (Ctrl+R)
• הגדרות, הרחבות, אישור תמידי (Ctrl+O), שליחה לרקע (Ctrl+B)
• עורך הנחיות חיצוני, מעבר מצבים עם Shift+Tab

פעולה שנדחתה גורמת לציור מחדש שקט. אין הודעת toast.

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

כיצד לצאת

• q או Esc מגלילה לאחור נקייה, או לחיצה על [✗].
• אם חיפוש בגלילה לאחור פתוח, q / Esc סוגר תחילה את החיפוש. לחיצה נוספת סוגרת את התצוגה.
• Ctrl+Q תמיד יוצא מ-Grok. הוא לעולם אינו נבלע כאן.

הגלילה לאחור של ההורה ממשיכה להציג את הסטטוס של תת-הסוכן לאחר הסגירה.

#מגבלות עומק

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

#מתי להשתמש בתת-סוכנים

תרחישי שימוש טובים:

• חקירת בסיס קוד בזמן שההורה ממשיך בעבודה אחרת
• הרצת בדיקות במקביל בזמן שההורה מממש שינויים
• סקירת שינויים שנוצרו לפני שאתה מבצע commit
• האצלת משימות עצמאיות שאינן תלויות זו בזו

מתי לא להשתמש:

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