מדריך למפתחים

בנייה, הרחבה ושחרור של אפליקציות על גבי הפריימוורק Agent-Lab

שתי דרכים לפתח

Agent-Lab הוא פריימוורק שצורכים כספרייה, והוא גם מאגר שאפשר לעבוד בתוכו ישירות. שתי האפשרויות נתמכות:

כספרייה (מומלץ למוצרים). מוסיפים את btech-agent-lab לפרויקט שלך, מגדירים סוכנים על ידי הרחבת מחלקות הבסיס ומרכיבים את האפליקציה עם create_app(). מרחיבים את הפריימוורק דרך ה-API הציבורי שלו — ירושה, דקורטורים ותצורה — ולעולם לא עורכים את קוד הפריימוורק. כדאי להתחיל עם ההדרכה או עם ההתחלה המהירה, ואז לקרוא את הרחבת הפריימוורק. כדי לדלג על קוד ה-boilerplate, אפשר ליצור שלד של פרויקט צרכן מוכן עם uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (ראו cookiecutter/README.md).
בתוך המאגר (לתורמים ולמימוש לדוגמה). משכפלים את המאגר ומוסיפים סוכנים תחת agent_lab/services/agent_types/, מריצים את אפליקציית הדוגמה המצורפת ומשתמשים במחברות ובבדיקות האינטגרציה. כך מפותחים הסוכנים המובנים. ראו בניית תהליכי עבודה אגנטיים.

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

התקנה והגדרה

התקנה

Agent-Lab מיועד ל-Python 3.12+ ומשתמש ב-uv לניהול תלויות.

שימוש ב-Agent-Lab כספרייה — מתקינים אותו בפרויקט שלך:

pip install btech-agent-lab
# or
uv add btech-agent-lab

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

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

יש לוודא ש-Docker או סביבת הרצה אחרת לקונטיינרים מותקנת ופועלת — בדיקות האינטגרציה משתמשות בה (באמצעות testcontainers), וקובצי Docker Compose המצורפים מספקים את התלויות של האפליקציה.

העתקת קובץ הסביבה לדוגמה

cp .env.example .env

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

מימוש לדוגמה

המאגר כולל אפליקציית דוגמה מלאה (agent_lab.main) שרושמת את כל הסוכנים המובנים — RAG, אוטומציה של דפדפן, תזכירים קוליים, ראייה ממוחשבת ומפקחים מרובי-סוכנים. היא גם מוצר שניתן לפרוס וגם הדוגמה הקנונית לאופן הצריכה של הפריימוורק: היא לא יותר מקריאה ל-create_app() מעל חבילות הסוכנים המובנים.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

אפשר להשתמש בה כדוגמה חיה בזמן בניית האפליקציה שלך, וכדרך המהירה ביותר לנסות את Agent-Lab מקצה לקצה. הקמת התשתית שלה (שלושת מסדי הנתונים של PostgreSQL, Redis, Keycloak, Vault) בסביבת פיתוח או ייצור מוסברת במדריך הפריסה. הסעיף הבא מראה איך להריץ אותה מקומית.

הרצת האפליקציה

הפעלת האפליקציה עם Uvicorn

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

uvicorn agent_lab.main:app --reload

התיעוד האינטראקטיבי של OpenAPI זמין בכתובת http://localhost:8000/docs.

כשצורכים את Agent-Lab כספרייה, מריצים את האפליקציה שלך באותה דרך — מפנים את uvicorn למודול שקורא ל-create_app():

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

הפעלת האפליקציה עם Docker Compose

שני קובצי Docker Compose מוגדרים מראש מריצים את אפליקציית הדוגמה יחד עם סביבת ניטור:

compose-grafana.yml: האפליקציה יחד עם Grafana, Prometheus, Tempo ו-Loki.
compose-opensearch.yml: האפליקציה יחד עם OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

לאחר שהאפליקציה עולה, ה-API זמין בכתובת http://localhost:18000/docs. דשבורדים לניטור:

Grafana: http://localhost:3000 (פרטי התחברות ברירת מחדל: admin/admin). ראו את הדוגמה של Grafana.
OpenSearch Dashboards: http://localhost:5601. ראו את הדוגמה של OpenSearch.

שיטות עבודה בפיתוח

הזרקת תלויות

האפליקציה משתמשת ב-Dependency Injector להזרקת תלויות, מה שמשמר הפרדה בין תחומי אחריות ומקל על כתיבת בדיקות.

הקונטיינר מוגדר ב-agent_lab/core/container.py. כשצורכים את Agent-Lab כספרייה, יורשים מ-Container כדי להוסיף providers משלך ומעבירים את המופע ל-create_app(container=...). כשעובדים בתוך המאגר, רושמים שירותי פריימוורק נוספים ישירות על הקונטיינר.

תצורת האפליקציה

התצורה נטענת דרך ConfigSource (ראו agent_lab/core/config.py) ומקושרת לקונטיינר ה-DI. הפריימוורק כולל שלושה מקורות YAML לפיתוח ולבדיקות, שנבחרים אוטומטית לפי משתנה סביבה:

config-dev.yml: סביבת פיתוח, מופעלת כש-DEVELOPING מוגדר — מיועדת לניפוי באגים ב-IDE.
config-test.yml: סביבת בדיקות, מופעלת כש-TESTING מוגדר — משמשת את הגדרת בדיקות האינטגרציה.
config-docker.yml: סביבת Docker Compose, מופעלת כש-DOCKER מוגדר.

קבצים אלה מגדירים הגדרות כמו חיבורים למסדי נתונים ואימות, והם מיועדים לפיתוח ולבדיקות בלבד. בסביבת ייצור משתמשים ב-Vault דרך VaultConfigSource (ברירת המחדל כשאף דגל סביבה אינו מוגדר). כדי לספק תצורה ממקור אחר, מממשים ConfigSource משלך ומעבירים אותו ל-create_app(config_source=...). כל מפתח תצורה וכל משתנה סביבה מתועדים בחומר העזר לתצורה.

מודל הדומיין של הישויות

ראו את מודל הדומיין של הישויות לתיאור מודל הנתונים — הישויות והקשרים ביניהן שבהם משתמשים לאורך האפליקציה.

לוגים וניטור

האפליקציה משתמשת ב-OpenTelemetry לרישום לוגים ולניטור; ההגדרה נמצאת ב-agent_lab/infrastructure/metrics/tracer.py. קריאות FastAPI, HTTPX, LangChain, SQLAlchemy ו-OpenAI מנוטרות מהקופסה, עם backends נשלפים עבור Langfuse ו-LangWatch. לפרטים, ראו את מדריך הניטור.

בדיקות

הפרויקט משתמש ב-pytest עם דגש על בדיקות אינטגרציה (סף כיסוי: 90%), בתמיכת Testcontainers, כך שהבדיקות רצות מול שירותים אמיתיים בקונטיינרים של Docker. חבילת סימולציות נפרדת מעריכה את התנהגות הסוכנים מקצה לקצה בשיטת LLM-as-judge.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

ההרצה הראשונה עשויה להימשך כמה דקות, משום שהיא מורידה images של Docker ומודלי embedding. לתמונה המלאה, ראו את מדריך הבדיקות.

אתחול pre-commit

אם מתכננים לתרום לבסיס הקוד או לבנות סוכנים חדשים על גבי Agent-Lab, יש להתקין את ה-hooks של pre-commit:

pre-commit install

כך מובטח שהקוד עומד בתקני הקוד של הפרויקט לפני כל commit.

בניית תהליכי עבודה אגנטיים

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

הגדרת מימוש חדש של סוכן

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

מחלקות הבסיס של Agent-Lab

מחלקה שמרחיבה את WorkflowAgentBase מגדירה:

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

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

פרמטרי אתחול של סוכן

אפשר ליצור ולשפר דרך ה-REST API כמה סוכנים המבוססים על אותו מימוש.

רישום הסוכן עם `@discoverable_agent`

מעטרים את תת-המחלקה של AgentBase ב-@discoverable_agent("<agent_type>"). הדקורטור היחיד הזה הוא כל הרישום שסוכן צריך — הוא הופך את הסוכן ל:

ניתן לגילוי על ידי רישום הסוכנים (agent_lab/services/agent_types/registry.py),
ניתן לפתרון דרך קונטיינר ה-DI, שיוצר ממנו מופע בעצלתיים ומזריק את כל ה-extra_deps שהוצהרו,
תקף ב-API, משום שסכמת יצירת הסוכן מאמתת את agent_type מול הרישום באופן דינמי.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

הערה (מיגרציה): גרסאות קודמות דרשו לחבר ידנית כל סוכן ל-container.py, להוסיף אותו ל-registry.py ולהרחיב את סכמת Pydantic ב-agents/schema.py. השלבים האלה מיושנים — @discoverable_agent מטפל בכולם. כל extra_deps שמוצהר נפתר לפי שם מתוך הקונטיינר (שייתכן שעבר ירושה) בזמן יצירת המופע.

אם סוכן זקוק לרכיבים משתפי פעולה מעבר ל-AgentUtils, חושפים אותם כ-providers על הקונטיינר (יורשים מ-Container כשצורכים את הספרייה) ומציינים את שמותיהם ב-extra_deps.

הפיכת הסוכן לניתן לגילוי

הפריימוורק מייבא רק מודולי סוכנים שסופרו לו עליהם, כדי שהדקורטור יופעל:

בתוך המאגר: ממקמים את הסוכן תחת agent_lab/services/agent_types/ — אפליקציית הדוגמה סורקת את החבילה הזו כחלק מ-DEFAULT_SCAN_PACKAGES (create_app()).
כספרייה: מעבירים את החבילה שלך ל- create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — רשימה מפורשת מחליפה את ברירות המחדל (וכך גם מחריגים יכולות מובנות) — או מפרסמים אותה מתוך חבילה מותקנת דרך קבוצת ה-entry point agent_lab.agents, כך שהצרכנים יקלטו אותה אוטומטית:
```
# pyproject.toml of the package that ships the agents
[project.entry-points."agent_lab.agents"]
my_agents = "my_agents"
```

ניסויים במימוש הסוכן

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

ממשק REST API לסוכנים

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

בדיקת הסוכן

בדיקות אינטגרציה (tests/integration/) מאמתות את הסוכן מול תשתית אמיתית באמצעות pytest ו-testcontainers.
סימולציות (tests/simulation/) מעריכות את ההתנהגות מקצה לקצה בשיטת LLM-as-judge. ראו את מדריך הבדיקות.

שרת MCP

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

הרחבת הפריימוורק

כשצורכים את Agent-Lab כספרייה, מעצבים את האפליקציה כולה דרך create_app() וה-API הציבורי שמיוצא מחבילת agent_lab ברמה העליונה — ולעולם לא על ידי עריכת קוד הפריימוורק:

נקודת הרחבה	איך
סוכנים	יורשים ממחלקת בסיס, מעטרים ב-`@discoverable_agent` ורושמים דרך `scan_packages=[...]` או דרך ה-entry point `agent_lab.agents`.
שירותים ותלויות	יורשים מ-`Container`, מוסיפים providers ומעבירים אותו כ-`create_app(container=...)`.
תצורה	מממשים `ConfigSource` (או משתמשים ב-`YamlConfigSource` / `VaultConfigSource`) ומעבירים `create_app(config_source=...)`.
נתיבי HTTP נוספים	בונים `APIRouter`, עוטפים אותו ב-`RouterMount` (עם מדיניות האימות שלו) ומעבירים `create_app(extra_routers=[...])`.
כלים ופרומפטים של MCP	מעטרים ב-`@discoverable_mcp_tool` / `@discoverable_mcp_prompt` / `@discoverable_mcp_registrar`, רושמים דרך אותו מעבר של `scan_packages` / entry point כמו הסוכנים, ומוסיפים מקטעי הנחיות MCP דרך `create_app(mcp_instructions=[...])`.
backends ל-tracing	יורשים מ-`TracingBackend` ורושמים אותו על ה-`Container` שלך כדי לייצא spans לפלטפורמה משלך.

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

כל מה שמופיע למעלה מיוצא מ-agent_lab (ראו agent_lab/__init__.py); הרשימה המלאה של מפתחות התצורה שבהם משתמשות האפשרויות האלה נמצאת בחומר העזר לתצורה.

תרומה לפרויקט

תמיכת הקהילה מוערכת מאוד. אם נתקלים בבעיות או שיש הצעות לשיפור, אפשר לדווח עליהן על ידי פתיחת issue בעמוד GitHub Issues שלנו.

כדי לתרום לפרויקט, יש לבצע את השלבים הבאים:

יוצרים fork של המאגר.
יוצרים branch חדש עבור הפיצ'ר או תיקון הבאג.
מפעילים את ה-hooks של pre-commit באמצעות הרצת pre-commit install, מבצעים את השינויים ועושים להם commit עם הודעות ברורות ותמציתיות.
מוודאים שהשינויים עוברים את ה-hooks של pre-commit ואת סף הכיסוי של 90% (make test).
דוחפים את השינויים למאגר ה-fork שלך.
יוצרים Pull Request (PR) ל-branch main של המאגר המקורי.

נבדוק את ה-PR ונמסור משוב. תודה על התרומה והתמיכה!

פריסה לסביבת ייצור

ראו את מדריך הפריסה לפריסת אפליקציית הדוגמה בסביבת ייצור באמצעות ה-Helm charts והסקריפטים של Terraform המצורפים.