ドキュメント走るブレークポイントのデバッグ

ブレークポイントのデバッグ

9 種類のブレークポイント、条件式、変数の検査とホット修正 —— 自動化プロセスをブラックボックスでなくします。

Braidrun のデバッガーはインタラクティブなブレークポイントデバッガーです。任意のステップにブレークポイントを設定し、一時停止後に変数を確認し、変更してから継続する、あるいは 1 コマずつステップ実行できます。体験は通常のコードのデバッグに揃えられています。

デバッグをオンにする

「実行」ポップアップウィンドウのチェックボックスをオンにします。

デバッグを有効にする — デバッグモードをオンにして、実行の詳細ページにデバッグパネルを表示します。
入場一時停止 — 最初のステップの前に自動的に一時停止します
例外時に一時停止する — いずれかのステップが失敗した場合は自動的に一時停止します
プレビュー — ポップアップ下部の「ドライラン」ボタンは、実行計画を検証するだけで実際には実行しません

debug を有効にすると、トップレベルの並列処理は直列化され、段階的なトラブルシューティングがしやすくなります。本番公開時に debug を無効にすればよいです。デバッガーは Pro プランから提供されます。

9 種類のブレークポイントタイプ

ブレークポイントの種類	トリガーポイント
`before_step`	手順を始める前に
`after_step`	ステップが正常に完了したら
`step_error`	ステップでエラーがスローされた場合
`state_machine_state`	state_machine ある state に入ったとき
`group_chat_round`	group_chat 各ラウンドの発言前
`iteration_item`	iterate_over 各反復の前に
`agent_based_delegation`	agent_based サブタスクを委任する前に
`sub_workflow_entry`	sub_workflow サブワークフローに入る前（親ステップでトリガー）
`sub_workflow_exit`	sub_workflow サブワークフローが返り、出力が親コンテキストに書き戻された後

各ブレークポイントにはさらにいくつかの任意フィールドがあります。

stepName — 指定したステップのみにヒットします（大文字と小文字を区別しません）。空にすると、そのタイプのすべての位置にヒットします
condition — 条件式で、満たされたときにのみ実際に中断します。構文は workflow の condition と同じです
once — 1 回ヒットした後に自動的に無効化されます

サブワークフローのデバッグ

ブレークポイントはデフォルトですべての階層に有効です。親ワークフローで設定したブレークポイントは、サブワークフローが同名のステップを実行する際にも同様にヒットします。sub_workflow_entry / sub_workflow_exit これら 2 種類のブレークポイントは親ステップに付加され、それぞれサブワークフローに入る前とそれが返った後で停止し、渡された inputs と書き戻された outputs を確認しやすくします。

同一のサブワークフロー（例えば 1 つのマーケットプレイスモジュール）が複数の親ステップで再利用される場合、デバッグエンジンはブレークポイントに以下を追加することをサポートします parentPath フィルタ: ブレークポイントは、サブワークフローが指定した親ステップの経路を経由して呼び出された場合にのみヒットし、他の呼び出し経路における同名のステップは中断されません。

デバッグパネル

デバッグ操作はすべて実行詳細ページのデバッグパネル内にあり、独立したデバッガーウィンドウはありません。

執行管理：一時停止 / 継続 / ステップ実行のボタン。上部には現在の一時停止位置がリアルタイムで表示されます
状況に応じた表示：変数、ステップ出力、ステップ結果の要約
スナップショット履歴：チェックポイントを 1 つ通過するたびにコンテキストのスナップショットが自動的に保存され（最大で直近 50 個を保持）、タイムラインをドラッグすると任意の一時停止時の変数を振り返ることができ、Diff を有効にして前後の変化を比較できます
変数の編集：一時停止中に変数値を変更するには、変数値をダブルクリックします。
DAG の視覚化：DAG 図上で直接ブレークポイントマーカーを表示し、ハイライトを一時停止します。
ログストリーム：実行の詳細ページの下部にあるターミナルスタイルのログパネル

REST でデバッグを制御する

デバッグパネルの背後には一連の REST エンドポイントがあり、スクリプトを書いてトラブルシューティングする際に直接呼び出せます（パネルと同じインターフェースです）。

Endpoint	用途
`GET /debug/state`	デバッグ状態: 一時停止しているかどうか、ブレークポイント一覧、現在の一時停止点
`GET /debug/context`	現在の変数、ステップ出力、結果の要約
`POST /debug/pause`	一時停止をリクエストし、次のチェックポイントで有効になります
`POST /debug/continue`	継続して、次のブレークポイントまで実行します
`POST /debug/step`	ステップ実行: 次のチェックポイントまでのみ進みます
`PUT /debug/breakpoints`	ブレークポイントをグループごと置き換えます（実行中いつでも変更できます）
`PUT /debug/break-on-error`	実行中に「例外時に一時停止」を切り替えます
`GET /debug/snapshots`	スナップショット履歴。番号を指定して 1 つだけ取得することもできます
`POST /debug/variables`	一時停止状態で変数を変更します

プレフィックスはすべて /api/executions/{executionId}です。例:

bash

# 给 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>"

一時停止時に変数を変更し、そのまま実行を続けます

典型的なシナリオ: 上流ステップが明らかに誤ったパラメータを算出した場合、ブレークポイントで停止した後に変数を直接正しい値に修正し、「継続」をクリックすれば、以降のステップは新しい値で実行され、全ラウンドのやり直しを省けます。パネルで変数の値をダブルクリックすると編集できます。REST では以下を使用します POST /debug/variables。実行が一時停止状態にあるときのみ変更を受け付けます。

bash

# 暂停态下把变量改对,然后 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"}}'

指定したステップから再実行

実行が終了状態（完了、失敗、またはキャンセル）に達した後、あるステップから再実行できます。実行タイムラインまたはステップ詳細パネルで「このステップから再実行」をクリックします。再実行ポイントより前のステップの結果はそのまま保持され、完了済みの LLM ステップはモデルを再度呼び出さないため、重複した token 費用は発生しません。

再実行ポイントは、この実行で実際に走ったステップである必要があります。最初のステップから再実行することは全体の再実行に相当し、この制限を受けません
実行がまだ動作中のときは再実行できません。まずキャンセルするか、終了を待ってください
REST:POST /api/executions/{executionId}/restart-from-step。body 内の stepName を空にすると、最初から再実行することを意味します

ブレークポイントによるトラブルシューティング + 変数の変更 + エラーステップからの再実行を組み合わせることが、長いワークフローの節約的なデバッグ手法です。前段の数十ステップの結果を保持し、エラーが起きた部分にのみ費用を払います。

現在の制限事項

主にステップ境界と複合ノードのキーポイントで一時停止します。
ツール/トークンストリーム内でハングしない
デバッグが有効になっている場合、トップレベルの同時実行はシリアル化されます。

次のステップ

スケジュール設定 — デバッグに渡されたワークフローを cron / webhook に接続する
自動再開 — デバッグ後、どのステップが冪等であるかを決定します