メインコンテンツまでスキップ

設計ガイド

プロジェクトを 1 つ作るということは、業務の進め方を 1 つ決めることです。このガイドでは、業務として何を決め、それをどう工程に分け、それぞれの工程に何を任せるかを決めるための選択肢と基準を扱います。

工程や登録 Agent が何なのかはプロジェクトと工程にあります。先に読んでおくと、ここでの判断が速くなります。工程に置く登録 Agent の設定はエージェントガイドにあります。

業務として決めること​

型・工程・Agent を決める前に、業務として 4 つを決めます。

  • どこまで任せるか。 手がかりは 3 つです。間違えたときに戻せるか——戻せない操作(外部への書き込みなど)をする Agent の前には、確認工程を置きます(確認ガイド)。外部への効果は、契約の「外部への効果」で分かります(エージェントガイド)。判断の基準を文章にできるか——文章にできない判断は人に残します。必要な情報に手が届くか——要る情報とつなぐ先を洗い出し、通信が許可されているかを作り始める前に確かめます(実行ルールと通信ガイド)
  • 何ができたら終わりか。 業務としての終わりを先に決め、確認担当者が進めるかを決める基準に落とします。実行の結果の読み方は記録と指標にあります
  • どこでプロジェクトを分けるか。 見せてよい相手、使う連携先、許す操作のどれかが違う業務は、プロジェクトを分けます。1 つの環境で持てるプロジェクトは 5 件までです(消したもの・アーカイブしたものは数えません。設定値リファレンス)
  • 結果をどこへ届けるか。 人が受け取るなら、ワークフローの最後に確認工程を置きます。外部の仕組みへ渡すなら、外部 API で結果を読むか、登録 Agent が連携先に書く作りにします(起動ガイド)

型を選ぶ​

最初に決めるのは型です。

サイクルワークフロー
終わり方開始も終了もなく、続く開始から終了へ、工程を順に進む(1 件が案件)
工程に置けるもの会話で使う登録 Agent(契約・認定は要りません)契約を登録し、認定済みの登録 Agent
始め方配置ごとの周期、Webhook手動(案件を開始)、時間、外部 API

プロジェクトを作る画面の既定はワークフローです(API で型を省略して作ると、サイクルになります)。 基準は「終わりがあるか」です。1 件ごとに始まって終わるなら、ワークフローです。1 件ごとに結果を追えて、確認工程で案件そのものをいったん止められます。終わりがなく、動き続けるならサイクルです。配置がそれぞれの周期で動き、全体の始まりも終わりもありません。確認工程・条件分岐の工程を置けるのは、ワークフローだけです。

画面上の場所 プロジェクトを作るとき > 種別

工程に分ける​

工程の分け方は、型によって考え方から違います。

ワークフローサイクル
向く仕事1 件を受けて、決まった順に処理して仕上げる対象を拾って処理し続ける
進み方工程の並びが順序。前の工程が終わってから次へ進む配置がそれぞれの周期で独立に動く。並びは順序にならない
段階のつなぎ方ファイルをつないだときだけ、前の工程の出力が渡る工程の間で出力は渡らない

工程を指定せずにプロジェクトを作ると、ワークフローでは 3 つ(Agent を置く工程・確認工程・Agent を置く工程)、サイクルでは 2 つが用意されます。工程の名前に、製品側の決まりはありません。 業務に合う名前を付けてください。名前によって進み方が変わることはありません。

ワークフローで分けるとき​

ワークフローは、1 件の仕事を受けて仕上げる型です。工程の並びが処理の順序になり、前の工程が終わってから次へ進みます。条件分岐の工程では、選ばれたレーンだけを通ります。

たとえば、届いた書類を 1 件ずつ処理して返すワークフローを考えます。

  1. 内容を確かめる — 登録 Agent が、書類の記載と添付を確かめる
  2. 人が承認する — 確認担当者が成果物を見て、進めるか差し戻すかを決める
  3. 登録して返す — 別の登録 Agent が、承認されたものを登録して返す

1 件が 1 → 2 → 3 と進み、終わります。 2 で差し戻されれば、戻り先の工程からやり直します。分けるのは、進行を区切りたいところです。 区切ると、その切れ目に次のことを置けます。

  • 人の判断を挟む → 確認工程を置きます。案件はそこでいったん止まり、確認担当者の決定(外部条件待ちなら条件の成立)で進みます(確認ガイド)
  • 差し戻しの戻り先にする → やり直しをどこから始めるかを、工程の単位で指定します
  • 時刻を待たせる → 工程に時刻を持たせられます。指定しなければ前の工程が終わり次第すぐ動きます(起動ガイド)

担当を分けるときは、前の Agent の結果を使うかで決めます。 1 つの工程に複数の Agent を置くと、配置順に 1 体ずつ動きます。前に動いた Agent の出力は、自動では渡りません。 次の Agent に使わせたい出力は、先に動く配置の出力として、入力ファイルにつなぎます(エージェントガイド)。配置は並列には動かず、配置順に 1 体ずつ動きます。

サイクルで分けるとき​

サイクルは、対象を拾って処理し続ける型です。登録 Agent はそれぞれの周期で独立に起動し、ほかの工程が終わるのを待ちません。だから 1 つが止まっても、残りは動き続けます。

段階が 1 つでも構いません。 決まった間隔で見に行き、必要があれば手を打つ——それだけなら段階を分ける必要はありません。工程を指定せずに作ると 2 つ用意されますが、使わない工程は無効にします(サイクルのクイックスタート)。サイクルに確認工程は置けません。 人の判断を挟みたいなら、ワークフローを選びます。サイクルの工程は、担当の分類です。 番号も矢印もつかず、順に進めたいならワークフローの型です。

サイクルの Agent は、1 回の処理が終わったら終了する作りでなければなりません。 終了しないと、その配置の次の回が見送られ続けます(起動ガイド)。

画面上の場所 編集 > 左の「編集ツール」>「工程を追加」。1 つ 1 つの設定は、中央の図で工程を選ぶと右に出ます

条件分岐の工程(ワークフロー)​

条件分岐の工程は、前の工程の結果を読んで、進むレーンを決めます。 Agent は置きません。条件ごとに、当てはまったときの進む先を、レーンか「何もせずに合流」から選びます。選ばれたレーンの工程だけを上から順に実行して、合流の後ろの工程へ進み、ほかのレーンの工程は実行しません。

  • 条件は上から順に確かめ、最初に当てはまった条件の進む先へ進みます。どの条件にも当てはまらないときは、「どの条件にも当てはまらないとき」の設定に従います
  • 判定対象は、結果の文・結果のJSON・成果物・工程の実行などです。使える判定の方法は、結果の文・結果のJSON・成果物・工程の実行を見る条件です
  • 条件の数やレーンの数などの上限は、SaaS 版と同じです(SaaS 版の設定値リファレンス)

ワークフローの工程は、登録 Agent を置く工程・確認工程・条件分岐で作ります。

登録 Agent を工程に置く​

登録 Agent を置く手順と、置いたあとに決める工程の設定・環境変数は、エージェントガイドにあります。判断の目安は次のとおりです。

  • 置けるのは、認定済みの登録 Agent だけです(ワークフロー)。未認定なら、管理者に契約と認定の登録を頼みます
  • 同じ登録 Agent を、別の工程にも置けます。 配置ごとに、別の設定値と連携先を持てます
  • 登録 Agent の動きは、プロジェクトでは変えられません。 変えたい内容で頼む先が決まります(エージェントガイド)

うまくいかなかったときどうするか(ワークフロー)​

登録 Agent の工程は、終わり方ごとに決まった扱いで動きます。契約の「外部への効果」が「読み取りのみ」か「書き込み (再送しても同じ結果)」で、何が起きたかが分かっている失敗は、自動でやり直し、回数を使い切ると案件は失敗で閉じます。二重に書き込むおそれがあるもの(「書き込み (再送で重複しうる)」)や、実行上限による時間切れを含む、何が起きたか分からない終わり方は、自動ではやり直さず、確認依頼を作ります。ですから、やり直してよい仕事かどうかを、Agent の契約の「外部への効果」で決めます(詳しい一覧は起動ガイド)。

立て直すときは、新しく案件を開始するか、確認待ちなら差し戻して途中の工程からやり直すかを決めます。

画面上の場所 やり直しの回数は 設定 >「実行ルール」の「工程ごとの再試行回数 (失敗・時間切れ)」(登録 Agent の工程で効くのは最大 2 回)

公開と再利用​

プロジェクトは公開できます。 公開すると、ほかの利用者が、その工程と登録 Agent の配置を自分のプロジェクトにコピーして使えます。

コピーしたプロジェクトでは、次のものを確かめてください。

  • 工程・登録 Agent の配置・工程の設定・実行ルールの上限は写されます
  • 連携先は、一覧が写されます。接続(認証)は写されないので、コピーしたプロジェクトで接続し直します
  • 時間トリガーは写されますが、無効の状態で来ます。開始する工程は設定し直します
  • サイクルのコピーには、確認工程は作られません

プロジェクトを作る画面で選べる方法は 3 つです。 「自分で作る」「社内のひな形から作る」「ファイルから取り込む」。今あるプロジェクトは、プロジェクトの画面とカードの「複製する」(オーナーだけ)や、公開プロジェクトの「自分のプロジェクトにコピー」で写せます。登録 Agent は管理者が登録します。

定義を書き出す・取り込む・社内のひな形にする​

プロジェクトの定義(工程・登録 Agent の配置・時間トリガー・連携先)は、ファイルにして別の環境へ持っていくことも、社内のひな形として公開することもできます。書き出しとひな形の公開は、設定 タブから行います。取り込みとひな形から作るは、プロジェクトを作るときの「どのように作りますか」から始めます。

書き出せるのはオーナーだけです。 設定 タブの「定義を書き出す」で、確定している定義が JSON のファイルに保存されます。接続の認証情報・確認担当者・環境変数の値、時間トリガー以外の起動(Webhook など)は含まれません。

取り込む定義に、この環境で使えない機能(外部の自動化の工程・結果ごとの次の工程・確認で選ぶ次の工程・通知するだけの確認・期限の後の自動の扱い・次の工程に渡す値と資料の役割・並列のレーンと「同時に実行」・ライブラリの対応づけ・質問で判定の条件)が含まれているときは、その部分は外れて取り込まれ、外れたことが取り込みの結果で知らされます。 サイクル型の定義の時間トリガーも、同じく外れます(サイクル型は、配置ごとの巡回で時刻に動かします)。

トリガー・工程の時刻・有効な巡回を含む定義は、「定期実行の作成」を許されていない人には取り込めません(そのひな形から作ることもできません)。

社内のひな形は、決めた欄だけを使う人に入れてもらう型です。 公開するのはオーナーだけです。使用する人が入力する欄に、入力ファイルはありません(入力ファイルは、案件で選んで渡します)。

画面上の場所 作るとき>「どのように作りますか」>「ファイルから取り込む」「社内のひな形から作る」/設定 タブ>「定義を書き出す」「社内のひな形にする」

下書きを確かめて反映する​

工程と配置の変更は、下書きとして溜まります。反映するまでプロジェクトは変わりません。 反映した設定が効くのは次の実行からで、動いている実行には影響しません。ただし、登録 Agent を初めて工程に置いたときは、下書きに載らず、その場でプロジェクトに保存されます(Agent ガイド)。

テナントで定義の変更に承認を要る設定がオンのときは、反映した変更は、承認されるまで使われません。 初めての配置も承認待ちのバージョンになります。

反映する前に設定を検証できます。検証は下書きを含めて確認し、保存もしません。たとえば、Agent を置いていない有効な工程、確認担当者が未選択の確認工程、周期を決めていないサイクルの配置は、反映する前に直す点として出ます。検証で問題が出なかったからといって、実行が成功するとは限りません。

設定 タブ >「基本情報」は、下書きを使わず、保存した時点で変わります。 編集を始めたあとに別の操作でプロジェクトが更新されていたら、保存のときに知らせが出るので、「最新を読み込む」か「入力した項目を残す」を選びます。

画面上の場所 編集 の上部 >「設定を検証」「変更を反映」

前のバージョンに戻す​

反映した定義はバージョンとして残ります。 概要 タブの「プロジェクト情報」の「すべて表示」で開く「バージョン」で、バージョンごとの変更の中身を見られます。オーナーは、工程の設定を前のバージョンに戻せます。 戻すのは、今もある工程の設定だけで、そのバージョンの工程の設定が下書きに読み込まれてエディタが開きます。「変更を反映」で保存します。戻せるのは、稼働中と差し戻された(却下された)バージョンです。今の工程の設定と違いが無いときは、その旨が出て、何も読み込みません。

画面上の場所 概要 タブ >「プロジェクト情報」>「すべて表示」>「バージョン」> バージョンを選ぶ >「このバージョンに戻す」(広い画面のエディタで)

取り違えやすいところ​

  • サイクルの工程の並びが、実行の順番だと思う。 配置がそれぞれの周期で動きます
  • 前の工程の出力が、自動で次の工程に渡ると思う。 ファイルをつないだときだけ渡ります
  • 同じ工程に置いた Agent の出力が、自動で次の Agent に渡ると思う。 つないだファイルだけが渡ります
  • 失敗したらいつでも自動でやり直すと思う。 外部への効果が「書き込み (再送で重複しうる)」の Agent は、やり直さず確認依頼になります
  • Agent の動きを、プロジェクトで変えられると思う。 変えられるのは工程ごとの設定だけです

次に読むもの​