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 492 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
• Input/output/intermediate events of all steps; the console obtains real-time updates through WebSocket
• Accumulated token/cost
• list of generated artifacts

When the service restarts abnormally, the execution in progress will be marked as INTERRUPTED. When the deployment enables automatic recovery, the workflow policy allows it, and the recovery point meets the idempotent requirements, the run will automatically continue from the step boundary. For details, 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.

Users can create two scopes: personal and team. Runtime performs identity resolution as currently:

1. Current user's personal namespace
2. The namespace of the user's team

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.

Connection · Third-party authorization

Third-party authorization is a specialized form of credentials: the platform knows which fields are required for this service, where to apply, and how to verify, so it can immediately make an upstream confirmation connection when you save it, and echo the recognized account number.

The official module directly declares which service it depends on in the contract. When dragged into the workflow, connection variables are automatically registered and wiring is automatically performed. The same service only needs to be authorized once in a workflow.

View full description of third-party authorizations

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 (variable extraction, aggregation and 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
• Step Types and Enhancements — 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