מדריך לחוקרים

למי מיועד המדריך

לחוקרי AI ולמפתחים שרוצים לחקור, לשחזר ולהרחיב ניסויים ב-Agent-Lab. מי שכותבים Python, משתמשים ב-Jupyter וחושבים במונחים של ניסויים, סוכנים ו-pipelines ירגישו כאן בבית. היכרות עם LLMs, RAG ויסודות הקונטיינרים מועילה, אך אינה נדרשת.

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

התחלה מהירה — הרצת הדוגמאות

דרישות: Python 3.12+, סביבת Jupyter פועלת (JupyterLab או Notebook), ובאופן אופציונלי Docker מקומי לאינטגרציות מקצה לקצה. עבודה בעותק משוכפל של המאגר:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

פותחים את notebooks/ ומתחילים עם 01_…, וממשיכים במחברות שמעניינות אותך.

הערות:

• המחברות ברובן עצמאיות; בכותרת של כל אחת מצוינים משתני הסביבה והשירותים החיצוניים הנדרשים (מפתחות API, נקודות קצה).
• המפתחות הנדרשים נמצאים ב-.env — מעתיקים את .env.example וממלאים אותו (ראו את חומר העזר לתצורה).
• כדי להתנסות ב-Agent-Lab מתוך פרויקט משלך במקום מתוך המאגר, מריצים pip install btech-agent-lab ומרכיבים את האפליקציה עם create_app() — ראו הרחבת הפריימוורק במדריך למפתחים.

מבנה הפרויקט — סיור קצר

• notebooks/ — דוגמאות אינטראקטיביות לסוגי סוכנים, להערכה ולאינטגרציות. מתחילים כאן.
• agent_lab/ — חבילת הפריימוורק:
  • app_factory.py — שורש ההרכבה: create_app().
  • core/ — מקורות תצורה, קונטיינר DI, פתרון extra_deps.
  • domain/ — מודלים, ממשקי repository, חריגות (מודל הדומיין של הישויות).
  • services/ — לוגיקה עסקית ומימושי agent_types/.
  • interface/ — api/ (נתבי HTTP) ו-mcp/ (שרת ה-MCP).
  • infrastructure/ — מתאמים למסד נתונים, לאימות ולמדדים/tracing.
• tests/ — חבילות unit/, integration/, template/ ו-simulation/ (ראו בדיקות וסימולציות).
• doc/ — התיעוד שלפניך.

הבנת השכבות האלה מראה היכן ההתנהגות נמצאת: דוגמאות ב-notebooks, חוזי הליבה ב-core/ וב-domain/, ומתאמים ב-infrastructure/.

מחברות — מסלול הלמידה העיקרי

התקדמות טיפוסית:

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

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

מושגי יסוד

• סוכן — מימוש רשום תחת agent_lab/services/agent_types/ (@discoverable_agent). הרישום פותר אותו בעצלתיים דרך קונטיינר ה-DI ומזריק את ה-extra_deps שהוצהרו.
• כלים — יכולות נפרדות שסוכן יכול לקרוא להן (חיפוש, גלישה, TTS/ASR), הממומשות כמתאמים ב-agent_lab/infrastructure/ או ב-agent_lab/interface/.
• Container — אובייקט ההרכבה של ה-DI (agent_lab/core/container.py); יורשים ממנו כדי להוסיף providers לניסויים שלך.
• Repositories — ממשקי גישה לנתונים ב-agent_lab/domain/repositories/.
• ConfigSource — המקור שממנו מגיעה התצורה; בניסויים משתמשים במקורות ה-YAML, ובסביבת ייצור ב-Vault.

כשרוצים לשנות התנהגות, מחליטים אם השינוי הוא: ניסיוני (במחברת בלבד), ארכיטקטוני (core/domain/services), או ברמת אינטגרציה (מתאם ב-infrastructure). עדיף לבצע שינויים קטנים שניתנים לבדיקה — ולהוסיף או לעדכן מחברת שמדגימה את ההתנהגות החדשה.

הרצת ניסויים ותיעוד תוצאות

המחברות מדפיסות שלבי ביניים; לניסויים יציבים יותר:

• משתמשים ב-seeds דטרמיניסטיים במקומות שבהם האקראיות משנה.

• מתעדים את המדדים הרלוונטיים לשאלה שלך — זמן תגובה, צריכת טוקנים, מספר הקריאות לכלים, ציוני שופט. שכבת הניטור מייצאת הכול כ-OpenTelemetry (ראו ניטור); תשתית הסימולציה רושמת את ציוני השופט ב- Langfuse/LangWatch (ראו בדיקות וסימולציות).

• להרצות חוזרות, מייצאים את תאי המחברת לסקריפטים ומריצים אותם ב-CI או על צומתי חישוב:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• הקובץ docker/app/Dockerfile בונה image של סביבת ריצה בגרסאות נעוצות, להרצה שניתנת לשחזור.

בניית אבות-טיפוס להתנהגויות חדשות

1. הוספת סוג סוכן חדש: יוצרים את המחלקה תחת agent_lab/services/agent_types/, מעטרים אותה ב- @discoverable_agent("your_type"), ומוסיפים מחברת שמחברת אותה דרך קונטיינר ה-DI ומפעילה אותה בתרחיש קטן. ההדרכה המלאה נמצאת ב- בניית תהליכי עבודה אגנטיים.
2. החלפת ספק embeddings: מממשים מתאם תואם תחת agent_lab/infrastructure/ ומאמתים אותו עם מחברת 01.
3. הוספת מאגר אחזור או מסד נתונים וקטורי: מממשים מתודות repository ב- agent_lab/domain/repositories/ ומתאם ב- agent_lab/infrastructure/database/; מאכלסים אותו בעזרת מחברת טעינה קטנה ומדגימים אחזור במחברת שאילתות.

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

בדיקות והערכה

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

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

רשימת תיוג לשחזוריות

• נועצים את הסביבה (uv + pyproject.toml / uv.lock).
• מתעדים seeds וקובצי תצורה (config-dev.yml, config-test.yml).
• שומרים את ה-checkpoint של המחברת ואת כל תוצרי הפלט (CSV/JSON) לצד הניסוי.
• מתעדים את נקודות הקצה של ה-tracing שאליהן ייצאת — ה-traces הם יומן הניסוי שלך.