دليل المطوّر

ابنِ التطبيقات ووسّعها وانشرها على إطار عمل Agent-Lab

طريقتان للتطوير

Agent-Lab إطار عمل تستخدمه بوصفه مكتبة، وهو أيضاً مستودع يمكنك العمل فيه مباشرة. والطريقتان مدعومتان:

بوصفه مكتبة (موصى به للمنتجات). أضف btech-agent-lab إلى مشروعك الخاص، وعرّف الوكلاء بتوسيع الفئات الأساسية، وجمّع التطبيق باستخدام create_app(). توسّع الإطار عبر واجهته البرمجية العامة — الفئات الفرعية، والمُزخرِفات، والإعدادات — دون أن تعدّل شيفرة الإطار مطلقاً. ابدأ بـ الدرس التعليمي أو البدء السريع، ثم اقرأ توسيع الإطار. ولتجاوز الشيفرة المتكررة، أنشئ مشروعاً مستهلكاً جاهزاً باستخدام 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 لمزوّدي الذكاء الاصطناعي ونقاط النهاية التي تستخدمها محاكاة الوكلاء. وكل متغير موثّق في مرجع الإعدادات.

التنفيذ المرجعي

يأتي المستودع مع تطبيق مرجعي كامل (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

بعد بدء تشغيل التطبيق، تتوفر الواجهة البرمجية على 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 لإضافة مزوّداتك الخاصة ومرّر النسخة إلى 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 مباشرة دون إعداد إضافي، مع واجهات خلفية قابلة للتوصيل لـ 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)

قد يستغرق التنفيذ الأول عدة دقائق لأنه ينزّل صور Docker ونماذج التضمين. راجع دليل الاختبار للصورة الكاملة.

تهيئة pre-commit

إذا كنت تخطط للمساهمة في الشيفرة أو بناء وكلاء جدد فوق Agent-Lab، فثبّت خطافات pre-commit:

pre-commit install

يضمن ذلك التزام شيفرتك بمعايير البرمجة الخاصة بالمشروع قبل الإيداع (commit).

بناء سير العمل الوكيلي

بُني Agent-Lab على LangGraph، الذي يوفّر طريقة فعّالة لبناء سير عمل وكيلي باستخدام نماذج LLM. وبناء أحدها عملية مباشرة بفضل البنية المعيارية والفئات الأساسية للوكلاء.

عرّف تنفيذاً جديداً لوكيل

الوكيل (Agent) مفهوم أساسي في Agent-Lab، ويمثّل كياناً مستقلاً يمكنه تنفيذ المهام، واتخاذ القرارات، والتفاعل مع وكلاء آخرين أو أنظمة خارجية. والوكيل تنفيذ فعلي لإحدى الفئات الأساسية:

الفئات الأساسية في Agent-Lab

تعرّف الفئة التي توسّع WorkflowAgentBase ما يلي:

سير عمل يمثّل سلوك الوكيل — المهام، واتخاذ القرارات، والتفاعلات مع وكلاء آخرين أو أنظمة خارجية.
معاملات التهيئة مثل الموجّهات (قوالب Jinja2) والإعدادات الأخرى التي تخصّص سلوك الوكيل (مجموعات مخزن المتّجهات، ودرجة الحرارة، وما إلى ذلك).

فيما يلي مثال على معاملات تهيئة مخزّنة لوكيل يجري النسخ الصوتي والتحليل، بعد إنشاء الوكيل وتخزينه في قاعدة البيانات:

معاملات تهيئة الوكيل

يمكن إنشاء وكلاء متعددين يعتمدون على التنفيذ نفسه وتحسينهم عبر REST API.

سجّل الوكيل باستخدام `@discoverable_agent`

زخرف الفئة الفرعية من AgentBase باستخدام @discoverable_agent("<agent_type>"). فهذا المُزخرِف الوحيد هو كل ما يحتاجه الوكيل للتسجيل — إذ يجعل الوكيل:

قابلاً للاكتشاف من سجل الوكلاء (agent_lab/services/agent_types/registry.py)،
قابلاً للحل عبر حاوية DI، التي تنشئه بشكل كسول وتحقن أي extra_deps مُعلَنة،
صالحاً في الواجهة البرمجية، لأن مخطط إنشاء الوكيل يتحقق من 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، فاعرضهم بوصفهم مزوّدات في الحاوية (أنشئ فئة فرعية من Container عند استخدام المكتبة) واذكر أسماءهم في extra_deps.

اجعل الوكيل قابلاً للاكتشاف

لا يستورد الإطار إلا وحدات الوكلاء التي يُبلَّغ بها، ليُفعَّل المُزخرِف:

داخل المستودع: ضع الوكيل ضمن agent_lab/services/agent_types/ — إذ يفحص التطبيق المرجعي تلك الحزمة ضمن DEFAULT_SCAN_PACKAGES (create_app()).
بوصفه مكتبة: مرّر حزمتك إلى create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — فالقائمة الصريحة تحل محل القيم الافتراضية (وهذه أيضاً طريقة استبعاد القدرات المدمجة) — أو انشرها من حزمة مثبّتة عبر مجموعة نقاط الدخول 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() والواجهة البرمجية العامة المُصدَّرة من الحزمة العليا agent_lab — ولا تعدّل شيفرة الإطار أبداً:

نقطة التوسعة	الطريقة
الوكلاء	أنشئ فئة فرعية من فئة أساسية، وزخرفها بـ `@discoverable_agent`، وسجّلها عبر `scan_packages=[...]` أو نقطة الدخول `agent_lab.agents`.
الخدمات والتبعيات	أنشئ فئة فرعية من `Container`، وأضف المزوّدات، ومرّرها بصيغة `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` / نقطة الدخول نفسها المستخدمة للوكلاء، وأضف أجزاء تعليمات MCP عبر `create_app(mcp_instructions=[...])`.
واجهات التتبّع الخلفية	أنشئ فئة فرعية من `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) من المستودع.
أنشئ فرعاً جديداً للميزة أو إصلاح الخطأ.
فعّل خطافات pre-commit بتشغيل pre-commit install، وأجرِ تغييراتك، وأودعها برسائل واضحة وموجزة.
تأكّد من أن تغييراتك تجتاز خطافات pre-commit وحد التغطية البالغ 90% (make test).
ادفع تغييراتك إلى مستودعك المتفرع.
أنشئ طلب سحب (Pull Request) إلى الفرع main في المستودع الأصلي.

سنراجع طلب السحب الخاص بك ونقدّم ملاحظاتنا. شكراً لمساهماتكم ودعمكم!

النشر في بيئة الإنتاج

راجع دليل النشر لنشر التطبيق المرجعي في بيئة الإنتاج باستخدام مخططات Helm وسكربتات Terraform المضمّنة.