コアコンセプト

Braidrun のすべての機能 (キャンバス、YAML、スケジューリング、承認、監視) は、非常に抑制された一連の核となる概念を中心に展開されます。このページでは、これらの概念を「後でどの記事を読んでも座標がわかる」ように図にまとめました。

ワークフロー · ワークフロー

ワークフローは、このプラットフォームの最上位オブジェクトです。これは、次のもので構成される「バージョン管理可能なビジネス プロセス図」と考えることができます。

• YAML ドキュメント (構造を定義する)
• メタデータのセット (トリガー、パラメーター プリセット、権限、タグ)
• 過去のいくつかの実行記録 (監査およびデバッグ用)

で構成されます。同一の workflow は Web UI 上で DAG キャンバスとして表示され、キャンバスと YAML は同じ定義の 2 つのビューです。Git 内の diff は通常の YAML diff であり、乱雑な JSON dump ではありません。

ワークフローは 5 つの方法でトリガーできます。

1. マニュアル — エディターで「実行」をクリックするか、リストからバッチを開始します。
2. スケジュール — cron 式、固定間隔、一度きりのスケジュール、または「上流ワークフロー完了後に N 秒遅延」というチェーントリガー。
3. Webhook — 外部システムからの POST トリガー、API Key 認証（HMAC 署名と互換）。
4. API — v1 API のトリガーエンドポイントを使って、お客様自身のシステムから実行を開始します。
5. 親ワークフローによって埋め込まれます — sub_workflow ステップを通じて別のワークフローによってブラック ボックスとして呼び出されます。

ステップ・ステップ

ステップはワークフローの最小の実行単位です。各ステップでは、「メイン モード」を 1 つだけ選択する必要があり、選択できるのは次のとおりです。

• single — 単一のエージェントが 1 つのタスクの説明を実行します。最も軽量な LLM 呼び出しプリミティブ。
• group_chat — 複数のエージェントが順番に話し合い、互いのコンテキストを参照します。ブレーンストーミングや批判的なレビューに適しています。
• agent_based — オーケストレーター エージェントはタスクを読み取り、サブタスクをワーカー エージェントに動的にディスパッチします。
• code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
• classifier — LLM が入力にカテゴリラベルを付与し、結果を output_variable で指定された変数に書き込みます。後続の step が condition で分岐するために使用します。
• state_machine — 複数の状態 + 状態遷移条件。複数の反復や小規模なプロセスを含むワークフローに適しています。
• sub_workflow — コントラクトの検証、ループ検出、変数の分離を備えた別のワークフローをブラック ボックスとして呼び出します。
• workflow_output_read — 別のワークフロー実行が公開した出力（publish_outputs）を読み取り、ローカル変数に格納します。

メイン モードに加えて、ほぼすべてのステップで、次の共通の拡張フィールドをオーバーレイできます。

• depends_on / condition — 先行依存関係 + スキップ条件（condition はトップレベルの && と || に対応）
• manual_approval — 手動承認ゲート: 実行を一時停止し、承認後に継続実行します
• parallel / timeout_seconds — 並列実行の設定 / ステップのタイムアウト
• retry — 一時的なエラーに対するバックオフ再試行戦略
• repeat_until / iterate_over — 条件が満たされるまでループ / コレクションを 1 項目ずつ実行
• extract / aggregate — 出力からフィールドを選択/複数の入力を結合
• publish_outputs — ステップの成果物を名前付き出力として公開し、workflow_output_read で利用できるようにします
• idempotent — 「同じ入力 → 同じ出力、副作用なし」を宣言します。サービス再起動後の自動再開時に、中断したステップから再実行できるかどうかの判断に使用されます
• on_success / on_failure — 成功/失敗後の補足アクション (通知の送信、監査の作成など)

エージェント・エージェント

Agent は「1 回の LLM セッション + それが使えるツール + その実行ポリシー」をカプセル化したものです。Braidrun では system prompt を直接手書きすることはほとんどありません。19 種類の内蔵 preset から 1 つを選び（universal / coder / researcher / data_analyst / web_scraper / writer ……）、必要に応じていくつかのフィールドを overrides するだけで十分です。

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

エージェントは複数のステップで参照できます。各ステップの実行により、新しいセッション インスタンスが開きます (文字列メモリはありません)。詳細を見る エージェント構成の詳細説明。

モジュール・モジュール

モジュールは「WorkflowModuleContract を宣言するワークフロー」です。つまり、入出力コントラクトを公開し、sub_workflow を通じて他のワークフローから呼び出すことができる再利用可能なワークフローです。

モジュールによってもたらされる価値:

• 型付き + フィールドレベルのコントラクト検証により、「フィールドが変更された場合に下流側で問題が発生する」ことはなくなります。
• ブラックボックス実行 - 呼び出し元は内部ステップを見ることができず、内部ロジックは独立して進化できます。
• 「A が B を参照し、B が A を参照」を回避するための実行時 + リリース時の二重ループ検出
• モジュール ライブラリでワンクリックでプロモート (ステップをモジュールに抽出)/降格 (モジュールをインライン ステップに復元)

モジュールライブラリには 120 以上の内蔵モジュール（プラットフォームログイン、時間ウィンドウ計算、ASA レポート取得、Excel レポート、Slack 配信など）が付属しています。詳細は以下を参照してください 内蔵モジュールライブラリ;独自のモジュールを作成するを参照してください。 モジュール化と再利用。

実行・実行

実行は、ワークフローの特定の実行インスタンスです。そのライフサイクルはステートマシンです。

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

承認ゲートに到達すると、実行は承認待ちの状態で停止し、承認後にステートマシンの処理を継続します。

各実行には次のものがあります。

• トリガーソース（manual/schedule/webhook/api/sub_workflow）
• 開始時刻、終了時刻、合計所要時間、ステップあたりの所要時間
• すべてのステップ入力/出力/中間イベント (SSE イベント ストリーム)
• 蓄積されたトークン/コスト
• 生成されたアーティファクトのリスト

サービスが異常再起動した際、進行中の execution は INTERRUPTED としてマークされます。recovery.autoResumeOnRestart を有効にすると、中断したステップから自動的に再開できます。詳細は以下を参照してください サービス再起動後の自動再開。

資格情報 · 資格情報

認証情報は、「API キー、Webhook シークレット、OAuth トークン」などの機密情報を統合して保存するものです。すべての値は AES-256-GCM で暗号化され、サーバー側に保存されます。一度書き込んだ後は読み戻すことはできません（上書きまたは削除のみ可能）。

解析リンクは順番に検索され、最初のヒットが有効になります。

1. 現在のユーザーの個人の名前空間
2. ユーザーのチームの名前空間
3. システム名前空間 (管理者によって設定された公開キー)

エージェント/コード ステップは実行時にオンデマンドで解析され、ログには書き込まれず、YAML エクスポートには表示されず、呼び出し元から他のステップには表示されません。

スキル / ツール · スキルとツール

エージェントの「手」 - LLM 推論中に呼び出すことができる関数。 3 つのカテゴリに分類されます。

• 内蔵ツールセット — file_system / shell / web / browser / code_execution お待ちください。デフォルトではプリセットに関連付けられます。
• MCP 拡張ツール — MCP サーバーによって公開される任意のツールを登録できます。
• スキル市場 — 「スキルマーケット」で公開されているスキルを選択し、ワンクリックで有効化します。

変数と式

すべての動的値は二重中括弧を介して渡されます。 {{ ... }} を参照します。3 つの書き方があります。

• {{var:name}} — workflow のトップレベル変数
• {{steps.plan.output}} — 上流ステップの出力（推奨される完全修飾形式）
• {{plan}} — 省略形式: まずステップ名で出力を検索し、次に変数名で値を検索します

classifier の分類結果は、その output_variable で指定された変数に書き込まれ、下流ステップは condition でどの分岐に進むかを判断します。認証情報はテンプレート変数を経由しません。実行時に provider に応じて認証情報センターから解決して注入されます。code ステップが取得する変数は、WF_VAR_* 環境変数として注入されます。

完全な構文 (JSONPath、フィルター、条件式) については、「」を参照してください。 変数と式。

それらを写真にまとめます

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

どこを見るべきかはすでにわかっていますね

• 実戦：最初のワークフロー — 上記の概念を実際のワークフローに組み込む
• 8ステップタイプ — メインモード専用の信頼できるリファレンス
• 変数と式 — ステップ間のデータを連結する
• 用語集 — 他の文書を読んで新しい単語に出会ったら、戻って調べてください