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

9 Breakpoint Types

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.

When the same sub-workflow (say, a marketplace module) is reused by multiple parent steps, the debug engine lets you add a parentPath filter to a breakpoint: it fires only when the sub-workflow is called via the specified parent-step path, and same-named steps on other call paths don't break.

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

Once an execution reaches a terminal state (completed, failed, or cancelled), you can rerun from a given step: click "Rerun from this step" in the execution timeline or the step details panel. Results of steps before the rerun point are kept as-is, completed LLM steps don't call the model again, and so no duplicate token charges are incurred.

• 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