Aller au contenu principal
DocumentCommencerConcepts de base

Concepts de base

Workflow, étape, agent, module, exécution, informations d'identification - que signifient exactement ces mots dans Braidrun.

Toutes les fonctions de Braidrun - canevas, YAML, planification, approbation, surveillance - tournent autour d'un ensemble très restreint de concepts de base. Cette page met ces concepts en image afin que vous « connaissiez les coordonnées quel que soit l'article que vous lisez plus tard ».

modèle mental dans une phrase

unWorkflowsest un DAG, composé de plusieursétapesComposé ; L'étape peut être un appel LLM (en utilisantAgent ), un bloc de code ou un sous-workflow (référençant un modules ) ; un contrôle d'approbation peut en outre être ajouté à n'importe quelle étape. Une fois déclenché, un Workflow produit une Déroulé de l'exécution, sera référencé lors de l'exécutionInformations d'identificationAccédez à des systèmes externes.

Flux de travail · Flux de travail

Workflow est l'objet de niveau supérieur de cette plateforme. Vous pouvez le considérer comme « un diagramme de processus métier versionnable », composé de :

  • Un document YAML (définissant la structure)
  • Un ensemble de métadonnées (déclencheurs, préréglages de paramètres, autorisations, balises)
  • Plusieurs enregistrements d'exécution passés (pour l'audit et le débogage)

. Un même workflow est présenté sous forme de canevas DAG dans l'interface Web ; le canevas et le YAML sont deux vues d'une même définition. Le diff dans Git est un diff YAML normal, et non un dump JSON confus.

Un workflow peut être déclenché de cinq manières :

  1. Manuel — Cliquez sur "Exécuter" dans l'éditeur ou lancez des lots à partir de la liste.
  2. Planifié — Expression cron, intervalle fixe, planification unique, ou déclenchement en chaîne « N secondes après l'achèvement du workflow en amont ».
  3. Webhook — Déclenchement par requête POST d'un système externe, avec authentification par API Key (compatible avec la signature HMAC).
  4. API — Lancez une exécution depuis votre propre système à l'aide de l'endpoint de déclenchement de l'API v1.
  5. Intégré par le workflow parent — Appelé comme boîte noire par un autre workflow via l'étape sub_workflow.

Étape · Étape

L'étape est la plus petite unité d'exécution du flux de travail. Chaque étape ne doit et ne peut sélectionner qu'un seul "mode principal" :

  • single — Un seul agent effectue une description de tâche. La primitive d'appel LLM la plus légère.
  • group_chat — Plusieurs agents discutent à tour de rôle et se réfèrent au contexte de chacun. Convient pour le brainstorming et l'examen critique.
  • agent_based — Un agent orchestrateur lit la tâche et distribue dynamiquement les sous-tâches à l'agent travailleur.
  • code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
  • classifier — Le LLM attribue une étiquette de catégorie à l'entrée ; le résultat est écrit dans la variable désignée par output_variable, pour un branchement par condition dans les step suivantes.
  • state_machine — États multiples + conditions de transition d’état. Convient à plusieurs itérations ou flux de travail contenant de petits processus.
  • sub_workflow — Appelez un autre flux de travail comme une boîte noire, avec vérification du contrat, détection des boucles et isolation des variables.
  • workflow_output_read — Lit la sortie publiée (publish_outputs) par l'exécution d'un autre workflow et l'enregistre dans une variable locale.

En plus du mode principal, presque toutes les étapes peuvent superposer les champs d'amélioration courants suivants :

  • depends_on / condition — Dépendances antérieures + condition de saut (condition prend en charge && et || au niveau supérieur)
  • manual_approval — Contrôle d'approbation humaine : met l'exécution en pause et la poursuit après approbation
  • parallel / timeout_seconds — Configuration de l'exécution parallèle / délai d'expiration de l'étape
  • retry — Stratégie de nouvelle tentative d'attente pour les erreurs passagères
  • repeat_until / iterate_over — Boucle jusqu'à ce qu'une condition soit satisfaite / exécution élément par élément sur une collection
  • extract / aggregate — Sélectionnez les champs de la sortie/fusionnez plusieurs entrées
  • publish_outputs — Publie l'artefact d'une étape en tant que sortie nommée, consommable par workflow_output_read
  • idempotent — Déclare « mêmes entrées → mêmes sorties, sans effet de bord » ; lors de la reprise automatique après un redémarrage du service, il sert à déterminer si l'on peut reprendre depuis l'étape interrompue
  • on_success / on_failure — Actions complémentaires après succès/échec (envoi de notifications, rédaction d'audits, etc.)

Agent·Agent

Un Agent encapsule « une session LLM + les outils qu'il peut utiliser + sa stratégie d'exécution ». Dans Braidrun, vous n'écrivez presque jamais directement un system prompt à la main — il suffit de choisir l'un des 19 presets intégrés (universal / coder / researcher / data_analyst / web_scraper / writer, etc.) et d'en overrides quelques champs au besoin.

yaml
agents:
  planner:
    preset: universal              # 选一个基线模板
  analyst:
    preset: data_analyst
    overrides:                     # 按需覆盖
      llm_config:
        temperature: 0.2
      tool_set: [file_system, csv, database]

Un agent peut être référencé par plusieurs étapes ; chaque exécution d'étape ouvrira une nouvelle instance de session (pas de mémoire de chaîne). Voir les détails Explication détaillée de la configuration de l'agent.

Module · Module

Un module est un "workflow qui déclare WorkflowModuleContract" - c'est-à-dire un workflow réutilisable qui expose le contrat d'entrées/sorties et peut être appelé par d'autres workflows via sub_workflow.

La valeur apportée par le module :

  • Vérification du contrat dactylographié + au niveau du champ, il n'y aura pas de « tous les problèmes en aval si le champ est modifié »
  • Exécution en boîte noire - l'appelant ne peut pas voir les étapes internes et la logique interne peut évoluer indépendamment
  • Détection de double boucle au moment de l'exécution + temps de relâchement pour éviter les "références A B et B références A"
  • Promouvoir en un clic (extraire une étape dans un module)/Rétrograder (restaurer le module en une étape en ligne) dans la bibliothèque de modules

La bibliothèque de modules est livrée avec plus de 120 modules intégrés (connexion à la plateforme, calcul de fenêtre temporelle, récupération de rapports ASA, rapports Excel, remise Slack, etc.) ; pour plus de détails, voir Bibliothèque de modules intégrée;Créez votre propre module voir Modularisation et réutilisation.

Exécution·Exécution

L'exécution est une instance en cours d'exécution spécifique d'un flux de travail. Son cycle de vie est une machine à états :

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

Face à un contrôle d'approbation, l'exécution s'arrête à l'état d'attente d'approbation et poursuit la machine à états une fois la décision rendue.

Chaque exécution a :

  • Source de déclenchement (manuel/planification/webhook/api/sub_workflow)
  • Heure de début, heure de fin, temps total, temps par étape
  • Tous les événements d'entrée/sortie/intermédiaires d'étape (flux d'événements SSE)
  • Jeton/coût accumulé
  • liste des artefacts générés

En cas de redémarrage anormal du service, une execution en cours est marquée INTERRUPTED. Une fois recovery.autoResumeOnRestart activé, la reprise automatique depuis l'étape interrompue est possible ; pour plus de détails, voir Reprise automatique après redémarrage du service.

Informations d'identification · Informations d'identification

Les informations d'identification sont le stockage unifié d'informations sensibles telles que « Clé API, Webhook Secret, OAuth Token ». Toutes les valeurs sont cryptées AES-256-GCM et stockées côté serveur. Une fois écrits, ils ne peuvent pas être relus (ils peuvent uniquement être écrasés ou supprimés).

Les liens d'analyse sont recherchés dans l'ordre et le premier accès prend effet :

  1. Espace de noms personnel de l'utilisateur actuel
  2. L'espace de noms de l'équipe de l'utilisateur
  3. Espace de noms système (clé publique configurée par l'administrateur)

Les étapes de l'agent/code sont analysées à la demande au moment de l'exécution, jamais écrites dans les journaux, n'apparaissent pas dans les exportations YAML et ne sont pas visibles par les autres étapes de l'appelant.

Compétence / Outil · Compétences et outils

"Mains" de l'agent - fonctions qui peuvent être appelées lors de l'inférence LLM. Divisé en trois catégories :

  • Ensemble d'outils intégré — file_system / shell / web / browser / code_execution Attendez, il sera lié par défaut au preset.
  • MCP Outils d'extension — Tout outil exposé par le serveur MCP peut être enregistré.
  • Marché des skills — Sélectionnez une compétence publiée dans le « Skill Market » et activez-la en un clic.

Variables et expressions

Toutes les valeurs dynamiques sont passées entre doubles accolades {{ ... }} y font référence. Trois syntaxes :

  • {{var:name}} — Variable de premier niveau du workflow
  • {{steps.plan.output}} — Sortie d'une étape en amont (forme pleinement qualifiée recommandée)
  • {{plan}} — Forme nue : recherche d'abord la sortie par nom d'étape, puis la valeur par nom de variable

Le résultat de classification d'un classifier est écrit dans la variable désignée par son output_variable, et les étapes en aval utilisent condition pour déterminer quelle branche suivre. Les identifiants ne passent pas par les variables de modèle : ils sont résolus par provider depuis le centre d'identifiants et injectés à l'exécution ; les variables reçues par les étapes code sont injectées sous forme de variables d'environnement WF_VAR_*.

Pour la syntaxe complète (JSONPath, filtre, expressions de condition), voir Variables et expressions.

Rassemblez-les dans une image

text
       ┌──────────── Workflow ────────────┐
       │                                  │
Trigger→─────►  Step 1 (single, agent=A) ◄─── Credential (解析给 A)
       │         │                        │
       │         ▼                        │
       │      Step 2 (classifier)         │
       │         │                        │
       │   ┌─────┴─────┐                  │
       │   ▼           ▼                  │
       │ Step 3       Step 4 (sub_workflow ──► Module)
       │ (code)       │                   │
       │              ▼                   │
       │      manual_approval 门控        │
       │              │                   │
       └──────────────┴──► Execution (记录状态 / 产物 / token / cost)

Vous savez déjà où chercher