חומר עזר לתצורה

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

איך התצורה נטענת

התצורה היא מילון פשוט שנטען על ידי 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 הבסיסית הציבורית של ה-API הזה (משמשת לקישורים בתגובות)	`http://localhost:8000`
`cdp_url`	נקודת קצה של Headless Chrome (CDP) עבור סוכני רשת (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	טעינת middleware האימות ונתיבי `/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`	כתובת 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`	הגשת build של SPA (`false` כשאין build של frontend)	`false`
`static.directory`	התיקייה שמכילה את ה-build של ה-SPA	`static/frontend/browser`
`static.index_file`	קובץ ה-fallback של ה-SPA	`index.html`
`static.mount_path`	נקודת העיגון של ה-SPA	`/`

static הוא מקרה מיוחד: מקורות ה-YAML מגדירים אותו במפורש, ואילו מקור Vault גוזר אותו ממוסכמה בקוד — הוא מופעל כשקיים build של SPA תחת STATIC_DIR.

מטען הסוד ב-Vault

VaultConfigSource קורא סוד KV-v2 יחיד (engine 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`

אופן הקצאת המטען הזה (Docker Compose לפיתוח, Kubernetes, Terraform) מוסבר בסודות עם Vault ובמדריך הפריסה.

משתני סביבה

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

משתנה	ברירת מחדל	ייעוד
`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`	(לא מוגדר)	תפקיד האימות של Vault ל-Kubernetes; מפעיל את מקור ה-K8s ומקבל עדיפות
`STATIC_DIR`	`static/frontend/browser`	המיקום שבו מחפשים את ה-build של ה-SPA

ניטור

משתנה	ברירת מחדל	ייעוד
`OTEL_EXPORTER_OTLP_ENDPOINT`	(לא מוגדר — tracing כבוי)	כתובת ה-URL הבסיסית של ה-collector ב-OTLP/HTTP; traces ← `/v1/traces`, metrics ← `/v1/metrics`, logs ← `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	שם המשאב ב-OTel
`SERVICE_VERSION`	`snapshot`	גרסת המשאב ב-OTel
`LANGFUSE_HOST`	(לא מוגדר)	כתובת ה-URL הבסיסית של Langfuse; יחד עם שני המפתחות שלהלן, מפעיל את ה-backend של Langfuse
`LANGFUSE_PUBLIC_KEY`	(לא מוגדר)	מפתח `pk-lf-…` של Langfuse
`LANGFUSE_SECRET_KEY`	(לא מוגדר)	מפתח `sk-lf-…` של Langfuse
`LANGWATCH_ENDPOINT`	(לא מוגדר)	נקודת הקצה של LangWatch; יחד עם המפתח שלהלן, מפעיל את ה-backend של LangWatch
`LANGWATCH_API_KEY`	(לא מוגדר)	מפתח ה-API של LangWatch

אם משתנה כלשהו של Langfuse חסר, ה-backend של Langfuse מושבת בשקט והאפליקציה עדיין עולה (וכך גם עבור LangWatch). פרטים ונקודת ההרחבה: ניטור.

אימות ואינטגרציות

משתנה	ברירת מחדל	ייעוד
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(לא מוגדר)	פרטי התחברות של Microsoft Entra ID עבור `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(לא מוגדר)	שירות ה-embeddings שבו משתמשים סוכני האחזור
`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 לנקודת הקצה המותאמת של השופט

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

מקורות תצורה מותאמים אישית

מממשים את ה-ABC 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 ברמה העליונה.