# 設計ガイド

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

工程や登録 Agent が何なのかは[プロジェクトと工程](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/concepts/project-and-steps.md)にあります。先に読んでおくと、ここでの判断が速くなります。工程に置く登録 Agent の設定は[エージェントガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md)にあります。

## 業務として決めること

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

- **どこまで任せるか。** 手がかりは 3 つです。**間違えたときに戻せるか**——戻せない操作（外部への書き込みなど）をする Agent の前には、確認工程を置きます（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/review-guide.md)）。外部への効果は、契約の「外部への効果」で分かります（[エージェントガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md#%E5%A5%91%E7%B4%84%E3%81%AE%E8%A6%81%E7%B4%84%E3%82%92%E8%AA%AD%E3%82%80)）。**判断の基準を文章にできるか**——文章にできない判断は人に残します。**必要な情報に手が届くか**——要る情報とつなぐ先を洗い出し、通信が許可されているかを作り始める前に確かめます（[実行ルールと通信ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/control-guide.md#%E5%A4%96%E3%81%B8%E3%81%AE%E9%80%9A%E4%BF%A1%E3%82%92%E7%B5%9E%E3%82%8B)）
- **何ができたら終わりか。** 業務としての終わりを先に決め、確認担当者が進めるかを決める基準に落とします。実行の結果の読み方は[記録と指標](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/concepts/records-and-metrics.md)にあります
- **どこでプロジェクトを分けるか。** 見せてよい相手、使う連携先、許す操作のどれかが違う業務は、プロジェクトを分けます。1 つの環境で持てるプロジェクトは 5 件までです（消したもの・アーカイブしたものは数えません。[設定値リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/reference/settings-ref.md)）
- **結果をどこへ届けるか。** 人が受け取るなら、ワークフローの最後に確認工程を置きます。外部の仕組みへ渡すなら、外部 API で結果を読むか、登録 Agent が連携先に書く作りにします（[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md)）

## 型を選ぶ

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

|          | サイクル                       | ワークフロー                  |
| -------- | -------------------------- | ----------------------- |
| 終わり方     | 開始も終了もなく、続く                | 開始から終了へ、工程を順に進む（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 で差し戻されれば、戻り先の工程からやり直します。**分けるのは、進行を区切りたいところです。** 区切ると、その切れ目に次のことを置けます。

- **人の判断を挟む** → 確認工程を置きます。**案件はそこでいったん止まり**、確認担当者の決定（外部条件待ちなら条件の成立）で進みます（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/review-guide.md)）
- **差し戻しの戻り先にする** → やり直しをどこから始めるかを、工程の単位で指定します
- **時刻を待たせる** → 工程に時刻を持たせられます。指定しなければ前の工程が終わり次第すぐ動きます（[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md#%E5%B7%A5%E7%A8%8B%E3%81%94%E3%81%A8%E3%81%AE%E6%99%82%E5%88%BB%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC)）

**担当を分けるときは、前の Agent の結果を使うかで決めます。** 1 つの工程に複数の Agent を置くと、配置順に 1 体ずつ動きます。**前に動いた Agent の出力は、自動では渡りません。** 次の Agent に使わせたい出力は、先に動く配置の出力として、入力ファイルにつなぎます（[エージェントガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md#%E5%B7%A5%E7%A8%8B%E3%81%AE%E8%A8%AD%E5%AE%9A%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC)）。配置は並列には動かず、配置順に 1 体ずつ動きます。

### サイクルで分けるとき

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

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

**サイクルの Agent は、1 回の処理が終わったら終了する作りでなければなりません。** 終了しないと、その配置の次の回が見送られ続けます（[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md#%E3%82%B5%E3%82%A4%E3%82%AF%E3%83%AB%E3%82%92%E5%9B%9E%E3%81%99)）。

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

## 条件分岐の工程（ワークフロー）

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

- **条件は上から順に確かめ**、最初に当てはまった条件の進む先へ進みます。どの条件にも当てはまらないときは、「どの条件にも当てはまらないとき」の設定に従います
- 判定対象は、結果の文・結果のJSON・成果物・工程の実行などです。**使える判定の方法は、結果の文・結果のJSON・成果物・工程の実行を見る条件です**
- 条件の数やレーンの数などの上限は、SaaS 版と同じです（[SaaS 版の設定値リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/settings-ref.md)）

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

## 登録 Agent を工程に置く

登録 Agent を置く手順と、置いたあとに決める工程の設定・環境変数は、[エージェントガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md)にあります。判断の目安は次のとおりです。

- **置けるのは、認定済みの登録 Agent だけです**（ワークフロー）。未認定なら、管理者に契約と認定の登録を頼みます
- **同じ登録 Agent を、別の工程にも置けます。** 配置ごとに、別の設定値と連携先を持てます
- **登録 Agent の動きは、プロジェクトでは変えられません。** 変えたい内容で頼む先が決まります（[エージェントガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md#agent-%E3%81%AE%E5%8B%95%E3%81%8D%E3%82%92%E5%A4%89%E3%81%88%E3%81%9F%E3%81%84%E3%81%A8%E3%81%8D)）

## うまくいかなかったときどうするか（ワークフロー）

**登録 Agent の工程は、終わり方ごとに決まった扱いで動きます**。契約の「外部への効果」が「読み取りのみ」か「書き込み (再送しても同じ結果)」で、何が起きたかが分かっている失敗は、**自動でやり直し**、回数を使い切ると案件は失敗で閉じます。二重に書き込むおそれがあるもの（「書き込み (再送で重複しうる)」）や、実行上限による時間切れを含む、何が起きたか分からない終わり方は、自動ではやり直さず、確認依頼を作ります。ですから、**やり直してよい仕事かどうかを、Agent の契約の「外部への効果」で決めます**（詳しい一覧は[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md#%E3%81%86%E3%81%BE%E3%81%8F%E3%81%84%E3%81%8B%E3%81%AA%E3%81%8B%E3%81%A3%E3%81%9F%E3%81%A8%E3%81%8D)）。

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

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

## 公開と再利用

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

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

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

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

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

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

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

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

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

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

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

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

工程と配置の変更は、**下書き**として溜まります。**反映するまでプロジェクトは変わりません。** 反映した設定が効くのは次の実行からで、動いている実行には影響しません。ただし、登録 Agent を**初めて**工程に置いたときは、下書きに載らず、**その場でプロジェクトに保存されます**（[Agent ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md)）。

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

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

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

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

### 前のバージョンに戻す

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

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

## 取り違えやすいところ

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

## 次に読むもの

- [プロジェクトと工程](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/concepts/project-and-steps.md) — 工程と配置の考え方
- [エージェントガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/agent-guide.md) — 登録 Agent を置く
- [確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/review-guide.md) — 人の判断の置き方
- [起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md) — いつ動かし、どう止めるか
