エディタの使い方
Workflow を作成する
ワークフロー 一覧(/workflows)で名前と説明を入力し、新規作成 を押すと、
空の draft Revision のエディタ(/workflows/revisions/:revisionId/edit)へ移動します。
または テンプレートから作成 のボタンから、定義済みのグラフで開始できます (テンプレート を参照)。
または AIで下書きを作成(Workflow Designer)を使って、自然言語の要望から自動でグラフ構造を下書き生成することもできます。
AIで下書きを作成 (Workflow Designer)
ワークフロー一覧画面の AIで下書きを作成 ボタンを押すと、専用の生成モーダルが開きます。
- 要望の入力 — 作成したいワークフローの処理内容(例: 「Vault 内の daily ノートを読み込んで要約し、Agent でタスクを整理する」など)を入力します。
- AI による下書き生成 — AI が専用ツール(GraphBuilder)を操作し、Node/Edge グラフ、Loop、型付き参照、条件などの構造を段階的に下書き生成します。
- プレビューと確認 — 生成完了後、グラフの概要・前提事項・構成ノードごとの想定副作用と承認要否・静的検証警告(静的検証 issue)がプレビュー表示されます。
- 下書きを作成 — 内容を確認し 下書きを作成 を押すと、Definition Package がインポートされ、
draftRevision として保存されたエディタ画面へ移動します。
複雑なグラフや未解決の参照を含む生成結果は、インポート後にエディタでノード設定や参照パスの手動調整が必要になる場合があります。静的検証警告が存在する場合でも、構造的に有効なグラフであれば「編集が必要な draft」として保存・編集が可能です。
- 外部送信情報: 外部 LLM プロバイダへ送信されるのは「要件テキスト」「Capability メタデータ/スキーマ」「Agent 名/ID/許可ツール」「Project 名/ID」「Person 名/ID」「Vault 相対パス」および「ツール実行結果」です。Vault の本文・Agent システムプロンプト・Project 作業パス・人物属性は送信されません。
- 実行ログ保持: 生成プロセスでのやり取りは turn ごとに
llm_call_logsに記録されます(日次ログ削除ジョブが導入されている環境では 30 日間保持されます)。 - 表示中止(キャンセル)の挙動: 生成中に「表示中止」を押すと、画面上の待機と表示のみが直ちに中断されます。バックエンドで進行中の LLM 処理の即時停止は保証されませんが、利用者が「下書きを作成」を押すまでデータベースへ Workflow は保存されません。
エディタの画面構成
上部ヘッダーに workflow_id / v<version> (<status>) が表示され、未保存の変更があると 未保存 が付きます。
公開済み / 旧版の Revision では読み取り専用になり、表示のみ と表示されます。
| ボタン | 動作 |
|---|---|
| 保存 | draft Revision を保存する。公開済み / 旧版では表示されない。 |
| 検証 | draft のみ。未保存があれば保存してからサーバー静的検証を実行する。 |
| 公開 | draft のみ。保存後に検証し、合格すれば published にする。 |
| 実行 | 公開済み Revision を開いたときだけ表示。実行入力 を使って Run を作成する。 |
| 削除 | draft / 旧版 Revision を削除する。公開済み Revision には表示されない。 |
公開済み Revision は編集できないため、そのまま 実行入力 で Run を作成します。
draft では実行ボタン自体が表示されず、「公開すると実行できます」と表示されます。
旧版では実行もできません(再公開は不可)。
Run は published Revision からしか作成できません。通常は Workflow 詳細の
公開中の Revision で 実行 を使います。
キャンバス上で Node をドラッグして位置を調整できます。
Node を追加する
右パネルの Node 追加 で種別を選び、追加 を押します。
- 種別 —
capability/agent/llm/loop/text_template/terminal/loop_result。 capabilityのときは capability を選択 — 有効な Capability のみ表示され、plan_requiredのものには(要承認)が付きます。agentのときは Agent を選択 — 既存の Agent 一覧から選びます。- 親 — トップレベルに置くか、既存の Loop Node の子グラフに置くかを選びます(
loop_resultは子グラフ内でのみ有効)。
追加した Node は選択状態になり、右パネルで設定を編集できます。Node の 表示名(任意) を
入れておくと、キャンバス・Edge の source/target・参照候補でその名前が表示され、同じ種別の
Node を見分けやすくなります(表示名を空にすると capability_key などの構成値が使われます)。
参照パスは常に Node ID(UUID)です。
Edge を追加する
Edge 追加 で source と target を選び、種別(normal / error)を決めて Edge 追加 を押します。
選択肢には 表示名(種別・ID の先頭6文字) が並ぶので、同じ Capability の Node が複数あっても区別できます。
- target には 同じスコープ(トップレベル同士、または同じ Loop の子)にある Node だけが表示されます。
- 同じ source からの Edge は追加順に
order_indexが割り当てられます。
Edge の condition(条件付き排他的分岐)は、Edge 一覧の 条件 から編集できます
(後述の 参照ピッカー で from_path を選べます)。
Node の設定を編集する
Node を選択すると、右パネルに対応する設定欄が表示されます。入力もスキーマ定義も ガイド付きフォームで編集できます。
| 種別 | 設定項目 |
|---|---|
capability | capability_key(選択)、target(target を持つ Capability のみ。委譲先 Agent / 対象 Project を選択)、inputs(Capability の入力スキーマから生成。要承認は選択肢に表示)、retry.max_attempts |
agent | agent_id(選択)、inputs(構造化エディタ。キーを追加し、各値は値か参照)、output_schema(スキーマ作成フォーム) |
llm | provider(選択)、model、system_prompt、max_tokens、reasoning_effort(対応 provider のみ)、inputs(構造化エディタ。各値は値か参照)、output_schema(スキーマ作成フォーム) |
loop | state_schema(スキーマ作成フォーム)、input_mapping(state_schema から生成。各値は値か参照)、max_iterations、entry_node_id、continuation_condition(条件エディタ) |
loop_result | output_mapping(親 Loop の state_schema から生成。各値は値か参照) |
text_template | inputs(構造化エディタ。各値は値か参照)、template(補完・プレビュー付きエディタ) |
terminal | outcome(success / failure) |
capabilityのinputsは、選択した Capability の入力スキーマから生成されます。enumは選択肢、booleanはチェックボックス、integer/numberは数値入力になります。既知の項目は専用ピッカーに なります(relative_pathは Vault ファイルピッカー、project_idは Project 検索、person_idは 人物ピッカー、agent_idは Agent 選択、日付系は date / datetime 入力)。自由形式の項目は JSON 欄になります。specialist_agent/coding_cliは target 欄が表示され、委譲先 Agent・対象 Project を選びます (target に型付き参照は使えません)。agentのinputsはスキーマを持たない自由形式です。キーを追加し、各値はテキスト入力か 参照(型付き参照)を選べます。task/contextは入力候補として表示されます。llmのinputsも自由形式です。reasoning_effortは provider がopenai/ollama/opencode_goのときだけ表示され、それ以外へ切り替えると消えます。output_schemaは必須で、 この schema が後続 Node の出力参照候補になります。agentのoutput_schema、llmのoutput_schema、loopのstate_schema、右パネルのinputs_schemaは スキーマ作成フォーム で編集します(後述)。
選択中の Node は 削除 できます。Edge 一覧 から不要な Edge を削除できます。
スキーマを作成する
inputs_schema / output_schema / state_schema は スキーマ作成フォーム で編集します。
- プロパティを追加 — 名前を入れて 追加。各行で型(
string/integer/number/boolean/object/array)、必須、説明、enum(カンマ区切り、省略可)を設定します。 object型は入れ子のプロパティ、array型はitemsの型と(objectのとき)そのプロパティを 編集できます。minItems/maxItems(省略可)も編集でき、値は 実行入力 フォームの 追加・削除の可否に反映されます。- 未定義のプロパティを許可する で
additionalPropertiesを切り替えます。 - 上級者向けに JSONで編集 で生 JSON に切り替えられます。ルートは
type: "object"が必要です。 - 許可されるのはサブセットで、
object/properties/required、primitive、enum、配列などです ($ref/oneOf/anyOf/allOf/ 再帰は未対応)。違反はフォーム下部に表示されます。
Capability と書込・外部操作
Capability の選択肢には、書込・外部操作を含むものに 書込・外部 が付きます。選択中は
説明の下に注意が表示されます。検証 を実行すると、そうした Capability を含むグラフには
黄色の警告(workflow-server-warnings)が表示されますが、公開はブロックされません。
読み取り専用 Workflow に書き込み権限が紛れ込んでいないか確認するために使います。
定義した inputs_schema は 実行入力 フォーム(および Run の再実行フォーム)に反映されます。
ネストした object や配列にも対応します。
参照ピッカー(型付き参照)
{"$ref": "..."} の型付き参照は、参照 ボタンからピッカーで選べます。ピッカーは
そのスコープで使える候補を型付きで一覧します。
run.inputs.<field>—inputs_schemaの各項目(ネストも展開、配列は[0]の例つき)。nodes.<node_id>.output.<field>— 先行 Node の出力。Agent と単発 LLM はoutput_schema、 Loop はfinal_state.*/iterations/exit_reason、Loop Result はstate_schemaの項目。 Capability は structured かつ strict がオンの Node の宣言済み必須フィールドのみ表示します。 出力全体・opaque / receipt・非 strict・未宣言・必須でない経路は表示されません。coding_cli/specialist_agent/research_agent(mixed)は例外で、narrative.text(自由文)と条件用のreceiptフィールド(statusなど)だけを表示します。 表示される候補は入力先に応じて絞られます(本文・表示用入力にはnarrativeのみ、 条件にはreceiptの条件可フィールドのみ、ID 系は表示されません)。 直接入力することもできますが、公開時のサーバー検証で拒否されます。loop.state.<field>/loop.input.<field>/loop.iteration— Loop 子グラフ内のみ。
Capability の設定欄には出力契約(structured / receipt / mixed / opaque)が表示されます。
structured の読み取り系と hitl_wait を選ぶと strict が自動でオンになり、
それ以外の Capability では strict を指定できません(チェックは無効化されます)。
候補は 候補から選ぶ で開閉でき、検索欄で絞り込めます。コピー でパスをコピーできます。
候補を使わず直接入力することもできます(参照形式でない場合は警告が出ます)。
選択中は長い nodes.<id>.output... の下に 読みやすい要約(例: ノード表示名 · フィールド)が
表示されるので、パス全体を横スクロールで確認する必要はありません。
検証
- ローカル検証 — 編集内容に対してクライアント側でも形状チェックが走り、問題は黄色で表示されます。
- サーバー検証 — 検証 ボタンで
POST .../validateを呼び、結果を赤色で表示します。 - 公開 はサーバー検証に合格した場合のみ実行されます。
- 問題の行をクリックすると、該当する Node(または Edge の source Node)を選択して キャンバス上にスクロールします。
検証で検出される代表的なエラーは 制約とトラブルシューティング を参照してください。
Run を開始する
通常は Workflow 詳細の 公開中の Revision で 開く を押し、エディタの 実行入力 に値を入れて 実行 を使います (Run・承認・復旧 を参照)。実行入力は式(日付式)にも対応しています。
plan_required の Capability か Agent Node を含む場合、Run は waiting_approval で作成され、
Run 詳細で承認するまで実行されません(Run・承認・復旧 を参照)。
ワークフロー名の下のヘッダーバー(エディタ / Run 画面の上部)の 承認なしで実行する を
有効にすると、これらを含んでいても承認なしで実行されます。
この設定は 以降の Run(Scheduler を含む)に適用され、既存の Run には影響しません。
Revision を追加する
Workflow 詳細(/workflows/:workflowId)で 新しい下書き を押すと、
次のバージョンの draft Revision が作成され、そのままエディタが開きます。公開済み Revision は編集できないため、
変更は新しい下書きで行います。
- 公開済み Revision がある場合、その Node / Edge / 入力 Schema などのグラフ内容が
複製 され、新しい ID が割り当てられた
draftとして作成されます。キャンバスの 配置(ui_position)や Loop の子グラフ構成・型付き参照も引き継がれます。 - 公開済み Revision がない場合(作成直後の最初の下書きを除く)は、空のグラフ・
既定の
inputs_schemaで開始します。 - 複製元の公開済み Revision は変更されません。下書き側を編集しても複製元には影響しません。
Revision を削除する
draft と旧版(superseded)の Revision は、エディタの 削除 ボタンか Workflow 詳細の一覧から削除できます。
公開済み(published)の Revision は削除できません。
- 削除は確認後に実行され、取り消せません。グラフ(Node / Edge)ごと削除されます。
- 削除した Revision を参照する Run は残ります。Run はグラフをスナップショットとして保持しているため、 閲覧や再実行(rerun)に影響しません。