مرجع الإعدادات

كل مفتاح إعداد ومتغير بيئة، وكيفية اختيار المصدر النشط

كيفية تحميل الإعدادات

الإعدادات عبارة عن قاموس (dictionary) بسيط يحمّله ConfigSource (راجع agent_lab/core/config.py) ويُربط بحاوية حقن التبعيات (DI). يختار create_app() مصدراً عبر default_config_source()، بهذا الترتيب تحديداً — أول تطابق هو المعتمد:

#	الشرط (متغير البيئة المضبوط)	المصدر النشط
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` — Vault عبر رمز ServiceAccount المُسقَط الخاص بالـ pod
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(لا شيء مما سبق)	`VaultConfigSource` — يقرأ `VAULT_URL` / `VAULT_TOKEN`

يمكنك تجاوز هذا الاختيار لكل تطبيق:

app = create_app(config_source=YamlConfigSource("config.yml"))  # explicit

مفاتيح الإعدادات

القاموس الذي يجب أن يُرجعه المصدر النشط. القيم الافتراضية المعروضة مأخوذة من config-dev.yml (بيئة التطوير)؛ ويأتي التطبيق المرجعي مع config-dev.yml وconfig-test.yml وconfig-docker.yml بهذه البنية تحديداً.

المفتاح	الغرض	قيمة مثال
`api_base_url`	عنوان URL الأساسي العام لهذه الواجهة البرمجية (يُستخدم للروابط في الاستجابات)	`http://localhost:8000`
`cdp_url`	نقطة نهاية Chrome بلا واجهة (CDP) لوكلاء الويب (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	تركيب وسيط المصادقة ومسارات `/auth` عندما تكون القيمة `true`	`false`
`auth.url`	عنوان URL الأساسي لـ Keycloak	`https://auth.example.com`
`auth.realm`	اسم الـ realm في Keycloak	`agent-lab`
`auth.client_id`	معرّف عميل OIDC	`agent-lab-api`
`auth.client_secret`	سر عميل OIDC	`…`
`broker.url`	عنوان URL لـ Redis لتحديثات الحالة عبر النشر/الاشتراك (pub/sub) في العمليات الطويلة	`redis://localhost:6379/0`
`db.url`	PostgreSQL — البيانات العلائقية	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL — قاعدة بيانات التضمينات (embeddings) عبر pgvector	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL — قاعدة بيانات نقاط الحفظ (checkpoints) في LangGraph (ذاكرة الوكيل)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	عنوان Vault (يُكتب أيضاً مرة أخرى لتتمكن الخدمات من قراءة الأسرار)	`http://localhost:8200`
`vault.token`	رمز Vault	`dev-only-token`
`static.enabled`	تقديم بناء SPA (القيمة `false` عند عدم وجود بناء للواجهة الأمامية)	`false`
`static.directory`	المجلد الذي يحتوي على بناء SPA	`static/frontend/browser`
`static.index_file`	الملف الاحتياطي لـ SPA	`index.html`
`static.mount_path`	نقطة تركيب SPA	`/`

للمفتاح static وضع خاص: تضبطه مصادر YAML صراحةً، بينما يستنتجه مصدر Vault من اصطلاح في الشيفرة — إذ يُفعَّل عند وجود بناء SPA ضمن STATIC_DIR.

حمولة السر في Vault

يقرأ VaultConfigSource سراً واحداً من نوع KV-v2 (المحرّك secret، والمسار app_secrets افتراضياً) ويربطه بالمفاتيح المذكورة أعلاه:

مفتاح السر	يُربط بـ
`api_base_url`	`api_base_url`
`cdp_url`	`cdp_url`
`auth_enabled` → `auth.enabled`	`auth.enabled`
`auth_url` → `auth.url`	`auth.url`
`auth_realm` → `auth.realm`	`auth.realm`
`auth_client_id` → `auth.client_id`	`auth.client_id`
`auth_client_secret` → `auth.client_id`	`auth.client_secret`
`broker_url`	`broker.url`
`db_url`	`db.url`
`db_vectors`	`db.vectors`
`db_checkpoints`	`db.checkpoints`

يتناول الأسرار باستخدام Vault ودليل النشر كيفية تجهيز هذه الحمولة (Docker Compose للتطوير، وKubernetes، وTerraform).

متغيرات البيئة

اختيار مصدر الإعدادات

المتغير	القيمة الافتراضية	الغرض
`DEVELOPING`	(غير مضبوط)	يختار `config-dev.yml` (التصحيح في بيئة التطوير المتكاملة IDE)
`TESTING`	(غير مضبوط)	يختار `config-test.yml` (حزمة الاختبارات)
`DOCKER`	(غير مضبوط)	يختار `config-docker.yml` (Compose)
`VAULT_URL`	(غير مضبوط)	عنوان Vault للمصدر الافتراضي
`VAULT_TOKEN`	(غير مضبوط)	رمز Vault للمصدر الافتراضي
`VAULT_ENGINE_PATH`	`secret`	نقطة تركيب KV-v2
`VAULT_SECRET_PATH`	`app_secrets`	مسار السر
`VAULT_K8S_ROLE`	(غير مضبوط)	دور مصادقة Kubernetes في Vault؛ يفعّل مصدر K8s ويحظى بالأولوية
`STATIC_DIR`	`static/frontend/browser`	مكان البحث عن بناء SPA

قابلية المراقبة

المتغير	القيمة الافتراضية	الغرض
`OTEL_EXPORTER_OTLP_ENDPOINT`	(غير مضبوط — التتبّع متوقف)	عنوان URL الأساسي لمُجمِّع OTLP/HTTP؛ التتبّعات → `/v1/traces`، والمقاييس → `/v1/metrics`، والسجلات → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	اسم المورد في OTel
`SERVICE_VERSION`	`snapshot`	إصدار المورد في OTel
`LANGFUSE_HOST`	(غير مضبوط)	عنوان URL الأساسي لـ Langfuse؛ مع المفتاحين أدناه، يفعّل واجهة Langfuse الخلفية
`LANGFUSE_PUBLIC_KEY`	(غير مضبوط)	مفتاح Langfuse `pk-lf-…`
`LANGFUSE_SECRET_KEY`	(غير مضبوط)	مفتاح Langfuse `sk-lf-…`
`LANGWATCH_ENDPOINT`	(غير مضبوط)	نقطة نهاية LangWatch؛ مع المفتاح أدناه، يفعّل واجهة LangWatch الخلفية
`LANGWATCH_API_KEY`	(غير مضبوط)	مفتاح API لـ LangWatch

إذا كان أي متغير من متغيرات Langfuse مفقوداً، تُعطَّل واجهة Langfuse الخلفية بصمت ويستمر التطبيق في الإقلاع (وينطبق الأمر نفسه على LangWatch). التفاصيل ونقطة التوسعة: قابلية المراقبة.

المصادقة والتكاملات

المتغير	القيمة الافتراضية	الغرض
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(غير مضبوط)	بيانات اعتماد Microsoft Entra ID لـ `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(غير مضبوط)	خدمة التضمينات التي تستخدمها وكلاء الاسترجاع
`OPENAI_API_KEY`	(غير مضبوط)	OpenAI (إدخال الصوت للمذكرات الصوتية؛ والمُحكِّم الافتراضي في المحاكاة)

المحاكاة (لحزمة الاختبارات فقط)

المتغير	القيمة الافتراضية	الغرض
`SIMULATION_LLM_MODEL`	(مطلوب)	وسم النموذج الذي يشغّل الوكلاء قيد الاختبار (مثل `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(مطلوب)	نقطة نهاية متوافقة مع OpenAI تقدّم ذلك النموذج
`SIMULATION_LLM_API_KEY`	`dummy-key`	مفتاح API لنقطة النهاية، إن كان مطلوباً
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	معرّف نموذج litellm الذي يستخدمه أسلوب LLM-as-judge
`SIMULATION_JUDGE_API_BASE`	القيمة الافتراضية للمزوّد	نقطة نهاية مخصّصة متوافقة مع OpenAI للمُحكِّم
`SIMULATION_JUDGE_API_KEY`	القيمة الافتراضية للمزوّد	مفتاح API لنقطة نهاية المُحكِّم المخصّصة

راجع الاختبارات والمحاكاة لمعرفة كيفية استخدام هذه المتغيرات.

مصادر الإعدادات المخصّصة

نفّذ الفئة المجردة ConfigSource ومرّرها إلى create_app(config_source=...) — وهذا مفيد مع AWS Secrets Manager، أو عمليات النشر المعتمدة على متغيرات البيئة فقط، أو لتغليف مصدر آخر:

from agent_lab import ConfigSource, create_app


class MyConfigSource(ConfigSource):
    def load(self) -> dict:
        return {
            "api_base_url": "https://api.example.com",
            "db": {"url": "postgresql://…", "vectors": "…", "checkpoints": "…"},
            "auth": {"enabled": True, "url": "…", "realm": "…", "client_id": "…", "client_secret": "…"},
            "broker": {"url": "redis://…"},
            # … remaining keys as in the table above
        }


app = create_app(config_source=MyConfigSource())

تُصدَّر المصادر المضمّنة (YamlConfigSource وVaultConfigSource وKubernetesVaultConfigSource) وdefault_config_source() جميعها من الحزمة العليا agent_lab.