YAMLでJinba Flowのワークフローマニフェストを記述する

フローマニフェストは、フロー名とステップ一覧を含むYAMLドキュメントです。各ツールステップにはID、ツールID、入力リストを指定します。入力や設定に指定できる値は、各ツールのドキュメントで確認してください。

実行できる例

テキストを受け取り、挨拶文として返すフローです。

name: First workflow
steps:
  - id: name
    tool: INPUT_TEXT
    input:
      - name: value
        value: Jinba

  - id: greeting
    tool: OUTPUT_TEXT
    needs:
      - name
    input:
      - name: value
        value: "Hello, {{ steps.name.result }}!"

フローとステップのフィールド

フィールド	対象	用途
`name`	フロー	必須のフロー名
`description`	フロー	フローの内容を説明する任意の文
`steps`	フロー	必須のステップ一覧
`id`	ステップ	必須の一意な識別子。英字、数字、アンダースコア、ハイフンを使用。`__proto__`、`constructor`、`prototype`は予約語
`name`	ステップ	エディターに表示する任意の表示名
`description`	ステップ	ステップの処理内容を説明する任意のメモ
`tool`	ツールステップ	Jinba FlowのツールカタログにあるツールID
`input`	ツールステップ	ツールが受け付ける`name`と`value`の組の一覧
`config`	ツールステップ	任意のツール固有設定値の一覧
`needs`	ステップ	実行前に完了している必要があるステップのID
`when`	ステップ	任意のCEL式。結果が偽の場合はステップをスキップ
`forEach`	ステップ	配列を要素ごとに処理する任意の式

ツールステップには、値を渡さない場合でもinputが必要です。入力のないツールではinput: []を指定します。選択したツールがサポートするフィールドだけを含めてください。

ツールを設定する

configはinputと同じくnameとvalueの一覧で指定します。設定値ではシークレットを参照できますが、ステップの結果は参照できません。

config:
  - name: <config_name>
    value: "{{ secrets.<SECRET_NAME> }}"

実行順序を決める

ステップの実行順序は、ファイル内の並び順ではなくneedsで決まります。needsのないステップは同時に開始されます。

ステップはneedsに挙げたすべてのステップの完了を待ちます。入力でsteps.<id>を参照しただけでは待たないため、そのIDをneedsに追加してください。
処理を分岐させ、再び合流させることもできます。同じ前段ステップに依存する2つのステップを、別のステップのneedsにまとめて指定できます。
循環する依存関係はFlow contains circular dependenciesとして拒否されます。
needsのステップが失敗またはキャンセルされると、依存するステップはキャンセルされます。needsのステップがすべてスキップされた場合は、依存するステップもスキップされます。

前のステップの結果を渡す

ステップIDとそのresultを使って、前のステップの出力を参照します。結果の形式はツールによって異なるため、ネストしたフィールドを使う場合は該当ツールのドキュメントを確認してください。

  - id: greeting
    tool: OUTPUT_TEXT
    needs: [name]
    input:
      - name: value
        value: "Hello, {{ steps.name.result }}!"

needsに依存関係を明示します。ステップIDはフロー入力の識別にも使われます。公開済みフローを呼び出すときは、入力ステップのIDを引数名に指定します。テンプレートで使える値:

参照	値
`{{ steps.<step_id>.result }}`	前のステップの結果全体
`{{ steps.<step_id>.result.<field> }}`	結果の特定のフィールド。配列の要素は`[0]`で指定
`{{ secrets.<SECRET_NAME> }}`	ワークスペースのシークレット
`{{ item }}`、`{{ itemIndex }}`、`{{ itemCount }}`	`forEach`ステップでの現在の要素、0から数えた位置、配列の長さ

{{ steps.<step_id>.result... }}のプレースホルダーがオブジェクトや配列を指す場合は、JSONテキストとして挿入されます。文字列はそのまま挿入され、値がない場合は空文字列になります。その他のパターンは変数とテンプレートを参照してください。

条件とループ

条件にはCEL式を直接指定します。次の例では、前のステップの結果にあるisValidが真の場合に実行します。

when: "steps.check.result.isValid"

条件には{{ }}のプレースホルダーも使えます。先に値が埋め込まれ、その結果のテキストがCEL式として評価されるため、文字列の値は引用符で囲みます。

when: "'{{ steps.check_genre.result.content }}' == 'General'"
when: "{{ steps.count_items.result }} > 5"

存在しないフィールドを参照しているなどの理由で条件を評価できない場合、ステップはFailed to evaluate when condition on step '<step_id>'で失敗します。 forEachを使うと、配列の各要素に対してステップを実行できます。対応する式では現在の要素をitemとして参照できます。

forEach: "{{ steps.get_items.result }}"

後続のステップでsteps.<step_id>.resultを参照すると、成功した要素の結果の配列が返ります。needs、when、forEachのその他の例はステップモジュールオプションを参照してください。

テンプレート

入力値は、ステップの実行前にNunjucksテンプレートとして展開されます。{{ }}のプレースホルダーに加えて、ループ、条件分岐、フィルターを使えます。

- name: prompt
  value: |
    Review these items:
    {%- for entry in steps.get_items.result.items %}
    - {{ entry.name }}
    {%- endfor %}
    {%- if steps.check.result.status == 'urgent' %}
    Flag anything that needs a reply today.
    {%- endif %}

{%-と-%}は、タグの前後の空白を取り除きます。
ループ内のloop.indexは1から数えた位置です。
組み込みフィルターにはdefault('<fallback>')、upper、lower、trim、replace('<old>', '<new>')、length、join(', ')などがあります。
jsonは厳密なJSONを出力します。フィルターを付けたプレースホルダーは自動ではJSONに変換されないため、値がオブジェクトの場合は| jsonを付けてください。
forEachの結果には、successful、failed、results、pluck('<field>')で要素ごとの出力を絞り込んだり取り出したりできます。

Pythonのzip()や、for x in items if ...のようなループ内の絞り込みはサポートされていません。代わりにループ内で{% if %}ブロックを使ってください。

複数行の値

コードやプロンプトなど複数行にわたる値には、YAMLの|を使います。値はインデントが終わるまで続きます。|-も同じですが、末尾の改行を取り除きます。

例: 分岐して結果をまとめる

数値のリストを読み込み、偶数の合計と奇数の合計を並列に計算して、結果をまとめるフローです。

name: Sum numbers
steps:
  - id: input_data
    tool: INPUT_JSON
    input:
      - name: value
        value: '{"numbers": [1, 2, 3, 4, 5]}'

  - id: sum_even
    tool: PYTHON_SANDBOX_RUN
    needs: [input_data]
    input:
      - name: code
        value: |
          data = {{ steps.input_data.result }}
          sum(x for x in data["numbers"] if x % 2 == 0)
      - name: data_type
        value: NUMBER

  - id: sum_odd
    tool: PYTHON_SANDBOX_RUN
    needs: [input_data]
    input:
      - name: code
        value: |
          data = {{ steps.input_data.result }}
          sum(x for x in data["numbers"] if x % 2 != 0)
      - name: data_type
        value: NUMBER

  - id: combine
    tool: PYTHON_SANDBOX_RUN
    needs: [sum_even, sum_odd]
    input:
      - name: code
        value: "{{ steps.sum_even.result.data }} * 2 + {{ steps.sum_odd.result.data }}"
      - name: data_type
        value: NUMBER

input_dataは、解析済みのJSONオブジェクトを返します。
sum_evenとsum_oddはどちらもinput_dataだけに依存するため、同時に実行されます。コードの最終行が結果となり、result.dataで参照できます(6と9)。
combineは両方の分岐の完了を待ち、21を返します。

マニフェストを検証する

フローの検証や実行に失敗する場合は、次を確認してください。

各ステップIDが一意で、英字、数字、アンダースコア、ハイフンだけを使っている
ツールIDと入力名が、該当ツールのドキュメントに記載されている
参照先のステップIDが存在し、needsに含まれている
結果の参照先が、そのツールの出力形式と一致している
YAMLのインデントがそろっている

ツールIDと入力はツール一覧を、検証エラーのメッセージはデバッグを参照してください。

​実行できる例

​フローとステップのフィールド

​ツールを設定する

​実行順序を決める

​前のステップの結果を渡す

​条件とループ

​テンプレート

​複数行の値

​例: 分岐して結果をまとめる

​マニフェストを検証する