Core Concepts

All the functions in Braidrun - canvas, YAML, scheduling, approval, monitoring - revolve around a very restrained set of core concepts. This page puts these concepts into a picture so that you "know the coordinates no matter which article you read later."

Workflow · Workflow

Workflow is the top-level object of this platform. You can think of it as "a versionable business process diagram", consisting of:

• A YAML document (defining the structure)
• A set of metadata (triggers, parameter presets, permissions, tags)
• Several past Execution records (for auditing and debugging)

. The same workflow is shown as a DAG canvas in the web UI; the canvas and the YAML are two views of one definition. Diffs in Git are ordinary YAML diffs, not a messy JSON dump.

A workflow can be triggered in five ways:

1. Manual — Click "Execute" in the editor, or initiate batches from the list.
2. Scheduled — A cron expression, a fixed interval, a one-time schedule, or a chained trigger that fires N seconds after an upstream workflow completes.
3. Webhook — Triggered by an external system POST, authenticated with an API Key (HMAC signatures supported for compatibility).
4. API — Start an execution from your own system using the v1 API's trigger endpoint.
5. Embedded by parent workflow — Called as a black box by another workflow through sub_workflow step.

Step · Step

Step is the smallest execution unit in the workflow. Each step must and can only select one "main mode":

• single — A single Agent performs one task description. The most lightweight LLM calling primitive.
• group_chat — Multiple agents discuss in turns and refer to each other's context. Suitable for brainstorming and critical review.
• agent_based — An orchestrator agent reads the task and dynamically dispatches the subtasks to the worker agent.
• code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
• classifier — The LLM assigns a category label to the input; the result is written to the variable named in output_variable, so later steps can branch on it via condition.
• state_machine — Multiple states + state transition conditions. Suitable for multiple iterations or workflows containing small processes.
• sub_workflow — Call another workflow as a black box, with contract verification, loop detection, and variable isolation.
• workflow_output_read — Read outputs published by another workflow's execution (publish_outputs) and store them in local variables.

On top of the main mode, almost any step can overlay the following common enhancement fields:

• depends_on / condition — Predecessor dependencies + skip conditions (condition supports top-level && and ||)
• manual_approval — Manual approval gate: pause execution and continue after approval
• parallel / timeout_seconds — Parallel-execution config / step timeout
• retry — Backoff retry strategy for transient errors
• repeat_until / iterate_over — Loop until a condition is met / iterate over a collection item by item
• extract / aggregate — Select fields from output / merge multiple inputs
• publish_outputs — Publish a step's artifacts as named outputs for workflow_output_read to consume
• idempotent — Declare "same input → same output, no side effects"; on auto-resume after a service restart, it decides whether the interrupted step can be rerun
• on_success / on_failure — Supplementary actions after success/failure (sending notifications, writing audits, etc.)

Agent·Agent

An Agent wraps "one LLM session + the tools it can use + its run policy." In Braidrun you almost never hand-write a system prompt — pick one of the 19 built-in presets (universal / coder / researcher / data_analyst / web_scraper / writer, and so on) and override a few fields as needed.

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

An Agent can be referenced by multiple steps; each step execution will open a new session instance (no string memory). See details Agent Configuration Guide.

Module · Module

A module is a "workflow that declares WorkflowModuleContract" - that is, a reusable workflow that exposes the inputs / outputs contract and can be called by other workflows through sub_workflow.

The value brought by the module:

• Typed + field-level contract verification, there will be no "all downstream problems if the field is changed"
• Black box execution - the caller cannot see the internal steps and the internal logic can evolve independently
• Double loop detection at runtime + release time to avoid "A references B, and B references A"
• One-click Promote (extract a step into a module)/Demote (restore the module to an inline step) in the module library

The module library ships with 120+ built-in modules (platform login, time-window calculation, ASA report pulls, Excel reports, Slack delivery, and more); see Built-In Module Library;Create your own module see Modularization and Reuse.

Execution·Execution

Execution is a specific running instance of a workflow. Its life cycle is a state machine:

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

When it hits an approval gate, execution pauses in an awaiting-approval state and resumes the state machine after a decision.

Each execution has:

• Trigger source (manual/schedule/webhook/api/sub_workflow)
• Start time, end time, total time taken, time taken per step
• All step input/output/intermediate events (SSE event stream)
• Accumulated token/cost
• list of generated artifacts

When the service restarts unexpectedly, in-progress executions are marked INTERRUPTED. With recovery.autoResumeOnRestart enabled, they can auto-resume from the interrupted step; see Auto-Resume After Service Restart.

Credential · Credentials

Credentials provide centralized storage for sensitive values such as API keys, webhook secrets, and OAuth tokens. All values are encrypted on the server with AES-256-GCM. After a value is saved, it cannot be read back; it can only be overwritten or deleted.

The parsing links are searched in order, and the first hit takes effect:

1. Current user's personal namespace
2. The namespace of the user's team
3. System namespace (public key configured by administrator)

Agent / code steps are parsed on demand at runtime, never written to logs, do not appear in YAML exports, and are not visible to other steps from the caller.

Skill / Tool · Skills and Tools

Agent's "hands" - functions that can be called during LLM inference. Divided into three categories:

• Built-in toolset — file_system / shell / web / browser / code_execution Wait, it will be tied by default with the preset.
• MCP Extension tools — Any tool exposed by the MCP server can be registered.
• Skill Market — Select a published skill in the "Skill Market" and activate it with one click.

Variables And Expressions

All dynamic values are passed through double curly braces {{ ... }} reference. Three forms:

• {{var:name}} — A workflow top-level variable
• {{steps.plan.output}} — An upstream step's output (the recommended fully-qualified form)
• {{plan}} — Bare form: look up the output by step name first, then the value by variable name

A classifier's result is written to the variable named in its output_variable, and downstream steps use condition to decide which branch to take. Credentials don't go through template variables: at run time they're resolved by provider from the credential center and injected; variables handed to a code step are injected as WF_VAR_* environment variables.

For complete syntax (JSONPath, filter, condition expressions) see Variables And Expressions.

Put Them Together in a Picture

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

You Already Know Where to Look

• Hands-On: Your First Workflow — String the above concepts into a real workflow
• 8 Step Types — An authoritative reference dedicated to the main mode
• Variables And Expressions — Concatenate data between steps
• Glossary — When reading other documents and encountering new words, come back and look them up