Conceptos centrales

Todas las funciones de Braidrun (lienzo, YAML, programación, aprobación, seguimiento) giran en torno a un conjunto muy restringido de conceptos básicos. Esta página resume estos conceptos para que "conozca las coordenadas sin importar qué artículo lea más tarde".

Flujo de trabajo · Flujo de trabajo

El flujo de trabajo es el objeto de nivel superior de esta plataforma. Puede considerarlo como "un diagrama de proceso de negocio versionable", que consta de:

• Un documento YAML (que define la estructura)
• A set of metadata (triggers, parameter presets, permissions, tags)
• Varios registros de ejecución anteriores (para auditoría y depuración)

lo componen. En la Web UI, un mismo workflow se representa como un lienzo DAG; el lienzo y el YAML son dos vistas de la misma definición. El diff en Git es un diff de YAML normal, no un volcado JSON caótico.

Un workflow se puede disparar de cinco maneras:

1. manuales — Haga clic en "Ejecutar" en el editor o inicie lotes desde la lista.
2. Programado — Expresión cron, intervalo fijo, disparo único programado, o disparo encadenado del tipo «N segundos después de que se complete el workflow upstream».
3. gancho web — Disparo por POST de un sistema externo, con autenticación por API Key (compatible con firma HMAC).
4. API — Iniciar una ejecución desde su propio sistema mediante el endpoint de disparo de la API v1.
5. Integrado por el flujo de trabajo principal — Otro flujo de trabajo lo llama como un cuadro negro a través del paso sub_workflow.

Paso · Paso

El paso es la unidad de ejecución más pequeña del flujo de trabajo. Cada paso debe y sólo puede seleccionar un "modo principal":

• single — Un único Agente realiza una descripción de tarea. La primitiva de llamadas LLM más ligera.
• group_chat — Varios agentes discuten por turnos y se refieren al contexto de cada uno. Adecuado para lluvia de ideas y revisión crítica.
• agent_based — Un agente orquestador lee la tarea y envía dinámicamente las subtareas al agente trabajador.
• code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
• classifier — El LLM asigna una etiqueta de categoría a la entrada, el resultado se escribe en la variable indicada por output_variable, y los steps posteriores ramifican con condition.
• state_machine — Múltiples estados + condiciones de transición de estado. Adecuado para múltiples iteraciones o flujos de trabajo que contienen procesos pequeños.
• sub_workflow — Llame a otro flujo de trabajo como caja negra, con verificación de contrato, detección de bucle y aislamiento de variables.
• workflow_output_read — Lee la salida publicada por la ejecución de otro workflow (publish_outputs) y la guarda en una variable local.

Además del modo principal, casi cualquier paso puede superponerse a los siguientes campos de mejora comunes:

• depends_on / condition — Dependencia predecesora + condición de salto (condition admite && y || de nivel superior)
• manual_approval — Control de aprobación manual: pausa la ejecución y, tras aprobar, continúa
• parallel / timeout_seconds — Configuración de ejecución en paralelo / timeout de paso
• retry — Estrategia de reintento de retroceso para errores transitorios
• repeat_until / iterate_over — Bucle hasta que se cumpla una condición / ejecución elemento a elemento sobre una colección
• extract / aggregate — Seleccionar campos de la salida/combinar múltiples entradas
• publish_outputs — Publica los artefactos del paso como salidas con nombre para que workflow_output_read las consuma
• idempotent — Declara «misma entrada → misma salida, sin efectos secundarios»; tras un reinicio del servicio, se usa para decidir si se puede reanudar automáticamente desde el paso interrumpido
• on_success / on_failure — Acciones complementarias tras el éxito/fracaso (envío de notificaciones, redacción de auditorías, etc.)

Agente·Agente

Un Agent es el encapsulado de «una sesión de LLM + las herramientas de que dispone + su política de ejecución». En Braidrun casi nunca escribe el system prompt a mano — elige uno de los 19 presets integrados (universal / coder / researcher / data_analyst / web_scraper / writer, etc.) y hace overrides de unos pocos campos según haga falta.

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

Se puede hacer referencia a un Agente mediante varios pasos; La ejecución de cada paso abrirá una nueva instancia de sesión (sin memoria de cadena). Ver detalles Explicación detallada de la configuración del Agente.

Módulo · Módulo

Un módulo es un "flujo de trabajo que declara WorkflowModuleContract", es decir, un flujo de trabajo reutilizable que expone el contrato de entradas/salidas y puede ser invocado por otros flujos de trabajo a través de sub_workflow.

El valor aportado por el módulo:

• Mecanografiado + verificación del contrato a nivel de campo, no habrá "todos los problemas posteriores si se cambia el campo"
• Ejecución de caja negra: la persona que llama no puede ver los pasos internos y la lógica interna puede evolucionar de forma independiente.
• Detección de bucle doble en tiempo de ejecución + tiempo de liberación para evitar "A hace referencia a B y B hace referencia a A"
• Promocionar con un clic (extraer un paso en un módulo)/Degradar (restaurar el módulo a un paso en línea) en la biblioteca de módulos

La biblioteca de módulos incluye más de 120 módulos integrados (inicio de sesión en la plataforma, cálculo de ventanas de tiempo, extracción de informes de ASA, informes de Excel, entrega en Slack, etc.); ver detalles en Biblioteca de módulos integrada;Crea tu propio módulo ver Modularización y reutilización.

Ejecución·Ejecución

La ejecución es una instancia en ejecución específica de un flujo de trabajo. Su ciclo de vida es una máquina de estados:

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

Al llegar a un control de aprobación, la ejecución se detiene en estado de espera de aprobación y, tras la resolución, continúa por la máquina de estados.

Cada ejecución tiene:

• Fuente de activación (manual/programación/webhook/api/sub_workflow)
• Hora de inicio, hora de finalización, tiempo total empleado, tiempo empleado por paso
• Todos los eventos de entrada/salida/intermedios de pasos (flujo de eventos SSE)
• Token/coste acumulado
• lista de artefactos generados

Cuando el servicio se reinicia de forma anómala, la execution en curso se marca como INTERRUPTED. Tras habilitar recovery.autoResumeOnRestart, se puede reanudar automáticamente desde el paso interrumpido; ver detalles en Reanudación automática tras reinicio del servicio.

Credencial · Credenciales

Las credenciales son el almacenamiento unificado de información confidencial como "Clave API, Secreto de Webhook, Token OAuth". Todos los valores están cifrados con AES-256-GCM y se almacenan en el lado del servidor. Una vez escritos, no se pueden volver a leer (solo se pueden sobrescribir o eliminar).

Los enlaces de análisis se buscan en orden y el primer resultado surte efecto:

1. Espacio de nombres personal del usuario actual
2. El espacio de nombres del equipo del usuario.
3. Espacio de nombres del sistema (clave pública configurada por el administrador)

Los pasos del agente/código se analizan según demanda en tiempo de ejecución, nunca se escriben en los registros, no aparecen en las exportaciones YAML y no son visibles para otros pasos de la persona que llama.

Habilidad / Herramienta · Habilidades y Herramientas

"Manos" del agente: funciones que se pueden invocar durante la inferencia LLM. Dividido en tres categorías:

• Conjunto de herramientas incorporado — file_system / shell / web / browser / code_execution Espere, estará vinculado de forma predeterminada con el ajuste preestablecido.
• MCP Herramientas de extensión — Se puede registrar cualquier herramienta expuesta por el servidor MCP.
• Mercado de skills — Selecciona una habilidad publicada en el "Mercado de habilidades" y actívala con un clic.

Variables y expresiones

Todos los valores dinámicos se pasan entre llaves dobles. {{ ... }} referencia. Tres formas de escribirlo:

• {{var:name}} — variable de nivel superior del workflow
• {{steps.plan.output}} — salida de un paso upstream (la forma totalmente cualificada recomendada)
• {{plan}} — forma escueta: busca primero la salida por nombre de paso y luego el valor por nombre de variable

El resultado de clasificación del classifier se escribe en la variable indicada por su output_variable, y los pasos posteriores usan condition para decidir qué rama seguir. Las credenciales no pasan por variables de plantilla: en tiempo de ejecución se resuelven e inyectan desde el centro de credenciales según el provider; las variables que recibe un paso de code se inyectan como variables de entorno WF_VAR_*.

Para ver la sintaxis completa (JSONPath, filtro, expresiones de condición), consulte Variables y expresiones.

Ponlos juntos en una imagen.

       ┌──────────── 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)

Ya Sabes donde buscar

• Combate práctico: el primer flujo de trabajo. — Inserte los conceptos anteriores en un flujo de trabajo real
• 8 Tipos de pasos — Una referencia autorizada dedicada al modo principal.
• Variables y expresiones — Concatenar datos entre pasos
• Glosario — Cuando lea otros documentos y encuentre palabras nuevas, regrese y búsquelas.