scenario-workflows

シナリオのワークフロー

概要

シナリオのワークフローは、複数のモデルをつないだノードグラフを保存し、1 回の呼び出しで実行するものです。ユーザーが「アプリ」と呼ぶのは、ステータスが ready のワークフローです。workflow_run はジョブを返し、ほかの生成ジョブと同じように追跡できます。

デフォルトで一覧に表示されるのは workflows_list、workflow_get、workflow_run のみです。承認と却下は、scenario_tools_search とそれぞれの実行レーンを通じて行います。接続と基本的なループについては、scenario スキルを参照してください。グラフの作成、編集、公開については、scenario-workflow-authoring スキルを参照してください。ここに記載されているスキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマに従い、スキルが不足していることを明記してください。

クイックリファレンス

手順	呼び出し	備考
1. 一覧表示	workflows_list status="ready"	limit は必ず上限を設けてください
2. 入力仕様を確認	一覧の inputs[]、workflow.inputs_definition を取得	name が実行時のキーです
3. 料金確認と検証	dry_run=true を指定して workflow_run	料金を返します。ジョブは作成しません
4. 実行	inputs を指定して workflow_run	ジョブを返します
5. 待機	jobs_wait	pending_job_ids を指定して再度呼び出します

ID の接頭辞は wflow_ です。workflows_list または search からコピーし、自分で作成しないでください。名前を指定したアプリや公開テンプレートを探すには、target="workflows"、キーワードの query、limit=3、対象範囲を指定して search を呼び出します。公開カタログを対象にするには、public=true を追加してください。ワークフローの検索で対応しているのは、キーワードテキストとフィルターであり、画像検索やセマンティック検索には対応していません。利用可能なアプリを探すには、生の filter: 'status = "ready"' を追加してください（filters.status ではありません）。検索結果は workflows から読み取り、選んだ ID に対して workflow_get を呼び出し、workflow.inputs_definition から入力仕様を確認してください。検索の概要には、実行時の入力も編集可能なグラフも含まれていません。検索では page_token ではなく offset を使用します。空のページに _hint がある場合は、同じ検索を繰り返さず、その指示に従ってください。

すべての一覧呼び出しに上限を設定する

各レコードには、コンパイル済みの flow とノードグラフ全体を含む editorInfo が含まれます。また、ツールには簡易表示フラグがありません。ライブレコードではこの 2 つのフィールドがバイト数の 4 分の 3 を占め、文字数は約 1,900～22,000 でした。また、flow: [] のドラフトにも editorInfo は含まれます。limit は 3 以下に設定し、id、name、hasFlow、inputs のみを読み取ってください。ページ送りでは、前の応答にある nextPaginationToken を page_token に設定します。最後のページでは指定しません。作成時点のツールスキーマでは上限が 200 と示されていましたが、API は 100 を超える値を pageSize と許容範囲 [1; 100] を示す 400 エラーで拒否します。そのため、スキーマの最大値をそのまま送信しないでください。

サーバー側でフィルターできるステータスは draft と ready のみです。それ以外のステータスは、各ページでクライアント側フィルターが適用されます（_workflowListStatusFilter が設定されます）。その場合、nextPaginationToken があるのにページが空でも、ページ送りを続けてください。

入力の仕様

workflow_run の inputs オブジェクトは、レコードからそのまま取得した inputs[].name をキーとします。それぞれの名前は、その入力の背後にあるノードの ID なので、名前は位置を示すもの（text2、text3 など）である場合があり、連番でも順序どおりでもありません。

• label と description は人間にとっての意図を示すものであり、キーではありません。
• editorInfo.nodes[].data.name からキーを取得しないでください。ノード名は古くなります。
• required はオブジェクトです。required.always === true をテストしてください。truthy チェックでは {"always": false} も必須として扱われてしまいます。
• 入力には string、file、file_array、string_array などの型があります。file にはアセット ID を指定します（先にアップロードしてください）。型を一致させてください。API はスカラーと配列の型が一致しない場合、何も通知せずに破棄し、それでも課金します。workflow_run は単純なスカラー値を配列にラップしますが、対象は単純なものに限られます。
• inputs[] だけでは仕様全体を把握できません。文字列入力には、その背後にあるノードの長さ制限（モデル独自のプロンプト上限。確認された最小値は 4000 文字）が適用されますが、この制限はレコードに記載されず、実行時にのみ、上限を示す一方で入力キーは示さない 400 エラーとして表面化します。ドライランでは同じバリデーターがコストゼロで実行されます。長いテキストは dry_run=true で処理し、同じ内容のまま再試行するのではなく、上限に収まるよう短くしてください。また、文字列入力が複数ある場合は、ドライランで二分探索して問題の入力を見つけてください。
• workflow_get は inputs_definition／editor_info を workflow 内にラップします。workflows_list は inputs／editorInfo を workflows 内にラップします。

実例：保存済みアプリを実行する

1. workflows_list に status="ready"、limit=3、および team_id と project_id を指定します。各レコードから id、name、inputs を読み取り、flow と editorInfo は無視します。
2. inputs[] のエントリーが {"name": "text1", "required": {"always": false}} の場合、{"text1": "..."} を指定して実行します。
3. workflow_id、dry_run=true、完全な inputs オブジェクトを指定して workflow_run を呼び出します。応答には creativeUnitsCost、creativeUnitsDiscount、空の job が含まれます。まずコストを提示してください。実際のバリデーターも実行されます。
4. dry_run なしで再度実行し、返されたジョブに対して jobs_wait を呼び出します。実行中は pending_job_ids を指定して再度呼び出します。
5. 出力アセットごとに、ID を 1 つずつ指定して asset_display を呼び出します。

よくある間違い

• inputs[] を読む代わりに、ラベルやノードグラフから入力キーを推測する。
• ドライランを省略する。ready 状態のワークフロー 3 件のうち 2 件は、入力名が正しく示されたバリデーションエラーで失敗しました。ペイロードではなく、そのエラーを報告してください。
• 親ジョブからコストやアトリビューションを読み取る。完了したワークフロージョブでは cuCost: 0 が請求され、assetIds は列挙されますが、モデルごとのアトリビューションはありません。各ノードは実際の cuCost を持つ子ジョブとして実行されます（合計はドライランの見積もりと一致します。ただし、forEach ループ内ではドライランは 1 回分の反復を見積もります）。ワークフロージョブに対して job_get を verbose=true で呼び出すと、metadata.flow に各ノードとその子 jobId、modelId、出力アセット ID の対応が返されます。
• file_array 入力にまとめて送信し、項目ごとに出力が 1 つずつ得られると期待する。アプリがループするかどうかは入力ではなくグラフで決まります。editorInfo でモデルより前に forEach ノードがあるか確認してください（コンパイル済みの flow では for-each。workflows_list のレコードには両方が含まれるか、workflow_get を使います）。ない場合、アプリはすべての項目を使って 1 回だけ生成するため、項目ごとに workflow_run を 1 回呼び出します（それぞれ個別のドライランとジョブが必要です）。ループするアプリのドライランは 1 回分の反復を見積もるため、見積もり額に項目数を掛けてください。
• ドラフトを実行する。inputs が完全に見えていても、flow: [] かつ hasFlow: false である場合があります。公開については scenario-workflow-authoring を参照してください。
• workflow_id、workflow_job_id、node_id の 3 つすべてを指定せずに workflow_approve または workflow_reject を呼び出す。承認ゲートはノードごとにあり、保留中の実行は自動では完了しません。jobs_list で実行を見つけ、job_get を verbose=true で呼び出して読み取ります（コンパクトな応答では metadata が省略されます）。metadata.flow にノードごとのステータスが列挙され、承認待ちノードの ID が node_id、ジョブの ID が workflow_job_id、その workflowId が workflow_id です。拒否すると実行はキャンセルされます。