# 確認ガイド

確認工程の考え方と、確認担当者の決め方は SaaS 版と同じです（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md)・[人の確認](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/concepts/human-review.md)）。このページは、マーケットプレイス版で違う点をまとめます。

|         | SaaS 版                      | マーケットプレイス版                |
| ------- | --------------------------- | ------------------------- |
| 確認方法    | 担当者の判断を待つ／期限後に自動で進める        | 担当者の判断を待つ／**外部条件待ち**      |
| 期限を過ぎたら | 通知して待つ・自動で進める・差し戻す・却下するから選ぶ | **自動では決めない**（通知して待つ）      |
| 次の工程の候補 | 2〜5 件                       | ない                        |
| 確認の対象   | 直前の工程の出力                    | 案件の**設定のバージョンと成果物のバージョン** |

## 確認工程で決まるのは「進めるかどうか」

確認工程は、**案件を次に進めてよいかを人が決める工程**です。**確認工程に着くと、案件はいったん止まります。** そのあとは、確認担当者の決定（または外部条件の成立）で進みます。

**Agent の操作そのものを止める仕組みではありません。** やってほしくない操作は、確認ではなく、Agent の作りと通信の制限で防いでください（[実行ルールと通信ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/control-guide.md)）。

**確認工程はワークフローのものです。** サイクルには置けません。

確認依頼の画面には、「確認内容のバージョン」と「次に実行する Agent」、成果物が出ます。決める前に、何が次の工程に渡るかを見られます（[案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md#%E7%A2%BA%E8%AA%8D%E5%BE%85%E3%81%A1%E3%81%A7%E7%9B%B4%E3%81%97%E3%81%A6%E3%81%8B%E3%82%89%E9%80%B2%E3%82%81%E3%82%8B)）。

画面上の場所 編集 ＞ 中央の図で確認工程を選ぶと、右に「確認の設定」が出ます

## 確認と手作業のどちらか

確認工程には**種類が 2 つ**あります。**その間に人がすることが違います。**

- **確認 (Agent の結果を人が判断する)** — 案件の成果物と設定を見て、**進める・差し戻す・却下する**のいずれかを決めます
- **手作業 (AI は実行せず、人が作業してから進める)** — その工程では Agent が動きません。**人が自分で作業を終えてから、次へ進めます**。Agent に任せない作業を業務の流れに組み込みたいときに使います

**どちらの種類でも、その工程では Agent は動きません。** Agent に動かしたい作業は、その前後に工程を分けて置いてください。

**確認の内容を直したいときは**、確認待ちのあいだに、オーナーが案件の設定や成果物を新しいバージョンにします（[バージョンに固定された確認](#%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%95%E3%82%8C%E3%81%9F%E7%A2%BA%E8%AA%8D)）。

画面上の場所 編集 ＞ 確認工程を選び、右の「確認の設定」＞「確認の種類」

## 決められるのは指定した人と、その代理人だけ

**確認担当者に指定された人と、その人が任せた期間中の代理人だけが決められます。** これは役割とは別で、**オーナーでも、その工程の確認担当者に指定されていなければ（代理人でもなければ）決められません**。確認担当者の欄にも、オーナーは「確認担当者に指定されている場合だけ回答できます」と出ます。

候補になるのは**プロジェクトのメンバー**です。**決めてほしい人は先にメンバーに加えます。** **メンバーから外すと、その人は確認担当者からも外れます。**

**複数人を指定できます。** ただし**最初の回答で確定します**。全員の同意を取る仕組みではないので、合議が必要なら、決めたうえで 1 人が代表して回答する形にしてください。

**確認担当者は、不在の間の決定を、同じ組織の 1 人に任せられます。** 個人の設定の「プロジェクト」の「確認依頼の代理人」で決めます。代理人にも通知が届き、代理人からさらに別の人へは任せられません。

**決まっていない確認依頼の担当は、オーナー・運用担当と組織の運用の役割の人が付け替えられます。** 案件の画面の「担当を付け替える」か、「対応待ち」の「担当の付け替え」で、選んだメンバーに置き換えます（[案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md#%E7%B7%A0%E3%82%81%E5%88%87%E3%82%8A%E3%81%A8%E7%A2%BA%E8%AA%8D%E3%81%AE%E6%8B%85%E5%BD%93)・[記録ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/record-guide.md#%E3%81%BE%E3%81%A8%E3%82%81%E3%81%A6%E6%93%8D%E4%BD%9C%E3%81%99%E3%82%8B)）。工程の確認担当者の設定は変わりません。

**有効な確認工程に確認担当者を選んでいないと、案件を開始できません。** 反映の前に「設定を検証」で確かめられます。

画面上の場所 編集 ＞ 確認工程を選び、右の「確認の設定」＞「基本設定」＞「確認担当者」。メンバーの追加は 設定 ＞「メンバー」。代理人は、個人の設定の「プロジェクト」

## 期限では決まらない

**登録 Agent で動く案件では、期限を過ぎても確認は自動で決まりません。** 期限を過ぎると、確認担当者（と、設定していれば期限超過時の連絡先）に知らせ、そのまま判断を待ちます。

期限で進めたい業務は、確認担当者が期限内に決める運用にしてください。

確認依頼と期限超過のメールは、SaaS 版と同じく確認担当者に届きます。送信には、管理コンソールの「お知らせと通知」＞「通知設定」＞「メールプロバイダー設定」のタブで決めた送信手段と送信元が使われます。**メールプロバイダーが設定されていないと、メールは送られません**（[設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md)）。

## バージョンに固定された確認

確認依頼には、「**確認内容のバージョン**」と「**次に実行する Agent**」、成果物が出ます。**確認担当者は、そのバージョンの設定と成果物に対して判断します。**

確認待ちのあいだに、オーナーが案件の設定を新しいバージョンにすると、確認の内容も新しいバージョンに置き換わります。成果物は、次の工程に渡すバージョンが編集元だったときに、新しいバージョンに切り替わります（そうでないときは、案件の設定で渡すバージョンを選び直します）。（[案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md#%E7%A2%BA%E8%AA%8D%E5%BE%85%E3%81%A1%E3%81%A7%E7%9B%B4%E3%81%97%E3%81%A6%E3%81%8B%E3%82%89%E9%80%B2%E3%82%81%E3%82%8B)）。確認担当者は、置き換わった内容を見て判断し直します。

**確認担当者に指名されても、オーナーでなければ案件の設定や成果物は直せません。** 直してほしいときは、差し戻すか、オーナーに頼んでください。

## 外部条件待ち

「**外部条件待ち**」は、人ではなく外部サービスの状態で次の工程へ進める確認方法です。**登録 Agent を置いたワークフローでだけ使えます。** 今使える外部条件は「**GitLabのMRのマージ**」の 1 つです。前の工程の Agent が作った MR が、期待したバージョンのままマージされたら、次の工程へ進みます。

### 設定する

確認工程の確認方法で「外部条件待ち」を選び、3 つの欄を入れます。

| 欄              | 入れるもの                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------- |
| **外部条件**       | 「GitLabのMRのマージ」                                                                                     |
| **観測に使用する連携先** | MR を読むための GitLab の連携先。このプロジェクトの連携先から選びます                                                            |
| **対象を示す出力**    | 前の工程の登録 Agent の、JSON 形式の出力。中身は `{"gitlab_project_id": …, "mr_iid": …, "expected_head_sha": "…"}` です |

`expected_head_sha` は 40 桁の 16 進数（コミットの SHA）です。この出力を作るのは Agent の仕事です。契約の出力に、この形式の JSON を宣言した Agent を前の工程に置いてください（[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md)）。

### 進み方

- 対象の MR が、`expected_head_sha` のバージョンのままマージされると、**自動で次の工程へ進みます。** 決定は「外部条件の成立で進行」と記録され、人の承認とは区別されます
- **確認担当者は進められません。** できるのは差し戻しと却下だけです（「外部条件の成立で進む確認です。人は進められません (差し戻し・却下はできます)」）
- まだマージされていないとき、期待と違うバージョンでマージされたときは、成立せずに待ち続けます
- 状態は 300 秒ごとに読み直します。案件の画面の「進行」に、対象・最終観測・観測したバージョン・次の観測が出ます

### 確かめられないとき

連携先や対象を示す出力が設定されていない、出力の形式が読めない、といった理由で条件を確かめられないときは、**確認担当者の判断を待つ確認に戻ります。** 案件の画面に保留の理由が出ます。

| 保留の理由                                                  | 直すところ                    |
| ------------------------------------------------------ | ------------------------ |
| 外部の条件を確認するのに使用する連携先が、このプロジェクトに追加されていません。「連携先」で追加してください | 設定の連携先に、GitLab の連携先を追加する |
| この外部の条件の確認方法には対応していません                                 | 確認工程の外部条件の設定を見直す         |
| 外部の条件で確認する対象をどの出力から参照するかが、工程に設定されていません                 | 確認工程の「対象を示す出力」を設定する      |
| 前の工程の Agent が、確認する対象を示す出力を作成しませんでした                    | Agent の出力を確かめる           |
| 確認する対象を示す出力の形式を読み取れませんでした                              | Agent の出力の JSON を確かめる    |
| 外部の条件を確認できないため、確認担当者の判断を待っています                         | 確認担当者が、内容を見て判断する         |

接続の認証が通らない・対象が見つからない・連携先が使えないときは、30 分おいて読み直します。最初の 1 回だけ通知します。外部サービスにつながらない・応答が遅いといった一時的な障害のときは、1 分から最大 60 分まで間隔を広げながら読み直します（通知はしません）。

### GitLab からの Webhook で早く進める

300 秒ごとの読み直しを待たずに進めたいときは、GitLab の Webhook を使います。

1. オーナーが、プロジェクトの設定の連携先で「**外部条件待ちのWebhook秘密鍵**」に 16〜255 文字の値を入れて保存します。保存した値は表示されません

2. GitLab のプロジェクトの Webhook に、次を登録します

   <!-- -->

   - URL: `https://<環境のドメイン>/api/connect/<プロジェクトの ID>/<連携先の ID>`
   - Secret token: 1 で入れた値
   - トリガー: Merge request events

3. MR がマージされると、Webhook を受けた時点で状態を読み直します

プロジェクトの ID は、プロジェクトの画面の URL（`/p/projects/<プロジェクトの ID>`）にあります。連携先の ID は、観測に使用する連携先の OAuth プロバイダーの ID です。管理者に確かめてください。 URL・ID・秘密鍵のどれかが合わないと、Webhook は `404` で断られます。

**Webhook の内容だけでは進みません。** Webhook は読み直しのきっかけで、進めるかどうかは連携先で MR を読んで決めます。

秘密鍵を**消去**すると、新しい秘密鍵を保存するまで Webhook を受け付けません（300 秒ごとの読み直しは続きます）。**置き換える**と、古い秘密鍵の Webhook はすぐに受け付けなくなるので、GitLab 側の Secret token も同じ値に更新してください。

## 決めたあと、どうなるか

- **進める** — 次の工程へ進みます。最終の工程の後なら、案件が完了します
- **差し戻す** — 理由を添えて、戻り先の工程からやり直します。差し戻した確認依頼は、戻り先が動くまで「対応待ち」に「差し戻し待ち」として並びます
- **却下する** — その案件は却下で閉じます

**閉じた案件をやり直すときは、新しく案件を開始します。**

確認の決定は、確認した**バージョン**に対して行われます。確認のあいだに内容が新しいバージョンに置き換わっていると、古いバージョンを見て決めた操作は受け付けられません。置き換わった内容を見て、もう一度決めてください。

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

- **オーナーなら確認を決められると思う。** 決められるのは、確認担当者に指定された人と、その代理人だけです
- **確認期限を過ぎたら自動で進むと思う。** 進みません。期限を過ぎても、確認担当者の判断を待ちます
- **確認のあいだにオーナーが直した内容を、決める前に見なくてよいと思う。** 内容が置き換わるので、決める前に確かめてください
- **外部条件待ちの確認を、人が進められると思う。** 人ができるのは差し戻しと却下だけです

## 次に読むもの

- [案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md) — 確認待ちで設定や成果物を直す
- [記録ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/record-guide.md#%E5%AF%BE%E5%BF%9C%E5%BE%85%E3%81%A1%E3%81%A7%E4%BA%BA%E3%81%AE%E6%89%8B%E3%81%8C%E8%A6%81%E3%82%8B%E3%82%82%E3%81%AE%E3%82%92%E7%89%87%E4%BB%98%E3%81%91%E3%82%8B) — 対応待ちで確認依頼を片付ける
- [起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md) — 案件を始める・止める
