scenario-workflow-authoring

シナリオワークフローの作成

概要

ワークフローには、2つの表現があります。編集可能なノードグラフである editor_info（nodes、edges、inputKeys）と、コンパイル済みの実行形式である flow です。MCP を使って作成する場合は、editor_info ドキュメント全体を書き込みます。ノードごとの編集ツールはありません。変更のたびに、workflow_create または workflow_update を使ってグラフ全体を読み取り、変更し、書き込みます。flow を手動で記述してはいけません。workflow_publish が editor_info をコンパイルして flow にし、ステータスを ready に切り替えます。ready 状態のワークフローで editor_info を編集しても、再度公開するまでは古い flow が実行され続けます。

グラフを作成する前に、references/editor-info.md をお読みください。ノードタイプの語彙、ノード選択の指針（llm ノードを使用できるケース）、エッジの方向のルール、ノードごとのデータコントラクト、検証済みの最小限の例が記載されています。作成、更新、公開、コピー、削除は、ツールカタログ（scenario_tools_search と対応する実行ツール。scenario スキルを参照）にあります。workflows_list、workflow_get、workflow_run は直接ツールです。スコープと dry_run は最上位の引数に指定し、実行ツールのラッパーには含めません。実行と料金については、scenario-workflows スキルを参照してください。ここで名前を挙げた関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業する場合は、ツールスキーマに従って進め、不足している点を明示してください。

クイックリファレンス

手順	呼び出し	備考
1. グラフを調査	動作するワークフローに対して workflow_get	構造をコピーし、ID は決してコピーしないでください
2. モデルのコントラクト	model_schema_get	ハンドル名と必須入力
3. 作成	editor_info + inputs_definition	リファレンスファイルに従ってください
4. 作成	workflow_create	原子的ではありません。以下を参照してください
5. 公開	workflow_publish	flow をコンパイルします。出力ピンが1つ必要です
6. 検証	dry_run=true を指定して workflow_run	料金を計算し、実際のバリデーターを実行します

workflow_create は内部で2回の呼び出しを行います。作成に失敗しても、エラーに ID が含まれるドラフトが作成済みの場合があります。その ID に対して workflow_update を使って復旧してください。再作成すると重複が生じます。手順1では workflow_get を使ってください。これにより、ID がわかっているワークフローの完全なグラフを取得できます。公開ワークフローも対象です（ユーザーが指定した ID またはアプリの URL、あるいは workflows_list で取得した自分のチームのワークフロー）。公開テンプレートを探すには、target="workflows"、public=true、キーワードの query、limit=3、およびスコープを指定して search を使います。たとえば、query="image" と生の filter: 'status = "ready"' を指定します。ID は workflows から取得し、選んだグラフは workflow_get で取得してください。検索結果は概要であり、グラフドキュメントではありません。ワークフロー検索が対応しているのはキーワードテキストとフィルターのみなので、画像検索やセマンティック検索のオプションは省略してください。保存済みワークフローの一覧には workflows_list を使います。 scripts/fetch_workflow_examples.py は、メンテナー向けに注目ワークフローのグラフを一括エクスポートして整形します（セットアップ方法はファイルのヘッダーを参照してください）。

例：テキストから画像を生成するアプリ

1. recommend を capability: "txt2img" として呼び出し、ユーザーの概要を prompt に指定します。scenario スキルの next_step の手順に従い、その後 model_schema_get を呼び出します。入力名はモデルノードのハンドル名になり、required フラグは接続が必要な項目を示します。ユーザーがモデル名を指定している場合は、代わりに search を使います。
2. editor_info を作成します。text1 には data.isInput: true、model1 には type: "model"、data.modelId、data.isOutput: true を指定します。model1 の入力から text1 の出力へエッジを1つ接続します（エッジでは下流のノードを source として指定します。リファレンスを参照してください）。inputKeys: ["text1"] も指定します。
3. name、editor_info、および text1 を文字列入力として指定する inputs_definition を指定して workflow_create を呼び出します。公開される入力キーはノード ID になるため、実行時の入力名は text1 のようになります。
4. workflow_publish を呼び出し、続けて dry_run=true を指定して workflow_run を呼び出し、検証と料金の確認を行います。検証に失敗した場合は、グラフを修正して再公開します。

各項目に対して1つずつ出力するにはループが必要です

複数アセットの入力を生成モデルの参照フィールドに直接接続すると、すべての項目を一度に条件として1回生成されます。たとえば、商品写真を10枚入力すると、10枚が混ざった画像が1枚返され、10件分の編集結果にはなりません。フィールド名とカーディナリティはモデルごとに異なるため、model_schema_get から確認してください（array: true はリストを示します）。また、フィールドの説明も確認してください。ユーティリティツールの中には、リストを受け取り、ループなしで項目ごとに1つの出力を返すものもあります。各項目に独自の結果が必要な場合は、リストを対象とする forEach の中にモデルを配置し、forEachEnd から出力を取得します（接続方法はリファレンスの forEach セクションを参照してください）。項目を単一出力の共同参照として使う場合に限り、直接接続します。ループ内では、現在の項目を1項目だけのリストとして配列フィールドに渡します。forEach は項目ごとに料金が発生するモデルジョブを1つ実行しますが、ドライランで表示される料金はリストの長さにかかわらず1回分です（確認例：項目が1つでも2つでも見積もりは1回分で、2つの場合はその2倍の料金が発生）。そのため、ユーザーに料金を提示する前に見積もり額に項目数を掛けてください。

別のノードツールからグラフを移行する

Weavy、ComfyUI、または別のノードエディターからエクスポートしたパイプラインはインポートできません。エクスポートとインポートの往復に対応するのは Scenario 独自のエクスポートのみです。上記のとおり、ノードごとに変換してから作成、公開、ドライランを行います。マッピング表、メンバーの解決方法、ユーザーに返されるレポートについては、references/foreign-graph-import.md を参照してください。このようなエクスポートを扱う前に必ず読み、その最初のルールに従って、ファイルを会話に貼り付けるのではなく、まずローカルで表にまとめてください。

よくある間違い

• UI パレット名をノードタイプとして記述する：保存されるタイプはリファレンスに記載された camelCase の語彙で、すべてのジェネレーターは type: "model" です。
• エッジを生成元から消費先へ接続する：保存されるエッジは逆方向を指します。
• editor_info を更新すれば、再公開しなくても実行中のアプリに反映されると思い込む。
• workflow_create が失敗したとき、エラーに記載された ID を使って workflow_update する代わりに、2回目の作成を試みる。
• 複数のアセットを1つのモデル入力に接続し、アイテムごとに1つの出力が得られると思い込む：これはそれらすべてを使った1回の生成です。forEach でループします。
• 出力ピンを設定せずに公開する、またはテキストノードやアセットノードに data.isOutput を設定する：compiled to an empty flow で公開に失敗します。出力ピンは、成果物を生成する model、llm、または forEachEnd ノードに設定します。入力ピンは任意です。プロンプトが組み込まれたグラフは、入力なしで公開して実行できます。
• ビルダーまたはモデルの前にテキストノードを置き、そのノードをゲートする：分岐でスキップされるのは、そのハンドルに接続されたノードだけです。そのため、後続のノードは保留状態のままになり、ジョブが完了しません。処理を行うノードをゲートするか、リファレンスの ifElse セクションに従い、条件付きのプロンプトテキストには CEL の三項演算子を使います。
• CEL リテラルに二重引用符を使う：評価はされますが、キャンバスエディターが壊れるため、一重引用符のみを使います。
• workflow_copy に workflow_id を送る：取得、更新、公開、実行、削除では workflow_id を指定しますが、コピーでは source_workflow_id を指定します。コピーはすべてをそのまま引き継ぎ、個別に公開する必要があります。