Orchestration רב-סוכני — Subagents, Agent Teams, ושליטה בעלות

מ-Single Agent ל-Team — מתי בכלל צריך כמה סוכנים

הפיתוי הכי גדול אחרי שבנית harness שעובד הוא להכפיל אותו. "אם סוכן אחד טוב, חמישה יהיו פי חמש." זו טעות שמדגדגת לכל vibe coder, והיא יקרה — מילולית. לפני שנכתוב שורת קוד אחת של orchestration, צריך לענות על שאלה אחת: מה הבעיה שצוות פותר שסוכן יחיד לא פותר?

יש בדיוק שלוש תשובות לגיטימיות, ושאר המקרים הם over-engineering:

• Parallelism אמיתי — יש 8 קבצים שצריך לסקור, והסקירות לא תלויות זו בזו. סוכן יחיד יעשה אותן בטור (8 × זמן); צוות יעשה אותן במקביל (1 × זמן, 8 × עלות). אתה קונה זמן בכסף.
• הפרדת אחריות (separation of concerns) — משימה שדורשת שני "מצבי חשיבה" סותרים. למשל: סוכן שכותב קוד וסוכן שמבקר אותו. אם תבקש מאותו סוכן גם לכתוב וגם לבקר, הוא יאשר את עצמו. הפרדה לשני subagents עם system prompts שונים יוצרת מתח בריא.
• Context isolation — תת-משימה שדורשת המון context משלה (לדוגמה, קריאת 30 קבצי לוג) ושהיית מעדיף שלא תזהם את ה-context של ה-supervisor. אתה שולח subagent, הוא "שורף" את ה-context שלו על הלוגים, ומחזיר רק את המסקנה. ה-supervisor נשאר רזה.

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

יש דרך מהירה לבדוק לאיזה מקרה אתה שייך — שאלה אחת על תלויות: "אם אריץ את תת-המשימות בסדר אקראי, האם התוצאה תשתנה?" אם כן (יש תלות סדר) → ליניארי, סוכן יחיד. אם לא (הסדר לא משנה) → יש מקביליות, מועמד לצוות. זו לא שאלה פילוסופית — היא בדיוק מה שקובע אם asyncio.gather חוקי כאן או לא. ב-orchestration, גרף התלויות הוא הארכיטקטורה; כל השאר זה אינסטרומנטציה סביבו.

נקודה שקל לפספס: גם כשיש מקביליות, היא לא תמיד שווה את העלות. parallelism קונה זמן ומשלם ב-כסף — תמיד. אם 8 הסקירות לוקחות 4 שניות כל אחת בטור (32 שניות) ואין לך לחץ זמן, אולי 32 שניות סדרתיות עם סוכן יחיד עדיפות על פני 8 sessions מקבילים ב-8× עלות. החלטת ה-fan-out היא תמיד trade-off בין latency לעלות, ולא ברירת מחדל. ככלל אצבע: fan-out משתלם כשהמקביליות גם חוסכת זמן וגם כשמדובר בעבודה שבכל מקרה היית עושה (כלומר ה-8× עלות לא נוסף — הוא פשוט במקביל במקום בטור).

תרחישי גבול שכדאי להכיר מראש

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

• "אני רוצה תשובה מהירה יותר, אז אני מפצל." זה לא parallelism, זה פנטזיה. אם המשימה היא מונוליטית (למשל "נתח את הבאג הזה"), פיצול לא יקצר — רק יוסיף overhead של handoff ו-spawn. רק עבודה שאפשר לחלק ל-N חתיכות בלי תלות סדר מתאימה ל-fan-out.
• "אני רוצה תשובה 'ממספר זוויות'." זה fork, לא team. אם אתה רוצה 3 גישות לאותה בעיה, השתמש ב-forkSession (נכיר בהמשך) — לא ב-supervisor שמפצל 3 subagents לאותה משימה. fork חולק context, team מכפיל context.
• "אני רוצה בקרת איכות." סוכן יחיד עם self-critique step בלולאה (פרק 2) עושה את זה ב-30% מהעלות של reviewer נפרד. הפרדה ל-author+reviewer הגיונית רק אם הביקורת דורשת system prompt שונה מהותית (למשל: תפקיד, סמכויות, סט כלים), לא סתם "עוד prompt שמבקר".

ה-Supervisor Loop — ה-Harness שמעל ה-Harnesses

ה-supervisor (נקרא גם orchestrator) הוא סוכן-על שלא עושה את העבודה בעצמו — הוא מפרק משימה לתת-משימות, מפצל subagent לכל אחת, ומאחד את התוצאות. אם הלולאה מפרק 2 הייתה goal → call model → run tools → repeat, הלולאה של ה-supervisor היא goal → decompose → spawn subagents → collect → synthesize.

החדשות הטובות: subagent הוא בדיוק ה-harness שכבר בנית. אתה לא לומד טכנולוגיה חדשה — אתה עוטף את ה-harness הקיים בלולאה אחת מעליו. הנה השלד המינימלי ב-Python מעל ה-Claude Agent SDK:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

# subagent = ה-harness שכבר בנית, עכשיו עם תקרות משלו
async def run_subagent(task: str, max_turns: int, budget_tokens: int):
    used_tokens = 0
    options = ClaudeAgentOptions(
        system_prompt="אתה worker ממוקד. בצע רק את המשימה שקיבלת.",
        max_turns=max_turns,          # הבלם מפרק 2 — לכל subagent בנפרד
    )
    result_text = ""
    async for message in query(prompt=task, options=options):
        # token accounting מפרק 5 — סופרים בזמן אמת
        if hasattr(message, "usage"):
            used_tokens += message.usage.input_tokens + message.usage.output_tokens
            if used_tokens > budget_tokens:        # budget cap לכל subagent
                return {"task": task, "status": "budget_exceeded",
                        "partial": result_text, "tokens": used_tokens}
        if hasattr(message, "result"):
            result_text = message.result
    return {"task": task, "status": "done",
            "result": result_text, "tokens": used_tokens}

# ה-supervisor: מפרק, מפצל, מאחד
async def supervisor(goal: str):
    # 1. decompose — מפרקים את ה-goal לתת-משימות עצמאיות
    subtasks = [
        "סקור את קבצי src/auth/ ודווח על בעיות אבטחה",
        "סקור את קבצי src/api/ ודווח על בעיות אבטחה",
        "סקור את קבצי src/db/  ודווח על בעיות אבטחה",
    ]
    # 2. spawn — כל subagent עם תקרות משלו, במקביל
    results = await asyncio.gather(*[
        run_subagent(t, max_turns=8, budget_tokens=40_000) for t in subtasks
    ])
    # 2.5 token accounting — מדפיסים per-subagent + total לפני synthesize
    for r in results:
        print(f"{r['task'][:30]:30s} → status={r['status']:15s} tokens={r['tokens']:,}")
    total_tokens = sum(r["tokens"] for r in results)
    print(f"{'TOTAL':30s} → {total_tokens:,} tokens")
    # 3. synthesize — ה-supervisor מאחד רק את המסקנות
    return synthesize(goal, results)

שלוש נקודות שמבדילות supervisor אמיתי מ-"לולאה שמריצה לולאות":

• כל subagent מקבל max_turns ו-budget_tokens משלו. זו לא תוספת — זו הליבה. נחזור לזה בסעיף העלות, אבל תזכור: ה-budget cap הוא בתוך ה-subagent, לא רק ב-supervisor.
• ה-supervisor לא מעביר את כל ההיסטוריה ל-subagent. כל subagent מקבל רק את ה-task string שלו. את ה-handoff הממוקד נבנה בסעיף נפרד — זו אחת הטעויות הכי יקרות אם מפספסים אותה.
• ה-synthesize מקבל רק מסקנות, לא transcripts. אם תזרוק את כל ה-output של שלושת ה-subagents ל-context של ה-supervisor, תאיץ compaction (פרק 3) ותשרוף tokens. כל subagent מחזיר תקציר מובנה, וה-supervisor מאחד תקצירים.

נקודה עדינה שכדאי להבין לפני שמתקדמים: ה-supervisor עצמו צריך max-turns ו-budget. זה לא רק subagents. תאר לך שכל ה-subagents חזרו תקינים, אבל שלב ה-synthesize (האיחוד) נתקע בלולאה כי הוא מנסה לאחד סיכומים סותרים. בלי תקרה על ה-supervisor, הוא יכול לרוץ עד שה-token counter של ה-API יחנוק אותו — או, גרוע יותר, עד שתקבל חשבון בלתי צפוי. הכלל: לכל סוכן בעץ, גם השורש, יש תקרה משלו. ה-supervisor מקבל תקרה גדולה יותר (כי הוא מאחד), אבל לא בלתי-מוגבלת.

שלושת דפוסי ה-Orchestration שתפגוש

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

• Fan-out / fan-in — ה-supervisor מפצל N subagents עצמאיים בו-זמנית (fan-out), מחכה לכולם, ומאחד (fan-in). זה הדפוס בשלד למעלה. מתאים לסקירות מקבילות, חיפוש רחב, או כל עבודה ש-"חלק אותה ל-N ואחד". זה גם הדפוס הכי קל לתמחר מראש.
• Pipeline / chain — subagents בשרשרת: הפלט של אחד הוא הקלט של הבא. כאן אין מקביליות אמיתית, אז שאל את עצמך אם בכלל צריך subagents — לעיתים קרובות זו לולאה ליניארית מחופשת. הצדקה אמיתית לשרשרת היא context isolation: כל שלב צריך context שונה לגמרי (למשל: extractor → summarizer → formatter, כל אחד עם system prompt אחר).
• Hierarchical / recursive — supervisor שמפצל subagents שהם בעצמם supervisors שמפצלים עוד subagents. עץ. כאן ה-cost explosion הכי מסוכן, כי כל רמה מכפילה. אם אתה לא ה-Anthropic שבונה compiler עם 16 סוכנים — כמעט תמיד עדיף שתי רמות לכל היותר.

הדפוס שתשתמש בו 90% מהזמן הוא fan-out/fan-in. הוא הכי פשוט לתמחר (N × עלות subagent), הכי קל לעשות לו tracing (span לכל ענף), והכי בטוח מבחינת cost — אין רקורסיה שמתפוצצת. אם אתה מתחיל ב-orchestration, התחל שם.

והנה הקוד ל-pipeline pattern לשם השוואה — שים לב שהוא כמעט זהה לסוכן יחיד עם context חיצוני, ולכן הצדקה צריכה להיות חזקה:

# pipeline: extractor → summarizer → formatter, כל אחד subagent נפרד
async def pipeline_documentation(notes: str) -> str:
    extract = await run_subagent(
        f"חלץ עובדות מובנות מתוך: {notes}", max_turns=5, budget_tokens=15_000)
    if extract["status"] != "done":
        return {"status": "failed_at_extract", "partial": extract}
    summary = await run_subagent(
        f"סכם את העובדות הבאות לפסקה אחת: {extract['result']}",
        max_turns=3, budget_tokens=10_000)
    if summary["status"] != "done":
        return {"status": "failed_at_summary", "partial": summary}
    return await run_subagent(
        f"עצב את הפסקה הבאה כ-Markdown: {summary['result']}",
        max_turns=3, budget_tokens=10_000)

Anti-Patterns של Multi-Agent — מה לא לעשות

לפני שממשיכים, שווה לעצור ולהגדיר את הצורות הנפוצות של כישלון ב-multi-agent. רוב הקוד שתראה ב-Stack Overflow ובפוסטים על "Agentic AI" נופל לפחות אחד מה-patterns האלה. ההגנה היא להכיר אותם בשם:

• Shared-state pollution — subagents שונים שמשתפים את אותו dict/list ודורסים זה את זה. זה קורה כשמנסים "לחסוך" על ידי כתיבת state משותף במקום כל subagent עם state משלו. התוצאה: תוצאות לא-דטרמיניסטיות שבלתי-אפשרי לדבג. הכלל: state פר-subagent, תמיד.
• Circular handoff — agent A קורא ל-agent B, שקורא ל-agent C, שקורא בחזרה ל-A. בלי timeout גלובלי, הלולאה רצה עד שמישהו נחנק על tokens. תיקון: graph של תלויות שאסור לו להכיל מעגלים, או hop counter פר-handoff שמסרב לעבור את N קפיצות.
• Subagent שעושה רק routing — supervisor שמפצל "router" agent שרק מחליט לאן להעביר, בלי ערך מוסף. זה over-engineering קלאסי: אתה משלם על session מלא כדי לקבל תשובה של משפט אחד. routing הוא תפקיד של ה-supervisor עצמו (if/elif), לא סוכן.
• Unbounded depth — hierarchical של 4+ רמות. גם אם ההגיון "מתאים" לעץ עמוק, העלות מתפוצצת: 3 רמות של 3 subagents = 27 sessions, ו-27 sessions × 20 turns = בלתי-אפשרי. תקרה קשיחה: 2 רמות בלבד, אלא אם כן אתה Anthropic עם תקציב מחקר.
• Untyped handoff — subagent שמחזיר free-form text וה-supervisor מנסה לפרסר אותו בכוח. זה הסיכון ש-flagged במפורש ב-course.research.json: "Fragility of parsing unstructured free-form text outputs from agents instead of enforcing structured JSON schemas." תיקון: JSON schema חובה על כל פלט subagent (פרק 4).

🔬 Case Study — Refactoring של Shared-State Pollution

קוד שראיתי בפועל ב-2 פרויקטונים שונים בשבוע שעבר: "למה כל subagent צריך state משלו? בואו נחסוך dict אחד". הנה האב-טיפוס, מצומצם:

# ❌ Anti-pattern: shared mutable state בין subagents
blackboard = {"findings": []}  # dict משותף לכל הצוות

async def review_module(module: str):
    findings = await scan(module)  # 4-8 findings אופייני
    blackboard["findings"].extend(findings)  # race בכתיבה מקבילית
    return blackboard  # מחזירים את כל ה-state, לא רק findings שלנו

async def supervisor_bad():
    return await asyncio.gather(*[review_module(m) for m in MODULES])
# תסמין: findings חסרים, סדר לא-דטרמיניסטי, דיבוג בלתי-אפשרי

מה השתבש: שלושת ה-subagents רצים במקביל דרך asyncio.gather, ו-extend() על list משותף בלי Lock מייצר race: לפעמים finding נדרס, לפעמים כפול. התיקון הוא לא להוסיף asyncio.Lock — אלא לבטל את ה-state המשותף. כל subagent מחזיר את שלו, וה-supervisor מאחד:

# ✅ Refactored: per-subagent state, merge ב-supervisor
async def review_module(module: str) -> list[dict]:
    findings = await scan(module)  # רק שלי, אין כתיבה ל-blackboard
    return findings  # מחזירים רק findings שלנו, לא את כל ה-dict

async def supervisor_good():
    per_module = await asyncio.gather(*[review_module(m) for m in MODULES])
    merged = [f for module_findings in per_module for f in module_findings]
    return merged  # איחוד דטרמיניסטי, בלי race

מה הרווחנו: אפס race condition (כל subagent רץ על state משותף לקריאה בלבד), איחוד דטרמיניסטי ב-supervisor, וכל subagent ניתן לדיבוג בנפרד — span הוא הגבול. העיקרון שעומד מאחורי: subagent = פונקציה טהורה על input, ה-state הוא רק ה-input שקיבלנו + ה-output שהחזרנו.

Ephemeral מול Durable — ההחלטה המרכזית

זו ההחלטה הארכיטקטונית הכי חשובה ב-orchestration, והיא חוזרת גם בפרק 8 כשתחליט in-process מול hosted. course.research.json מסמן אותה במפורש כ-key_decision: "Ephemeral vs. Durable State: Deciding whether to use ephemeral, session-bound agents (like Claude Agent Teams) or durable, code-defined agents with persistent state databases (like LangGraph or Aden Hive)." שני סוגי orchestration:

• Ephemeral orchestration (session-bound) — הסוכנים חיים רק לאורך session אחד. כשהמשימה נגמרת, הם נעלמים, וה-state שלהם נעלם איתם. זה המודל של Claude Agent Teams (לפי course.research.json, GA פברואר 2026 לצד Claude Sonnet 4.6): מופעי Claude מקבילים שמתקשרים בזמן אמת כ-teammates ארעיים. מצוין למשימות חד-פעמיות, מהיר להקים, אפס תשתית state.
• Durable orchestration (persistent state) — הסוכנים מוגדרים בקוד, ויש להם state database מתמשך. ריצה יכולה להיעצר ולהמשיך מאוחר יותר, ו-state שורד בין הרצות. זה המודל של frameworks כמו LangGraph (הבסיס ל-Deep Agents של LangChain) ו-Aden Hive (לפי course.research.json: outcome-driven multi-agent harness שמייצר את ה-graph מתיאור בשפה טבעית, ~10.5k כוכבים ב-GitHub). מתאים ל-pipelines שרצים שוב ושוב, ל-human-in-the-loop שמחכה שעות לאישור, ולתהליכים שחייבים לשרוד crash.

עוד נקודה שלא תמיד ברורה: durable לא אומר שהסוכן עצמו רץ ברקע. הוא אומר שה-state שלו שרד. הסוכן עצמו עדיין קם, רץ, ויורד — רק שכשהוא קם שוב, הוא טוען את ה-state מה-DB. זה הבדל חשוב: durable זה persistence של מידע, לא availability של חישוב. אם אתה צריך גם availability (סוכן שרץ 24/7 ומגיב מיידית לאירועים), אתה צריך managed/hosted — וזה כבר פרק 8.

ההיברידי שכמעט תמיד עובד

בפועל, רוב ה-harnesses הטובים אינם טהורים. הם ephemeral בתוך, durable מסביב: ה-supervisor וה-subagents רצים ephemeral (מהיר, אפס תשתית) למשך ריצה אחת — אבל ה-תוצאות וה-state הקריטי (decisions, deliverables, failures) נכתבים ל-store מתמשך בין הריצות. ככה אתה מקבל את המהירות של ephemeral ואת השרידות של durable בלי לשלם את מלוא מחיר ה-state DB על כל turn.

זה בדיוק ה-threshold-based backup מפרק 3, רק במעלה רמה: שם שמרת state קריטי לפני compaction; כאן אתה שומר את תוצאת הריצה לפני שה-session הארעי נעלם. וזה גם הגשר לפרק 7 — ה-store המתמשך הזה הוא בדיוק ה-memory store שעליו ירוץ Dreaming. שים לב לתבנית החוזרת: ריצה ארעית, זיכרון מתמשך. היא תחזור בכל harness production שתבנה.

דוגמה מעשית להיברידי: דוח סקירת קוד שרץ בכל commit (ephemeral — 30 שניות), אבל הממצאים נכתבים לטבלת code_reviews ב-DB (durable — שורד). בלי DB, אין היסטוריה; בלי ephemeral, כל commit מחכה ל-DB write שלא נגמר.

Parallel Subagent Cost Explosion — הסכנה שלא רואים עד החשבון

זו הסכנה המספר-אחת של orchestration רב-סוכני, והיא מופיעה במפורש ב-topic_risk_flags וב-gotchas של course.research.json. הציטוט המדויק: "Parallel Subagent Cost Explosion: Each spawned subagent consumes a completely separate session, leading to exponential token cost spikes."

הסיבה פשוטה אבל קלה לפספס: כל subagent הוא session נפרד לחלוטין. יש לו ה-system prompt שלו, ה-context שלו, ההיסטוריה שלו. כשאתה מפצל 5 subagents, אתה לא משלם פי 5 על "עוד קצת עבודה" — אתה משלם על 5 חלונות context מלאים, כל אחד גדל בכל turn.

בוא נראה את המתמטיקה. נניח subagent ממוצע: ~3,000 input tokens ב-context ההתחלתי, גדל ב-~2,000 tokens בכל turn (history מצטבר + tool results), ו-~500 output tokens ל-turn:

שורת המפתח היא האחרונה: subagent אחד בלי budget cap שנתקע בלולאה (בדיוק התרחיש שה-circuit-breaker מפרק 5 נועד לתפוס) יכול לשרוף יותר tokens מכל שאר הצוות יחד. הסכנה היא לא "צוות גדול", אלא צוות בלי תקרות פר-subagent.

שים לב למה זה לא ליניארי, כי זו הנקודה שמפילה אנשים. כל subagent הוא session נפרד, ובכל turn ה-context שלו גדל — ההיסטוריה מצטברת, tool results נערמים. כלומר ה-turn העשירי של subagent יקר משמעותית מה-turn הראשון שלו, כי הוא נושא את כל מה שקדם לו. עכשיו הכפל את זה ב-N subagents שכל אחד עושה את אותו דבר. התוצאה: כשאתה מכפיל את ה-turns, אתה לא מכפיל את העלות — אתה מרבע אותה בערך (כי גם מספר ה-turns וגם הגודל של כל turn גדלים). זה ההבדל בין "פי 3 כי 3 subagents" (לינארי, צפוי) ל-"פי 15 כי כל אחד עשה 20 turns ארוכים" (ריבועי, מפתיע).

תקרת ה-Parallelism — מתי עוד סוכנים מחמירים את המצב

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

• API rate limits — Anthropic (וכל ספק) מגבילים requests-per-minute. אם 10 subagents קוראים במקביל, אתה פוגע ב-rate limit וחלקם נחנקים ב-429. תיקון: semaphore מודע ל-rate limit, או backoff.
• Supervisor context bloat — ה-supervisor שמחכה ל-N תוצאות צריך להחזיק את כולן בזיכרון עד ה-synthesize. אם 10 תוצאות × 5K tokens כל אחת = 50K רק של תוצאות, וזה נכנס ל-compaction buffer. תיקון: stream תוצאות בחזרה, או summarize לפני שמחזירים.
• Failure multiplication — אם הסיכוי להצלחה של subagent הוא 90%, הסיכוי שכל 10 יצליחו במקביל הוא רק 0.9¹⁰ ≈ 35%. כל subagent נוסף מכפיל את הסיכוי שמשהו ייכשל. תיקון: תכנן retry או partial-success mode ("עבור אם 7/10 הצליחו").

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

שים לב ש-max_turns לבדו לא מספיק: subagent יכול לעשות 8 turns "חוקיים" שכל אחד מהם מחזיר tool result של 40KB ולשרוף תקציב עצום בלי לחצות את תקרת ה-turns. לכן budget_tokens הוא בלם נפרד — הוא סופר את מה ש-max_turns לא רואה. ובלם שלישי, ה-circuit-breaker, תופס את המקרה הספציפי של לולאה לפני ששני האחרים בכלל מתקרבים. שלושתם יחד, פר-subagent — זו רשת הביטחון.

הנה מחשבון ה-cost שתבנה כ-deliverable — פונקציה דטרמיניסטית, בלי LLM, שמעריכה מראש:

def estimate_run_cost(n_subagents: int, turns_per_subagent: int,
                      base_input: int = 3_000, growth_per_turn: int = 2_000,
                      output_per_turn: int = 500,
                      price_in_per_mtok: float = 3.0,
                      price_out_per_mtok: float = 15.0):
    """אומדן tokens ועלות USD לריצה רב-סוכנית. דטרמיניסטי, לרוץ לפני spawn."""
    input_per_agent = 0
    for turn in range(turns_per_subagent):
        # ה-context גדל בכל turn — זה הלא-ליניארי
        input_per_agent += base_input + growth_per_turn * turn
    output_per_agent = output_per_turn * turns_per_subagent

    total_input  = input_per_agent  * n_subagents
    total_output = output_per_agent * n_subagents
    cost_usd = (total_input  / 1_000_000) * price_in_per_mtok \
             + (total_output / 1_000_000) * price_out_per_mtok
    return {
        "total_input_tokens":  total_input,
        "total_output_tokens": total_output,
        "total_tokens": total_input + total_output,
        "est_cost_usd": round(cost_usd, 4),
    }

# לפני spawn — בודקים אם זה שפוי
print(estimate_run_cost(n_subagents=5, turns_per_subagent=20))
# {'total_tokens': ~1.1M, 'est_cost_usd': ~1.05}  → לישראלי: + מע"מ + שער ILS/USD

Claude Agent Teams — מקביליות עם תקשורת בזמן אמת

עד עכשיו ה-supervisor שלנו היה היררכי: supervisor מדבר ל-workers, workers לא מדברים ביניהם. זה דפוס supervisor→worker. Claude Agent Teams מוסיף משהו חדש: worker↔worker — סוכנים מקבילים שמתקשרים ביניהם בזמן אמת, לא רק דרך ה-supervisor.

לפי course.research.json, Claude Agent Teams הוא "a design primitive in Claude Code that allows dedicated, parallel Claude instances to act as ephemeral teammates communicating directly in real-time", שיצא ל-GA בפברואר 2026 לצד Claude Sonnet 4.6. ה-key update המלווה: Anthropic הדגימה את היכולת על ידי בניית C compiler פונקציונלי עם 16 סוכני Claude מקבילים על פני 2,000 sessions.

מה ה-case study הזה מלמד, ומה הוא לא מלמד:

• מה כן: בעיות שניתנות לחלוקה ברורה (compiler = lexer + parser + codegen + optimizer + tests) מתאימות במיוחד ל-Agent Teams. כל סוכן בעל אחריות מוגדרת, והם מתאמים בזמן אמת על הממשקים ביניהם.
• מה לא: 16 סוכנים × 2,000 sessions זה הרבה tokens. זה הדגמה של יכולת, לא של חיסכון. אל תסיק מזה ש"יותר סוכנים = יותר טוב". הסק שכש-הבעיה מתחלקת באמת, scale אפשרי — אבל מי שמשלם הוא אתה, ולכן ה-budget caps מהסעיף הקודם הם לא אופציה.

פירוט קצר על ה-compiler case study, כי הוא מלמד על הארכיטקטורה: ה-16 סוכנים חולקו לתפקידים — כל אחד אחראי על "שכבה" של ה-compiler (lexing, parsing, type-checking, code generation לכל target, optimization, tests). הם תיאמו בזמן אמת על ה-AST format, על ה-symbol table API, ועל ה-IR (intermediate representation). זה בדיוק המקרה שבו peer-to-peer קריטי: parser ו-type-checker חייבים להסכים על ה-AST node structure תוך כדי, לא דרך supervisor שמתווך. עם תיווך, כל שינוי ב-AST דורש round-trip דרך ה-supervisor, שמאט את הצוות בסדר גודל. ה-case study הזה מוכיח שבבעיות מצומדות, ה-peer channel הוא must, לא nice-to-have.

ההבדל המעשי בין supervisor heirarchy ל-Agent Teams:

למה ה-peer communication חשוב מבחינה הנדסית, ולא רק "נחמד"? בדפוס supervisor→worker, כל פיסת מידע שעוברת בין שני workers חייבת לעשות מסלול של שתי קפיצות: worker A → supervisor → worker B. זה אומר שה-supervisor חייב להחזיק בראש את כל מצב התיאום של כל הזוגות, וה-context שלו תופח. בבעיה צמודה עם 5 חלקים, יש 10 זוגות פוטנציאליים של תיאום — וכולם עוברים דרך צוואר בקבוק אחד. עם peer communication, A מדבר ל-B ישירות, ה-supervisor משוחרר לתפקיד שלו (פירוק ואיחוד), וה-context שלו נשאר רזה. זה בדיוק למה Anthropic בחרה ב-Agent Teams ל-compiler: lexer, parser, ו-codegen חייבים להסכים על ממשקים תוך כדי, ולתעל את כל זה דרך supervisor אחד היה הופך אותו לצוואר בקבוק.

אבל שים לב למה זה לא מלמד. Agent Teams הוא primitive מנוהל של Claude Code — אתה לא כותב את לולאת התקשורת, Claude Code מנהל אותה. זה נוח, אבל זה גם אומר שאתה מאבד חלק מהשליטה הגרעינית שבנית בקורס (הלולאה המפורשת, ה-state management הידני). זו אותה דילמת control מול convenience שתחזור בפרק 8 כשתחליט in-process מול hosted. ל-fan-out פשוט של תת-משימות עצמאיות, ה-supervisor→worker הידני שכתבת נותן לך יותר שליטה בזול. ל-תיאום הדוק בין חלקים מצומדים, Agent Teams חוסך לך לכתוב מנגנון תקשורת שלם — בתמורה לשליטה.

V2 Session API — send/stream מנותקים וניהול sessions

כדי לתזמר sessions מרובים, אתה צריך שליטה גרעינית יותר ממה ש-query() המונוליטי נותן. כאן נכנס ה-V2 Session API. לפי course.research.json זוהי "a modernized preview API within the Claude Agent SDK that shifts away from the single, monolithic query() generator to decoupled send() and stream() methods", ומאפשרת "create, resume, list, and fork" של sessions.

למה זה משנה ל-orchestration:

• send() / stream() מנותקים — במקום generator יחיד שמחזיק את כל הריצה, אתה שולח הודעה ומקבל stream בנפרד. זה מאפשר ל-supervisor להחזיק כמה sessions פתוחים בו-זמנית ולנהל אותם בלי שכל אחד יחסום את האחר.
• createSession / resumeSession / listSessions — ניהול מחזור החיים של sessions. resumeSession הוא הבסיס ל-durable: אתה יכול לעצור subagent, לשמור את ה-session id, ולהמשיך אותו מאוחר יותר.
• forkSession — היכולת המעניינת ביותר ל-orchestration. אתה לוקח session בנקודה מסוימת ו"מפצל" אותו לכמה מסלולים שונים מאותה נקודת התחלה. שימוש קלאסי: לנסות 3 גישות שונות לאותה בעיה במקביל, מאותו context משותף, ולבחור את הטובה ביותר.

# דפוס fork — לנסות כמה מסלולים מאותה נקודה (סכמטי; אמת מול ה-docs)
from claude_agent_sdk import unstable_v2_createSession, unstable_v2_forkSession

async def explore_approaches(base_goal: str, approaches: list[str]):
    # 1. session בסיס משותף — מבצע את ה-setup פעם אחת
    base = await unstable_v2_createSession(system_prompt="...")
    await base.send(base_goal)            # context משותף שכל ה-forks יורשים

    # 2. fork לכל גישה — כל fork יורש את ה-base אבל מתפצל ממנו
    forks = [await unstable_v2_forkSession(base.id) for _ in approaches]

    # 3. כל fork מנסה מסלול אחר, במקביל — עם budget cap לכל אחד
    results = await asyncio.gather(*[
        run_fork(fork, approach, budget_tokens=30_000)
        for fork, approach in zip(forks, approaches)
    ])
    return pick_best(results)

בנוסף ל-fork, resumeSession פותח את דפוס ה-durable orchestration. הנה דוגמה מעשית — pipeline שעוצר ל-human-approval:

# resume pattern — subagent שמחכה לאישור אנושי
from claude_agent_sdk import unstable_v2_createSession, unstable_v2_resumeSession

async def approval_gated_subagent(plan: str, approver_id: str):
    # 1. צור session, שלח תוכנית, בקש אישור
    session = await unstable_v2_createSession(
        system_prompt="אתה agent שמבצע רק אחרי אישור אנושי")
    await session.send(f"הכן תוכנית עבור: {plan}")
    plan_text = await session.stream_until_text()

    # 2. שמור session_id לפני שה-process יורד — כאן durable מתחיל
    session_id = session.id
    save_to_db("pending_approvals", session_id=session_id,
               plan=plan_text, approver=approver_id, status="waiting")

    # 3. חזור מאוחר יותר (אולי שעות) והמשך
    #  resume_session = await unstable_v2_resumeSession(session_id)
    #  await resume_session.send(f"האישור התקבל. בצע: {plan_text}")
    return session_id

זה בדיוק ה-pattern שמאפשר lead-enrichment של ה-capstone: הסוכן מכין טיוטת email, נשמר ב-DB עם status "pending", וכשהאדם מאשר ב-UI, ה-process חוזר וממשיך אותו session — בלי לאבד את הקונטקסט של ההכנה.

Handoff בין סוכנים — להעביר context ממוקד, לא את הכל

זו הנקודה שמחברת את הפרק הזה ישירות ל-context management מפרק 3, והיא אחת הטעויות הכי יקרות ב-orchestration. כשאתה מפצל subagent, מה אתה מעביר לו?

הפיתוי: "אעביר לו את כל ההיסטוריה של ה-supervisor, ליתר ביטחון, שיהיה לו את כל ההקשר." זו טעות שעולה משולש:

• מנפח את ה-context של ה-subagent — הוא מתחיל עם 30K tokens של היסטוריה לא רלוונטית במקום 2K של המשימה שלו.
• מאיץ compaction (פרק 3) — ה-subagent מגיע לסף ה-83.5% מהר יותר, וההיסטוריה שלו נדחסת — אולי דווקא החלק החשוב.
• שורף tokens — אתה משלם על העברת אותו context שוב ושוב, לכל subagent בנפרד.

ה-handoff הנכון מעביר רק את ה-context הממוקד למשימה: ה-task string, ה-constraints הרלוונטיים, וה-references (לא התוכן המלא) ל-state חיצוני אם צריך. הנה מודול handoff מינימלי:

def build_handoff(subtask: str, shared_constraints: list[str],
                  refs: dict | None = None) -> str:
    """בונה context ממוקד ל-subagent — לא את כל ההיסטוריה."""
    parts = [f"המשימה שלך (וזו בלבד): {subtask}", ""]
    if shared_constraints:
        parts.append("אילוצים שחלים על כל הצוות:")
        parts += [f"  - {c}" for c in shared_constraints]
    if refs:
        # references ל-store חיצוני, לא התוכן עצמו (פרק 3 — scratchpad)
        parts.append("\nמקורות זמינים (טען לפי צורך):")
        parts += [f"  - {k}: {v}" for k, v in refs.items()]
    parts.append("\nאל תניח context שלא נמסר לך כאן. שאל אם חסר.")
    return "\n".join(parts)

# בשימוש מתוך ה-supervisor:
handoff = build_handoff(
    subtask="סקור את src/auth/ לבעיות אבטחה",
    shared_constraints=["דווח רק high/critical", "JSON output בלבד"],
    refs={"security_policy": "file://policies/sec.md"},   # reference, לא תוכן
)

שים לב: ה-refs מעבירים הצבעה ל-store חיצוני (קובץ, KV) — בדיוק ה-scratchpad / working memory מפרק 3. ה-subagent טוען את התוכן רק אם הוא צריך אותו, במקום לקבל 50KB של policy ב-context ההתחלתי.

שלושה דפוסי handoff — בחר לפי המשימה

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

• Minimal handoff (task + constraints) — הקצר ביותר. מתאים ל-subagents שעובדים על קובץ או פיסת קוד עצמאית, בלי צורך ב-context חיצוני. הסיכון: ה-subagent עלול להחליט בלי context קריטי (למשל, "למחוק" קובץ בלי לדעת שהוא שייך לפיצ'ר פעיל).
• Structured handoff (task + constraints + structured payload) — הוספת payload מובנה (JSON) עם הקשר ספציפי. למשל, ה-supervisor מעביר רשימת 5 קבצים רלוונטיים ב-JSON, ולא את כל ה-repo. זה הדפוס המומלץ לרוב המקרים — מאזן בין בהירות לעלות.
• Resumable handoff (task + constraints + handoff_id) — ה-subagent מקבל handoff_id שמצביע ל-state ב-DB. הוא יכול לקרוא, לעבוד, ולכתוב בחזרה ל-DB. זה מה שמאפשר resume אחרי crash (durable) או המשך על ידי subagent אחר (handoff בין sessions). הסיכון: coupling לסכמת ה-DB.

כלל אצבע מעשי: אם ה-subagent שלך יכול לסיים את המשימה בלי לדבר עם אף אחד אחר, minimal מספיק. אם הוא צריך רק "את הנתונים האלה", structured. אם הוא צריך "לדבר" עם העולם (לכתוב, לקרוא, לחכות לאישור) — resumable.

Observability לצוות — Trace לכל Subagent

זוכר את ה-Langfuse מפרק 5? כאן הוא הופך מ"נחמד שיש" ל"בלעדיו אי אפשר". כשסוכן יחיד נתקע, אתה יכול לקרוא את ה-print-ים. כשאחד מתוך 5 subagents מקבילים נתקע, בלי tracing אין לך מושג איזה, איפה, או כמה זה עלה. צוות בלי observability הוא קופסה שחורה כפול N.

הדפוס: trace אחד לכל הריצה, span נפרד לכל subagent, ו-sub-span לכל turn ו-tool call בתוכו. ככה אתה רואה את כל הצוות במבט אחד, יכול לפתוח כל subagent בנפרד, ולייחס token cost לכל ענף.

from langfuse import Langfuse
lf = Langfuse()

async def supervisor_traced(goal: str, subtasks: list[str]):
    trace = lf.trace(name="multi-agent-run", input={"goal": goal})
    async def run_one(task, idx):
        # span לכל subagent — נראה בנפרד ב-Langfuse
        span = trace.span(name=f"subagent-{idx}", input={"task": task})
        result = await run_subagent(task, max_turns=8, budget_tokens=40_000)
        span.update(output=result, metadata={"tokens": result["tokens"],
                                              "status": result["status"]})
        span.end()
        return result
    results = await asyncio.gather(*[run_one(t, i) for i, t in enumerate(subtasks)])
    trace.update(output={"n_agents": len(results),
                         "total_tokens": sum(r["tokens"] for r in results)})
    return results

עכשיו כשתפתח את ה-trace ב-Langfuse, תראה את ה-supervisor למעלה ושלושה spans מתחתיו — אחד לכל subagent, כל אחד עם ה-tokens, ה-status (done / budget_exceeded), וה-latency שלו. ה-subagent שנתקע בולט מיד באדום.

Token Attribution — לחלק את החשבון בצורה הוגנת

Tracing נותן לך נתונים גולמיים, אבל השאלה הניהולית היא: למי מיוחס ה-cost? בעולם production עם ריצות רבות, אתה צריך attribution ברור. שלוש שיטות נפוצות, ולכל אחת trade-off:

• By-subagent (הכי קל) — כל span עם ה-tokens שלו, הסיכום ב-trace. מתאים ל-debugging ולשיפור ביצועים ("איזה subagent צורך הכי הרבה?").
• By-supervisor (הכי הוגן ל-billing) — כל ה-tokens של הריצה (supervisor + כל ה-subagents) מיוחסים למי שהפעיל את הריצה. זה מה שתרצה לחייב לקוח או למדוד ROI.
• By-tenant (ל-multi-tenant) — חלוקה לפי לקוח/פרויקט. דורש metadata על ה-tenant בכל span. הכי מורכב, אבל הכי חשוב אם יש לך כמה לקוחות על אותו harness.

מילון מונחים

בדוק/י את עצמך

סיכום הפרק וגשר לפרק הבא

צ'קליסט סיום פרק

סמן/י כל סעיף לפני המעבר לפרק 7. אם משהו לא מסומן — חזור אליו, הוא יחזור להכאיב בפרק 8.

• בניתי supervisor loop שמפצל 2–3 subagents במקביל עם asyncio.gather.
• לכל subagent יש max_turns וגם budget_tokens משלו — לא רק ל-supervisor.
• גם ל-supervisor עצמו יש max_turns ו-budget_tokens (גדולים יותר, אבל לא בלתי-מוגבלים).
• אני יכול/ה לנמק במשפט אחד מתי משימה צריכה צוות ומתי סוכן יחיד עדיף.
• אני מכיר/ה את 5 ה-anti-patterns (shared-state, circular, unbounded-depth, untyped, subagent-as-router) ובודק/ת את הקוד שלי מולם.
• יש לי טבלת החלטה ephemeral↔durable, ואני יודע/ת לאיזה צד ה-capstone שלי נוטה ולמה.
• החלטתי האם ה-capstone שלי היא "ephemeral בתוך, durable מסביב" או דפוס אחר.
• בניתי מחשבון cost דטרמיניסטי שרץ לפני spawn ומזהה את נקודת ההתפוצצות (500K+).
• תרגמתי את ה-cost-per-run ל-₪ כולל מע"מ ושער USD (הערת שוק מקומי).
• אני מבין/ה את ההבדל בין supervisor→worker ל-worker↔worker (Agent Teams), ומתי כל אחד.
• עטפתי כל קריאת unstable_v2_* בשכבת abstraction דקה (sessions.py) — לא פיזרתי אותן.
• אני יודע/ת מתי להשתמש ב-resumeSession (durable orchestration, pause-for-approval) ומתי ב-forkSession (כמה גישות לאותה בעיה).
• מודול ה-handoff שלי מעביר task + constraints + references בלבד — לא את כל ההיסטוריה.
• בחרתי בין minimal / structured / resumable handoff לפי מורכבות המשימה.
• מדדתי במספרים את החיסכון של handoff ממוקד מול handoff מלא (תרגיל 3).
• כל subagent מקבל span נפרד ב-Langfuse, ואני יכול/ה לפתוח כל אחד ולראות tokens + status.
• החלטתי על מודל token attribution (by-subagent / by-supervisor / by-tenant) לפי הצורך שלי.
• הרצתי את אותה משימה ephemeral מול durable והשוויתי traces (תרגיל 4 — deliverable מרכזי).
• בדקתי שה-circuit-breaker מפרק 5 תופס לולאת tool גם בתוך subagent, לא רק בסוכן יחיד.
• ענה/תי על כל 5 שאלות ה-check-yourself בלי לחזור לטקסט.
• סימנתי את אזורי ה-freshness (V2 Session API ב-preview) שצריך לאמת מול ה-docs לפני production.