Breakpoint Debugging

Braidrun's debugger is an interactive breakpoint debugger: set a breakpoint on any step, inspect variables when it pauses, edit and continue, or single-step forward one at a time. The experience matches debugging ordinary code.

Turn On Debug

Check the box in the "Execute" pop-up window:

• Enable Debug — Turn on debugging mode and display the debugging panel on the execution details page.
• Entrance Paused — Automatically pause before first step
• Pause on Exception — Automatically pause if any step fails
• Preview — The "Dry run" button at the bottom of the dialog only validates the execution plan without actually running it

Breakpoint Type

The engine supports nine breakpoint kinds in total. The visual panel on the execution detail page offers seven of them, filtered by step type; the sub-workflow entry and exit checkpoints can currently only be set through the REST API.

Each breakpoint also has a few optional fields:

• stepName — Hit only the specified step (case-insensitive); leave empty to hit every location of that type
• condition — A conditional expression that actually breaks only when satisfied, with the same syntax as a workflow condition
• once — Auto-disable after hitting once

Debugging Sub-Workflows

Breakpoints apply at all levels by default: a breakpoint set in a parent workflow also fires when a sub-workflow reaches a step of the same name.sub_workflow_entry / sub_workflow_exit These two breakpoint types attach to the parent step, pausing before entering the sub-workflow and after it returns, respectively, to make it easy to inspect the inputs passed in and the outputs written back.

The current public API matches breakpoints by type and stepName; it does not support call-path filtering. If a same-named child step is reused in several places, prefer setting sub_workflow_entry / sub_workflow_exit on the parent step or give each reuse site a distinct step name.

The Debug Panel

All debug controls live in the debug panel on the execution details page — there's no separate debugger window:

• Executive Control：Pause / Continue / Step buttons, with the current pause location shown live at the top
• Contextual Viewing：Variables, step outputs, and step-result summaries
• Snapshot History：A context snapshot is saved automatically at each checkpoint (up to the most recent 50 kept); drag the timeline to look back at the variables at any pause and open a diff to compare before and after
• Variable Editing：Double-click the variable value to modify it while paused
• DAG Visualization：Display breakpoint markers and pause highlighting directly on the DAG diagram
• Log Stream：Terminal-style log panel at the bottom of the execution details page

Controlling Debugging Via REST

Behind the debug panel is a set of REST endpoints you can call directly when scripting a diagnosis (the same interface the panel uses):

The prefix is /api/executions/{executionId}. For example:

# 给 fetch_data 步骤加断点,再加一个"出错即停"的一次性断点
curl -X PUT https://braidrun.com/api/executions/<execution-id>/debug/breakpoints \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "breakpoints": [
      {"point": "before_step", "stepName": "fetch_data"},
      {"point": "step_error", "once": true}
    ]
  }'

# 暂停 / 单步 / 继续
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/pause \
  -H "Authorization: Bearer <token>"
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/step \
  -H "Authorization: Bearer <token>"
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/continue \
  -H "Authorization: Bearer <token>"

Change a Variable While Paused, Then Continue

A typical scenario: an upstream step computed an obviously wrong parameter; once the breakpoint pauses, you fix the variable directly, click "Continue," and the following steps run with the new value, saving a whole rerun. In the panel, double-click a variable value to edit it; via REST use POST /debug/variables, and edits are only accepted while the execution is paused.

# 暂停态下把变量改对,然后 continue
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/variables \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"target_country": "US"}}'

Rerun from a Chosen Step

After the execution reaches the final state (completed, failed, canceled or interrupted), you can rerun from a certain step: click "Rerun from this step" in the execution timeline or step details panel. Usually the results of the steps before the rerun point are retained, and the retained LLM steps will not call the model again.

• The rerun point must be a step this execution actually ran; rerunning from the first step is a full rerun and isn't subject to this restriction
• You can't rerun while the execution is still running — cancel it or wait for it to finish first
• REST:POST /api/executions/{executionId}/restart-from-step; leaving stepName empty in the body means a full rerun from the start

Current Restrictions

• Mainly pause at step boundaries and compound node key points
• does not hang inside the tool / token stream
• Top-level concurrency will be serialized when debugging is enabled

Next

• Scheduling — Connect the debug-passed workflow to cron / webhook
• Auto-Resume — After debugging, decide which steps are idempotent