Aller au contenu principal

Référence de configuration

Tous les paramètres ci-dessous sont des variables d'environnement. Le backend les lit dans backend/.env (backend/.env.example en est le modèle commenté) ; les deux variables du frontend sont lues dans l'environnement du processus du frontend lui-même. Les paramètres du modèle et des clés d'API ont leur propre page, Configuration du LLM.

Paramètres du serveur​

VariableValeur par défautRôle
HOST0.0.0.0Adresse sur laquelle le backend écoute
PORT8000Port sur lequel le backend écoute
RELOADfalseRechargement automatique d'uvicorn pour le développement local. Lue uniquement lorsque le backend est démarré avec python -m backend.main ; la commande de démarrage de l'image Docker n'en dépend en aucun cas
TIMEZONEUTCNom IANA du fuseau horaire local du déploiement. Il détermine où commence un jour calendaire pour les métriques d'exploitation (les compteurs « du jour » et les tranches quotidiennes de la tendance du délai d'exécution). C'est aussi le fuseau dans lequel l'agent de workflow interprète l'exigence horaire d'une tâche lorsqu'elle n'en nomme aucun. Un nom non reconnu se rabat sur UTC au lieu de faire échouer le démarrage : une faute de frappe fausse donc les heures locales sans arrêter l'application
APP_BASE_URL—L'adresse à laquelle les utilisateurs ouvrent ce déploiement dans un navigateur : schéma, hôte et port facultatif, sans chemin, p. ex. https://a2flow.example.com. Les e-mails de notification renvoient vers l'adresse du tenant du destinataire sous celle-ci, l'authentification unique en dérive son URI de redirection, et elle fixe les valeurs par défaut de CORS_ORIGINS et SESSION_COOKIE_SECURE. Toute autre forme empêche le backend de démarrer. Sans elle, les messages partent sans lien de retour et l'authentification unique est indisponible. Chaque tenant peut aussi être ouvert à sa propre adresse sous celle-ci (le nom du tenant, un point, puis l'hôte, p. ex. acme.a2flow.example.com), dès qu'un DNS et un certificat TLS couvrent tous les noms sous l'hôte (*.a2flow.example.com) — voir À l'adresse de votre tenant. Impossible si l'hôte est une adresse IP

Paramètres du frontend​

VariableValeur par défautRôle
BACKEND_BASE_URLhttp://localhost:8000Destination vers laquelle le frontend transmet /api/* lorsqu'aucun proxy inverse ne l'achemine d'abord vers le backend (exécution sans conteneurs), et adresse à laquelle la page de documentation de l'API vérifie la session connectée. Lue une seule fois au démarrage du processus. Dans la pile Docker Compose, il s'agit de l'adresse du backend sur le réseau interne, et non d'une adresse publique
APP_PORT3000Docker Compose uniquement : le port de l'hôte sur lequel l'application est publiée, c'est-à-dire le port du service ingress, qui sert à la fois les écrans et l'API. Sauf si .env définit APP_BASE_URL, la pile transmet comme URL de base http://localhost: suivi de ce port
OPENBAO_PORT8200Docker Compose uniquement, avec --profile openbao : le port de l'hôte sur lequel l'interface d'OpenBao est publiée ; consultez Essayer les secrets Vault avec OpenBao. A2Flow y accède dans tous les cas par le réseau interne

Base de données de l'application​

VariableValeur par défautRôle
DB_URLsqlite:///a2flow.dbURL de la base de données. SQLite (relatif au répertoire de travail) et PostgreSQL sont pris en charge
DB_POOL_SIZE5PostgreSQL uniquement. Nombre de connexions que chacun des deux pools de connexions d'un processus backend garde ouvertes. Au moins 1. Consultez Pooling de connexions pour savoir comment ce nombre se cumule entre les réplicas
DB_MAX_OVERFLOW10PostgreSQL uniquement. Connexions supplémentaires que chaque pool peut ouvrir au-delà de DB_POOL_SIZE sous charge, puis refermer une fois le pic passé. Au moins 0

Le suffixe du pilote asynchrone (sqlite+aiosqlite / postgresql+asyncpg) est ajouté automatiquement ; le schéma simple suffit donc :

DB_URL=postgresql://user:password@localhost:5432/a2flow

Les changements de schéma sont suivis sous forme de migrations Alembic versionnées et appliqués automatiquement au démarrage : redéployer l'application suffit donc à mettre le schéma à jour. Exécuter plusieurs réplicas du backend nécessite PostgreSQL ; consultez Mise à l'échelle horizontale. Le contenu de chaque table est décrit dans Base de données.

Utilisateurs initiaux​

Au démarrage, le backend crée un utilisateur système caché, ainsi que deux comptes réels, chacun créé uniquement au tout premier démarrage qui constate l'absence de l'enregistrement visé :

  • Un utilisateur root initial détenant le rôle Super administrateur (consultez Rôles et autorisations), à l'échelle de la plateforme (tenantId: null). Sa création est ignorée dès qu'il existe au moins un utilisateur réel (non système) ; elle n'a donc lieu qu'au tout premier démarrage.
  • Un tenant Default (slug: default) et, à l'intérieur, un utilisateur admin initial détenant le rôle Administrateur. Le tenant (d'après son slug) et l'utilisateur (d'après son username dans ce tenant) sont vérifiés indépendamment : l'un peut donc être recréé sans dupliquer l'autre.

L'utilisateur système caché est propriétaire des enregistrements d'amorçage (il ne peut pas se connecter et n'apparaît pas dans la liste des utilisateurs).

VariableValeur par défautRôle
ROOT_PASSWORDgénéréeMot de passe de l'utilisateur root initial
ADMIN_PASSWORDgénéréeMot de passe de l'utilisateur admin initial du tenant Default

Si l'une de ces variables n'est pas définie (ou est vide), un mot de passe aléatoire est généré à la place et consigné une seule fois, au niveau WARNING, à la création de l'utilisateur. Il ne peut plus être récupéré une fois cette ligne de journal disparue. Au-delà d'un simple essai en local, définissez explicitement les deux avant le premier démarrage, ou relevez aussitôt les mots de passe générés dans les journaux de démarrage et modifiez-les ensuite. Les noms d'utilisateur sont fixés à root et admin.

Durée de vie des sessions​

VariableValeur par défautRôle
SESSION_IDLE_TIMEOUT_SECONDS28800 (8 heures)Délai d'inactivité glissant. Les requêtes authentifiées actualisent l'heure de dernière activité de la session, au plus une fois toutes les 5 minutes (ou selon un intervalle égal à la moitié de cette valeur, s'il est plus court) ; une session peut donc se terminer jusqu'à cette durée plus tôt. Une session inactive plus longtemps que ce délai est rejetée et supprimée
SESSION_COOKIE_SECUREtrue si APP_BASE_URL commence par https://, sinon falseMarque les cookies de session et CSRF comme Secure (HTTPS uniquement). Ne la définissez que pour remplacer cette valeur par défaut

Les cookies eux-mêmes sont des cookies de session (sans Max-Age ni Expires) ; ils sont donc aussi effacés à la fermeture du navigateur. Le navigateur atteint le backend sur la même origine que le frontend (/api/* y est acheminé selon le chemin, soit par le proxy inverse, soit par le frontend lui-même) : les cookies sont donc de première partie et SameSite=Lax s'applique sans difficulté.

CORS​

VariableValeur par défautRôle
CORS_ORIGINSAPP_BASE_URL, ou http://localhost:3000 sans elleListe, séparée par des virgules, des origines autorisées à appeler l'API du backend

Ajoutez chaque origine depuis laquelle le frontend est servi :

CORS_ORIGINS=https://app.example.com,http://localhost:3000

* est rejeté au démarrage : allow_credentials=True est toujours activé, et l'associer à une origine générique n'est pas valide selon la spécification CORS.

Authentification unique​

VariableValeur par défautRôle
OIDC_ALLOWED_PRIVATE_HOSTSvideNoms d'hôte séparés par des virgules, comme keycloak.internal,localhost, que l'URL de l'émetteur de l'authentification unique d'un tenant peut avoir même s'ils se résolvent vers une adresse privée, pour un fournisseur d'identité interne. Tout autre émetteur doit se résoudre vers une adresse publique

L'authentification unique dépend aussi de l'URL de base du déploiement, APP_BASE_URL (voir Paramètres du serveur). Sans elle, l'authentification unique est indisponible et Paramètres administrateur affiche un avertissement à la place de l'URI de redirection. Deux exigences :

  • L'URL de base se limite à l'origine — schéma, hôte et port facultatif, comme https://a2flow.example.com, sans chemin. Le backend refuse de démarrer avec toute autre valeur.
  • Le backend doit voir l'origine publique. Derrière un proxy inverse, faites conserver au proxy l'en-tête Host d'origine lorsqu'il transmet une requête et faites-lui définir X-Forwarded-Proto avec le schéma d'origine, puis faites approuver le proxy par le backend en indiquant son adresse dans FORWARDED_ALLOW_IPS (par défaut, seul 127.0.0.1 est approuvé). Sinon, chaque connexion SSO prend une redirection de plus.

Magasin de compétences d'agent​

VariableValeur par défautRôle
SKILLS_DIRbackend/.skillsRacine du magasin dans lequel les dépôts de compétences d'agent sont clonés superficiellement. Sous docker compose, il s'agit de /var/lib/a2flow/skills, porté par le volume nommé skills
SKILLS_PRUNE_GRACE_SECONDS3600Durée pendant laquelle le répertoire d'une révision est conservé, qu'il soit référencé ou non. Une récupération supprime les révisions auxquelles aucune exécution n'est liée, et ce délai de grâce couvre l'intervalle entre le moment où une exécution lit la révision actuelle et celui où elle insère la ligne qui la nomme
SKILLS_CLONE_TIMEOUT_SECONDS120Limite la durée de chaque requête HTTP d'un clonage. Sans elle, un dépôt distant qui ne répond plus bloque le clonage indéfiniment et laisse la compétence à l'état Clonage

Le magasin contient un répertoire immuable par révision, et une révision n'est plus jamais modifiée une fois publiée ; une récupération ne perturbe donc jamais un agent en train d'en charger une existante :

$SKILLS_DIR/<agent_skill_id>/<commit_sha>/

Il s'agit d'un état durable, et non d'un cache : une exécution reste liée à la révision avec laquelle elle a démarré. Effacer le répertoire empêche donc les exécutions existantes de charger leur compétence (HTTP 409 SKILL_NOT_READY) jusqu'à ce qu'un administrateur récupère à nouveau la compétence, et cette récupération rapporte le head actuel du dépôt, et non la révision figée. Sauvegardez-le (Sauvegarde et restauration) et donnez le même répertoire à chaque réplica du backend (Mise à l'échelle horizontale).

Bases de connaissances​

VariableValeur par défautRôle
KNOWLEDGE_SOURCE_MAX_BYTES20971520 (20 Mio)Taille maximale d'un document importé dans une base de connaissances et d'une page web récupérée pour celle-ci. Un import plus volumineux est refusé dès qu'il dépasse cette limite
KNOWLEDGE_INGEST_CHUNK_CHARS40000Nombre de caractères d'une source que le LLM lit à la fois. Une source plus longue est lue par parties successives. Réduisez cette valeur pour un modèle à petite fenêtre de contexte
KNOWLEDGE_FETCH_TIMEOUT_SECONDS30Durée que peut prendre, par requête, la récupération d'une source de type page web

Les sources et les pages sont stockées dans la base de données, comme les fichiers de session, et ne nécessitent donc aucun volume dédié. La lecture d'une source appelle le LLM configuré pour les agents (Configuration du LLM), plusieurs fois pour un document volumineux.

Fichiers de session​

VariableValeur par défautRôle
SESSION_FILE_MAX_BYTES20971520 (20 Mio)Taille maximale d'un fichier joint à une session du workflow. Un import est refusé dès qu'il dépasse cette limite ; un corps plus volumineux n'est donc jamais conservé en entier
SESSION_FILES_MAX_TOTAL_BYTES209715200 (200 Mio)Taille cumulée de tout ce que contient une session. Les fichiers ne sont supprimés qu'à la suppression de leur exécution ; c'est donc cette valeur qui borne une session de longue durée

Les fichiers de session sont stockés dans la base de données et non sur le disque : ils ne nécessitent ni répertoire dédié, ni volume partagé entre réplicas, ni autre étape de sauvegarde que celle de la base de données (Sauvegarde et restauration). Relever ces limites augmente la part de la base de données qu'une exécution peut occuper, ainsi que la mémoire consommée par un seul import ou téléchargement, car les octets sont lus en entier.

Gestion des secrets​

VariableValeur par défautRôle
SECRET_ENCRYPTION_KEY—Clé Fernet utilisée pour chiffrer les secrets local avant leur stockage
SECRET_KEY_FILE.secret_keyChemin du fichier de clé sur le disque, à côté du fichier de base de données SQLite. Sous docker compose, il s'agit de /var/lib/a2flow/secret-key/.secret_key, porté par le volume nommé secret-key que partagent le backend et le worker d'e-mails

La clé de chiffrement est déterminée à la première utilisation, dans cet ordre :

  1. SECRET_ENCRYPTION_KEY, qui doit être une clé Fernet valide.
  2. Le fichier de clé indiqué par SECRET_KEY_FILE.
  3. À défaut, une clé est générée et enregistrée dans ce fichier, et un WARNING est consigné.

Sauvegardez la clé. Sa perte rend indéchiffrables tous les secrets locaux stockés, et cette même clé protège la clé de signature de la CA d'approbation.

Il n'existe aucune variable d'environnement pour HashiCorp Vault : le Vault propre à un tenant est défini par son administrateur dans Paramètres administrateur, l'adresse du Vault global par un super administrateur dans Paramètres système, et l'identifiant de chaque tenant pour ce Vault sur la page du tenant. L'adresse du Vault propre à un tenant subit les mêmes contrôles SSRF que les autres URL fournies par les utilisateurs et doit donc être publique. L'adresse du Vault global en est exemptée, car seul un super administrateur peut la définir et un Vault se trouve généralement sur une adresse privée.

Outils MCP et approbations​

Chaque appel d'outil MCP doit présenter un certificat X.509 de courte durée émis pour la tâche qui l'effectue, accordé lorsque l'approbation de la tâche l'est, ou lorsque démarre une tâche pour laquelle aucune approbation n'a été demandée. La racine de signature est générée à la première utilisation et stockée chiffrée avec la même clé que les secrets locaux : il n'y a donc rien à configurer ici pour que la fonctionnalité marche.

VariableValeur par défautCe qu'elle borne
MCP_TOOL_CERT_TTL_SECONDS3600Durée de validité du certificat d'une tâche, c'est-à-dire la fenêtre pendant laquelle elle peut appeler ses outils
MCP_TOOL_CERT_SIGNATURE_WINDOW_SECONDS60Tolérance de décalage d'horloge pour la signature de preuve de possession qui accompagne chaque appel relayé
MCP_CA_COMMON_NAME / MCP_CA_VALIDITY_DAYSA2Flow MCP Approval CA / 3650Sujet et durée de vie de la racine générée. Lues uniquement lors de la première génération de la racine ; les modifier ensuite n'a aucun effet sur une racine existante
MCP_REGISTRY_URLhttps://registry.modelcontextprotocol.ioURL de base du registre dans lequel cherche la boîte de dialogue Parcourir le registre
MCP_ELICITATION_TIMEOUT_SECONDS900Durée pendant laquelle un appel d'outil attend que l'initiateur de l'exécution réponde à la confirmation d'un serveur MCP avant que la question n'expire. L'initiateur vient de reprendre la tâche : cette limite ne concerne donc qu'une question laissée sans suite
AGENT_TURN_TIMEOUT_SECONDS3600Durée maximale d'un tour d'agent dans une exécution, attente comprise. Gardez-la bien au-dessus de MCP_ELICITATION_TIMEOUT_SECONDS, car un tour dont l'appel d'outil attend une personne reste en cours

Proxy MCP​

Un serveur MCP enregistré n'est pas du code d'A2Flow : il s'exécute donc à un autre endroit que l'agent et ses secrets. Le déploiement Docker Compose met tout cela en place ; un déploiement qui assemble lui-même ses conteneurs le configure ici.

Si ces variables ne sont pas définies, comme lors d'une simple exécution locale, l'agent atteint lui-même les serveurs MCP, dans son propre processus. C'est pratique pour le développement, mais ce n'est pas souhaitable dans un environnement où n'importe qui peut enregistrer un serveur.

VariableValeur par défautRôle
MCP_PROXY_URLnon définieEmplacement du proxy. C'est sa définition qui fait sortir les serveurs MCP du processus de l'agent
MCP_PROXY_SERVER_NAME / MCP_PROXY_PORTmcp-proxy / 8443Nom par lequel le proxy est atteint et port sur lequel il écoute. Le nom fait partie de son certificat : les deux extrémités doivent donc s'accorder
MCP_PROXY_TLS_DIRun répertoire à côté de l'applicationEmplacement où l'agent publie ce dont le proxy a besoin pour s'identifier. Le proxy lit le même répertoire, en lecture seule
MCP_BACKEND_TLS_DIRun répertoire à côté de l'applicationEmplacement où l'agent conserve sa propre clé. Volontairement distinct du répertoire ci-dessus : rien de ce qui s'exécute dans le proxy ne doit pouvoir la lire
MCP_TRANSPORT_CERT_VALIDITY_DAYS365Durée de vie de ces éléments. Ils sont réémis automatiquement lorsqu'il reste moins de 30 jours et ne demandent donc aucune attention
MCP_SANDBOX_DIRnon définieEmplacement du répertoire personnel de chaque tenant pour les lancements de serveurs en bac à sable : les paquets téléchargés par les serveurs d'un tenant y sont conservés, à raison d'un répertoire par tenant. Si elle est définie, chaque serveur démarré localement s'exécute dans son propre bac à sable ; le proxy refuse de démarrer sans elle. Elle n'est pas définie lors d'une simple exécution locale, où les serveurs démarrent sans bac à sable

LLM​

Le LLM par défaut du système — le modèle sur lequel s'exécutent les agents de tous les tenants, et la clé avec laquelle on l'atteint — se modifie sur l'écran Paramètres système. Ces deux variables permettent aussi de le définir depuis l'environnement, comme les paramètres d'e-mail ci-dessous. La configuration d'un fournisseur est décrite dans Configuration du LLM.

VariableValeur par défautRôle
SYSTEM_DEFAULT_LLM_MODEL—Un nom de modèle Gemini ou, pour tout autre fournisseur, litellm:<fournisseur>/<modèle>. Si ni cette variable ni l'écran n'en définissent un, le modèle par défaut intégré gemini-3.8-flash est utilisé
SYSTEM_DEFAULT_LLM_API_KEY—La clé d'API de ce fournisseur. Stockée chiffrée, jamais écrite dans les journaux et jamais renvoyée par une réponse de l'API

Comme les paramètres d'e-mail ci-dessous, celles-ci sont réappliquées à chaque démarrage :

  • Appliquées au démarrage du backend, dans Paramètres système. Une variable définie écrase ce qu'un admin a enregistré sur l'écran : la modifier puis redémarrer est donc la façon de renouveler la clé. Une variable non définie ou vide laisse son champ tel quel, géré depuis l'écran.
  • Une valeur mal formée est journalisée comme avertissement et ignorée, par exemple un nom de modèle de plus de 200 caractères. Les paramètres d'e-mail sont tout de même appliqués, et l'application démarre.
  • Si elles ne sont pas définies, la variable propre au fournisseur est lue comme avant (GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY ou AWS_BEARER_TOKEN_BEDROCK) tant qu'aucune clé n'est stockée. C'est aussi ainsi que l'on fournit des identifiants qui ne sont pas une clé unique, comme ceux de Vertex AI.

E-mails de notification​

Ce sont les mêmes valeurs que celles modifiées dans l'interface d'administration sous Paramètres système. Elles peuvent être définies depuis l'environnement, de sorte qu'un déploiement puisse embarquer sa configuration de messagerie au lieu d'en faire une étape manuelle.

VariableValeur par défautRôle
SMTP_ENABLEDfalseInterrupteur général de l'envoi d'e-mails. Doit valoir explicitement true ; il n'est jamais déduit de la définition des autres variables
SMTP_HOST / SMTP_PORT— / 587Relais auquel remettre les messages. Un simple nom d'hôte interne convient ici : il est transmis au client SMTP et non récupéré comme une URL
SMTP_SECURITYstarttlsnone, starttls ou ssl
SMTP_USERNAME / SMTP_PASSWORD—Identifiants SMTP AUTH. Le mot de passe n'est jamais stocké que sous forme chiffrée, n'est jamais journalisé et n'est renvoyé par aucune réponse d'API
SMTP_FROM_EMAIL / SMTP_FROM_NAME—Adresse de l'expéditeur, requise dès que l'envoi est activé, et nom d'affichage facultatif qui l'accompagne

Contrairement à tout le reste de cette page, ces valeurs ne sont pas relues à chaque utilisation : elles sont écrites dans l'unique enregistrement de paramètres. Elles obéissent donc à leurs propres règles :

  • Elles sont réappliquées à chaque démarrage, et pas seulement au premier : changer le mot de passe d'un relais revient donc à redéployer.
  • Seules les variables effectivement définies sont écrites : en laisser une non définie préserve la valeur stockée, y compris ce qu'un administrateur a configuré manuellement dans l'interface.
  • Une valeur mal formée est consignée sous forme d'avertissement et entièrement ignorée. Un port incorrect, une adresse non valide ou SMTP_ENABLED=true sans hôte laissent la configuration stockée intacte ; l'application démarre quand même.

Comme l'indicateur d'activation est distinct, l'hôte et les identifiants d'un relais peuvent être préparés lors d'un déploiement, et l'envoi activé lors d'un déploiement ultérieur.

File d'envoi des e-mails​

Voici les réglages de la file qui se vide vers le relais ; consultez La file d'envoi pour son comportement. Aucun n'a besoin d'être défini pour un déploiement normal.

VariableValeur par défautRôle
EMAIL_WORKER_IN_PROCESStrueIndique si le processus d'API exécute aussi le worker qui vide la file, de sorte que uvicorn main:app envoie à lui seul les e-mails. Définissez-la sur false lorsque vous exécutez un processus worker dédié ; consultez Organisation des processus. Laisser les deux actifs est sans danger, mais sans intérêt : un verrou consultatif élit exactement un expéditeur dans tout le déploiement
EMAIL_SEND_RATE_PER_SECOND5.0Messages par seconde remis au relais ; le worker marque une pause de 1 / rate avant chaque envoi. Réduisez cette valeur pour rester sous la limite d'un relais plus strict
EMAIL_QUEUE_BATCH_SIZE / EMAIL_QUEUE_POLL_INTERVAL_SECONDS20 / 5.0Nombre de messages pris en charge par une passe, et durée de sommeil du worker lorsque la file est vide. L'intervalle d'interrogation est le délai d'envoi minimal d'une notification produite pendant que le worker dort
EMAIL_MAX_ATTEMPTS9Nombre de tentatives d'envoi avant qu'un message ne devienne une lettre morte. Le délai entre tentatives passe par 15 s, 30 s, 1 min, 2 min et ainsi de suite, plafonné à une heure : la valeur par défaut permet donc de tenir environ une heure d'indisponibilité du relais. Un échec que le relais signale comme définitif est abandonné dès la première tentative, quelle que soit cette valeur
EMAIL_SENT_RETENTION_DAYS30Durée de conservation des messages envoyés avant que le worker ne les purge. Ils constituent un historique de ce qui est parti, et non un état de la file. Les lettres mortes ne sont jamais purgées

Agent​

VariableValeur par défautRôle
EXECUTION_MAX_PARALLEL_SESSIONS4Nombre maximal de sessions dans lesquelles une exécution travaille en même temps : sa session principale, plus les sessions de branche créées lorsque son graphe de tâches se ramifie. Une fois la limite atteinte, une tâche prête attend sa session au lieu d'en créer une autre. 1 désactive la création de sessions de branche. Au moins 1
ROLE_DESCRIPTIONUne description générique d'assistantTexte de rôle autour duquel est construit le prompt système de l'agent, avec les règles du workflow et le schéma d'interface
SESSION_RUNNER_CONCURRENCY4Nombre de tours qu'un réplica exécute en même temps pour le compte d'une exécution : lancements et reprises après la décision d'une approbation. Chacun est une conversation active avec le modèle : cette valeur borne donc les appels au modèle d'un réplica pour les exécutions que personne ne suit. Au moins 1