# 起動ガイド

起動の考え方は SaaS 版と同じです（[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/trigger-guide.md)）。このページは、マーケットプレイス版で違う点をまとめます。

## 型ごとに使えるもの

|           | ワークフロー                                                                                                                                                                                          | サイクル                             |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| 手動で始める    | 「**案件を開始**」（プロジェクトの参加者と組織の運用の役割の人）                                                                                                                                                              | できません                            |
| 決めた時刻に始める | 時間トリガー。**開始のときに設定値を渡せません**                                                                                                                                                                      | 巡回の周期を配置ごとに決めます                  |
| 外部から始める   | 外部 API（サービスアカウントのトークンか、プロジェクトの参加者と組織の運用の役割の人のアプリケーションのトークン）。実行の開始では設定値を渡せます。**Webhook トリガーの呼び出しでは渡せません**。オーナーが「外部公開（A2A・MCP）」で公開すると、管理者が受け口を開けた環境では、外部の Agent（A2A）や MCP のクライアントからも依頼文を付けて始められます | 外部 API で Webhook トリガーを呼びます（先に登録） |
| メールで始める   | できません                                                                                                                                                                                           | できません                            |

## 自動の起動を作る・有効にするには

**決めた時刻・Webhook・巡回で自動で始まる起動を作る・有効にするには、管理者が機能の許可で「定期実行の作成」を許している必要があります。** 許されていない人は、次の操作を断られます: トリガー（時間・Webhook）を作る・有効にする、工程の時刻（ワークフロー）を入れる・変える、巡回を有効にする・有効な巡回の周期を変える、これらを含む定義をファイルから取り込む・社内のひな形から作る。**すでにある起動は止まりません。** 止める・外す操作、工程の時刻を同じ値のまま保存する操作、有効なトリガーの設定を有効なまま変える操作は、許可が無くてもできます。有効な巡回の周期を変えるのは断られます。

**自動で動くものは、プロジェクトの区画の上部の「自動実行」に一覧で並びます。** 参加しているプロジェクトのトリガー・先頭の工程の時刻・巡回が、種類・所属・状態・次の起動とともに出ます。**工程の時刻は、ワークフローの最初の有効な工程の 1 つだけが並びます**（その工程に時刻が無ければ出ません）。有効な時間トリガーがあるプロジェクトでは、その時刻では始まらないので「無効」と出ます。作る・変える・止めるは、名前から開く各画面で行います。

画面上の場所 許可は管理コンソールの「接続先と使える範囲」＞「機能の許可」の「定期実行の作成」（システム管理者）。一覧はプロジェクトの区画の上部の「自動実行」

## ワークフローを始める

**画面から始めるときは「案件を開始」を使います。** 配置ごとの設定値・連携先・指示ファイルを、その案件のために入れられます（[案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md#%E6%A1%88%E4%BB%B6%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B)）。

**外部 API の実行の開始では、「案件を開始」と同じ設定値・連携先・入力ファイルを開始のときに渡せます**（`config`。[システム連携 API リファレンス — 実行の開始](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/api-reference.md#start-run)）。**時間トリガーと Webhook トリガーの呼び出しで始めた案件には、開始のときに設定値を渡せません。** そのときの各 Agent の設定値は、契約の標準値に工程の設定を重ねたものになります。外部 API で `payload` を付けると、その内容は依頼として最初の工程の Agent に渡ります。設定値にはなりません。依頼を使うかどうかは Agent の作りによります（[ワークフローガイド — 外から始めた run の依頼](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E5%A4%96%E3%81%8B%E3%82%89%E5%A7%8B%E3%82%81%E3%81%9F-run-%E3%81%AE%E4%BE%9D%E9%A0%BC)）。

**必須の設定値・連携先・入力ファイルが工程の設定（外部 API で `config` を渡したときは、それを重ねたもの）でそろっていないと、その案件は始まりません。**

- 時間トリガーでは、その回は始まらず、次の予定の時刻へ進みます
- 外部 API では、エラーが返ります

**時間トリガー・Webhook トリガーや、`config` を渡さない外部 API で動かすなら、必須の値はすべて工程の設定に入れておいてください**（[エージェントガイド](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)）。

外部 API は、次の 2 つのトークンで呼べます。

- サービスアカウントのトークン（システム連携）: 管理コンソールで作ります。サービスアカウントは、この環境のすべてのプロジェクトを対象に、許された操作を行えます（[システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/api-reference.md)）
- アプリケーションのトークン: 利用者が外部ツールでログインして得ます。管理者が外部ツールでのログインの入口を開けた環境でだけ使えます。案件を始める・Webhook トリガーを呼ぶのは、そのプロジェクトの参加者（オーナー・運用担当・メンバー）と組織の運用の役割の人です（[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#common-access)）。メイン画面にログインしたときのトークンでは呼べません

## サイクルを回す

巡回の周期の決め方は SaaS 版と同じです。マーケットプレイス版では、次の点が決まっています。

- **同じ配置が実行中のあいだに来た回は見送ります。** 積み上げて、あとからまとめて動かすことはしません
- **予定から 5 分を過ぎた回は、見送りとして 1 件だけ残し、次の予定へ進みます。** 環境が止まっていた間の回を、あとから全部動かすことはしません
- **同じ配置の前の実行が終わってから 60 秒は、次の巡回を見送ります。** Webhook の呼び出しは、60 秒待ってから起動します
- **同じ配置に起動を待っている Webhook の呼び出しがあるあいだも、巡回は見送ります**

**Agent が処理のあとに終了しないと、その配置の次の回がずっと見送られます。** 見送りが続くときは、Agent の開発者に終了の作りを確かめてもらってください（[はじめてのエージェント](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/quickstart/quickstart-sdk.md#exit-after-run)）。

## 工程ごとの時刻（ワークフロー）

**ワークフローでは、Agent を置く工程に動く時刻を持たせられます。** 選ぶのは 2 つです。

- **前の工程の完了後すぐ** — 既定です。前の工程が終わり次第動きます
- **所定の時刻に** — 前の工程が終わったあと、その時刻まで待ってから動きます

**時刻を待つのは、2 つ目以降の工程です。** 最初の有効な工程は、案件が始まるとすぐ動きます（その時刻は、案件の開始時刻として扱われます。下の段落）。確認の差し戻しで、時刻を決めた工程にもう一度入るときは、時刻を待たずに動きます。

**決めた時刻まで開始を待たせたいときに使います。** **動き始めたあとの時間は制限しません**（実行の制限時間は、Agent の契約の実行上限で決まります）。**サイクルにはこの設定がありません。** サイクルで時刻を決めるのは、巡回の周期です。

**最初の有効な工程の時刻は、案件の開始時刻になります**（**有効な時間トリガーが無いとき**）。そこに時刻を置くだけでも、時間で始められます。**この始め方でも、時間トリガーと同じく、案件を始めるときに設定値は渡せません**（[ワークフローを始める](#%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B)）。

画面上の場所 編集 ＞ 中央の図で工程を選び、右の「工程の設定」＞「起動条件」

## Webhook で動かす（サイクル）

Webhook トリガーの登録の仕方は SaaS 版と同じです。**受けた呼び出しの扱いが違います。**

- **呼び出しをまとめません。** 受けた呼び出しは、同じ配置に 1 件ずつ順に渡します。呼び出しの回数と実行の回数は同じです
- 配置ごとの待ちは 20 件までです。超えると `429 queue_full` が返ります
- 受け付けてから 24 時間たっても起動できなかった呼び出しは、起動しません

**Webhook トリガーを削除・無効化したり、起動する配置を付け替えたり、配置の環境変数を変えたり、プロジェクトを一時停止したりすると、まだ起動していない呼び出しも無効になります**（削除の確認に「受付を待っている起動の要求も無効になります。」と出ます）。一時停止中に呼ぶと `409` で断られます。

## 同時に進められる数（ワークフロー）

**案件には、同時に進められる数に上限があります。** 数えるのは、実行中と確認待ちの案件の合計で、**3 件まで**です（[設定値リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/reference/settings-ref.md)）。

上限に達しているときに新しく始めようとすると、次のようになります。

- **手動（案件を開始）** — 断られます
- **外部 API** — 断られます（`429`）
- **決めた時刻（時間トリガーと、最初の有効な工程の時刻）** — **その回は見送られ、あとから取り戻されません**

**確認が滞ると、新しい案件が始まらなくなります。** 確認担当者と進め方は[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/review-guide.md)にあります。外部 API から始めるなら、断られた依頼を呼び出す側で持っておき、あとで送り直す仕組みが要ります。

## 時刻の指定とタイムゾーン

**時刻の指定には、選ぶだけで済む形が用意されています。** 周期（○分ごと）・毎時・毎日・平日・毎週から選べます。**cron 式を書く必要はありません。** 細かく指定したいときは「カスタム (cron)」を選びます。

**時刻には、タイムゾーンも指定します。** **保存する前に、意図したタイムゾーンかを確かめてください。**

画面上の場所 時刻を決める画面はいずれも同じ形で、プリセットと「タイムゾーン」を選びます。時間トリガー＝設定 ＞「トリガーと通知」／工程の時刻＝編集 ＞ 工程を選び、右の「工程の設定」＞「起動条件」／巡回の周期＝編集 ＞ Agent を選び、右の「工程の Agent」＞「起動条件」＞「巡回の周期」

## うまくいかなかったとき

**登録 Agent の工程は、終わり方ごとに次の決まった扱いで動きます（ワークフロー）。** 画面には、扱いを選ぶ設定はありません。

| 終わり方                                                              | 扱い                                                                             |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 完了・対象なしの省略                                                        | 次の工程へ進む                                                                        |
| 未完遂・停止                                                            | 自動ではやり直さず、確認依頼を作る（同じ工程への差し戻しを選べる）                                              |
| ルールにより実行不可・そのほかの省略                                                | 確認依頼を作る（外部の API で工程の「ルールにより実行できない場合」を「失敗として閉じる」にしてあると、ルールにより実行不可のときは案件が失敗で閉じる） |
| 失敗・時間切れ（何が起きたかが分かっていて、外部への効果が「**読み取りのみ**」か「**書き込み (再送しても同じ結果)**」） | **自動でやり直します。** やり直しの回数を使い切ると、**案件は失敗で閉じます**                                    |
| 失敗・時間切れ（外部への効果が「**書き込み (再送で重複しうる)**」）                             | 二重に書き込まないように、自動ではやり直さず、確認依頼を作る                                                 |
| 何が起きたか分からない終わり方                                                   | 外部への効果の種類にかかわらず、自動ではやり直さず、確認依頼を作る                                              |

- 自動でやり直すのは、プロジェクトの「工程ごとの再試行回数」と 2 回の、少ないほうの回数までです

- 「何が起きたか分からない終わり方」には、Agent のプロセスが異常に終わった、Pod が消えた、結果を受け取りきれなかった、**契約の実行上限で打ち切られた**（既定 900 秒）ときが入ります。実行上限による時間切れは、自動ではやり直しません

- **起動の前に実行ルールを読めなかったとき**（存在しない連携先を指す禁止操作があるときなど）は、少しおいて照合し直し、回数を使い切ると確認依頼を作ります

## 止める・再開する

SaaS 版と同じく、プロジェクトの一時停止で、新しく始まる実行をすべて止められます。マーケットプレイス版では、次の止め方が加わります。

| 止めたいもの            | 止め方                                                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 動いている案件（ワークフロー）   | 案件の画面の「**案件を中断する**」（オーナー・運用担当と組織の運用の役割の人と、その案件を始めた本人）。[案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md#%E6%A1%88%E4%BB%B6%E3%82%92%E4%B8%AD%E6%96%AD%E3%81%99%E3%82%8B) |
| 動いているサイクルの 1 回の実行 | その実行の実行記録の「**停止する**」（オーナー・運用担当と組織の運用の役割の人）                                                                                                                                                                                   |

**管理者がプロジェクトを止めたときと、実行する利用者のアカウントが停止されたときは、次のとおりです。**

| 起きたこと                                    | 動き                                                                                                | 戻し方                        |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------- |
| 管理者がプロジェクトを止めた（管理コンソールの「AIエージェント一覧（横断）」） | 新しい案件は始まらず、巡回も止まります。画面には「管理者が停止しているため、この操作はできません」と出ます（外部 API では 409 `admin_stopped`）              | 管理者に再開を頼みます                |
| 実行する利用者（プロジェクトの持ち主）のアカウントを、管理者が停止した      | 案件を始める・再開するのが断られます。画面には「実行する利用者のアカウントが停止されているため、実行できません」と出ます（外部 API では 409 `principal_suspended`） | 管理者に、持ち主の変更か、利用の停止の解除を頼みます |

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

- **時間トリガーや Webhook トリガーでも、案件の設定を入れられると思う。** 開始のときに入れられるのは「案件を開始」と、外部 API の実行の開始（`config`）だけです。時間トリガーと Webhook トリガーでは、工程の設定の値で動きます。確認待ちの案件の設定は、画面でも外部 API でも直せます（オーナーだけ）
- **時間トリガーの時刻には必ず始まると思う。** 必須の値が足りない、同時に進められる数（3 件）に達している、などのときは、その回は始まらず、取り戻されません
- **サイクルの Webhook はまとめて 1 回になると思う。** マーケットプレイス版では、1 件ずつ順に動きます
- **期限で確認が進むと思う。** 進みません（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/review-guide.md#%E6%9C%9F%E9%99%90%E3%81%A7%E3%81%AF%E6%B1%BA%E3%81%BE%E3%82%89%E3%81%AA%E3%81%84)）
- **メールで起動できると思う。** 起動は、時間・手動・Webhook などで行います

## 次に読むもの

- [案件ガイド](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/review-guide.md) — 期限と外部条件待ち
- [記録ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/record-guide.md) — 結果の読み方
