起動ガイド
起動の考え方は SaaS 版と同じです(起動ガイド)。このページは、マーケットプレイス版で違う点をまとめます。
型ごとに使えるもの
| ワークフロー | サイクル | |
|---|---|---|
| 手動で始める | 「案件を開始」(プロジェクトの参加者と組織の運用の役割の人) | できません |
| 決めた時刻に始める | 時間トリガー。開始のときに設定値を渡せません | 巡回の周期を配置ごとに決めます |
| 外部から始める | 外部 API(サービスアカウントのトークンか、プロジェクトの参加者と組織の運用の役割の人のアプリケーションのトークン)。実行の開始では設定値を渡せます。Webhook トリガーの呼び出しでは渡せません。オーナーが「外部公開(A2A・MCP)」で公開すると、管理者が受け口を開けた環境では、外部の Agent(A2A)や MCP のクライアントからも依頼文を付けて始められます | 外部 API で Webhook トリガーを呼びます(先に登録) |
| メールで始める | できません | できません |
自動の起動を作る・有効にするには
決めた時刻・Webhook・巡回で自動で始まる起動を作る・有効にするには、管理者が機能の許可で「定期実行の作成」を許している必要があります。 許されていない人は、次の操作を断られます: トリガー(時間・Webhook)を作る・有効にする、工程の時刻(ワークフロー)を入れる・変える、巡回を有効にする・有効な巡回の周期を変える、これらを含む定義をファイルから取り込む・社内のひな形から作る。すでにある起動は止まりません。 止める・外す操作、工程の時刻を同じ値のまま保存する操作、有効なトリガーの設定を有効なまま変える操作は、許可が無くてもできます。有効な巡回の周期を変えるのは断られます。
自動で動くものは、プロジェクトの区画の上部の「自動実行」に一覧で並びます。 参加しているプロジェクトのトリガー・先頭の工程の時刻・巡回が、種類・所属・状態・次の起動とともに出ます。工程の時刻は、ワークフローの最初の有効な工程の 1 つだけが並びます(その工程に時刻が無ければ出ません)。有効な時間トリガーがあるプロジェクトでは、その時刻では始まらないので「無効」と出ます。作る・変える・止めるは、名前から開く各画面で行います。
画面上の場所 許可は管理コンソールの「接続先と使える範囲」>「機能の許可」の「定期実行の作成」(システム管理者)。一覧はプロジェクトの区画の上部の「自動実行」
ワークフローを始める
画面から始めるときは「案件を開始」を使います。 配置ごとの設定値・連携先・指示ファイルを、その案件のために入れられます(案件ガイド)。
外部 API の実行の開始では、「案件を開始」と同じ設定値・連携先・入力ファイルを開始のときに渡せます(config。システム連携 API リファレンス — 実行の開始)。時間トリガーと Webhook トリガーの呼び出しで始めた案件には、開始のときに設定値を渡せません。 そのときの各 Agent の設定値は、契約の標準値に工程の設定を重ねたものになります。外部 API で payload を付けると、その内容は依頼として最初の工程の Agent に渡ります。設定値にはなりません。依頼を使うかどうかは Agent の作りによります(ワークフローガイド — 外から始めた run の依頼)。
必須の設定値・連携先・入力ファイルが工程の設定(外部 API で config を渡したときは、それを重ねたもの)でそろっていないと、その案件は始まりません。
- 時間トリガーでは、その回は始まらず、次の予定の時刻へ進みます
- 外部 API では、エラーが返ります
時間トリガー・Webhook トリガーや、config を渡さない外部 API で動かすなら、必須の値はすべて工程の設定に入れておいてください(エージェントガイド)。
外部 API は、次の 2 つのトークンで呼べます。
- サービスアカウントのトークン(システム連携): 管理コンソールで作ります。サービスアカウントは、この環境のすべてのプロジェクトを対象に、許された操作を行えます(システム連携 API リファレンス)
- アプリケーションのトークン: 利用者が外部ツールでログインして得ます。管理者が外部ツールでのログインの入口を開けた環境でだけ使えます。案件を始める・Webhook トリガーを呼ぶのは、そのプロジェクトの参加者(オーナー・運用担当・メンバー)と組織の運用の役割の人です(ユーザー API リファレンス(プロジェクト))。メイン画面にログインしたときのトークンでは呼べません
サイクルを回す
巡回の周期の決め方は SaaS 版と同じです。マーケットプレイス版では、次の点が決まっています。
- 同じ配置が実行中のあいだに来た回は見送ります。 積み上げて、あとからまとめて動かすことはしません
- 予定から 5 分を過ぎた回は、見送りとして 1 件だけ残し、次の予定へ進みます。 環境が止まっていた間の回を、あとから全部動かすことはしません
- 同じ配置の前の実行が終わってから 60 秒は、次の巡回を見送ります。 Webhook の呼び出しは、60 秒待ってから起動します
- 同じ配置に起動を待っている Webhook の呼び出しがあるあいだも、巡回は見送ります
Agent が処理のあとに終了しないと、その配置の次の回がずっと見送られます。 見送りが続くときは、Agent の開発者に終了の作りを確かめてもらってください(はじめてのエージェント)。
工程ごとの時刻(ワークフロー)
ワークフローでは、Agent を置く工程に動く時刻を持たせられます。 選ぶのは 2 つです。
- 前の工程の完了後すぐ — 既定です。前の工程が終わり次第動きます
- 所定の時刻に — 前の工程が終わったあと、その時刻まで待ってから動きます
時刻を待つのは、2 つ目以降の工程です。 最初の有効な工程は、案件が始まるとすぐ動きます(その時刻は、案件の開始時刻として扱われます。下の段落)。確認の差し戻しで、時刻を決めた工程にもう一度入るときは、時刻を待たずに動きます。
決めた時刻まで開始を待たせたいときに使います。 動き始めたあとの時間は制限しません(実行の制限時間は、Agent の契約の実行上限で決まります)。サイクルにはこの設定がありません。 サイクルで時刻を決めるのは、巡回の周期です。
最初の有効な工程の時刻は、案件の開始時刻になります(有効な時間トリガーが無いとき)。そこに時刻を置くだけでも、時間で始められます。この始め方でも、時間トリガーと同じく、案件を始めるときに設定値は渡せません(ワークフローを始める)。
画面上の場所 編集 > 中央の図で工程を選び、右の「工程の設定」>「起動条件」
Webhook で動かす(サイクル)
Webhook トリガーの登録の仕方は SaaS 版と同じです。受けた呼び出しの扱いが違います。
- 呼び出しをまとめません。 受けた呼び出しは、同じ配置に 1 件ずつ順に渡します。呼び出しの回数と実行の回数は同じです
- 配置ごとの待ちは 20 件までです。超えると
429 queue_fullが返ります - 受け付けてから 24 時間たっても起動できなかった呼び出しは、起動しません
Webhook トリガーを削除・無効化したり、起動する配置を付け替えたり、配置の環境変数を変えたり、プロジェクトを一時停止したりすると、まだ起動していない呼び出しも無効になります(削除の確認に「受付を待っている起動の要求も無効になります。」と出ます)。一時停止中に呼ぶと 409 で断られます。
同時に進められる数(ワークフロー)
案件には、同時に進められる数に上限があります。 数えるのは、実行中と確認待ちの案件の合計で、3 件までです(設定値リファレンス)。
上限に達しているときに新しく始めようとすると、次のようになります。
- 手動(案件を開始) — 断られます
- 外部 API — 断られます(
429) - 決めた時刻(時間トリガーと、最初の有効な工程の時刻) — その回は見送られ、あとから取り戻されません
確認が滞ると、新しい案件が始まらなくなります。 確認担当者と進め方は確認ガイドにあります。外部 API から始めるなら、断られた依頼を呼び出す側で持っておき、あとで送り直す仕組みが要ります。
時刻の指定とタイムゾーン
時刻の指定には、選ぶだけで済む形が用意されています。 周期(○分ごと)・毎時・毎日・平日・毎週から選べます。cron 式を書く必要はありません。 細かく指定したいときは「カスタム (cron)」を選びます。
時刻には、タイムゾーンも指定します。 保存する前に、意図したタイムゾーンかを確かめてください。
画面上の場所 時刻を決める画面はいずれも同じ形で、プリセットと「タイムゾーン」を選びます。時間トリガー=設定 >「トリガーと通知」/工程の時刻=編集 > 工程を選び、右の「工程の設定」>「起動条件」/巡回の周期=編集 > Agent を選び、右の「工程の Agent」>「起動条件」>「巡回の周期」
うまくいかなかったとき
登録 Agent の工程は、終わり方ごとに次の決まった扱いで動きます(ワークフロー)。 画面には、扱いを選ぶ設定はありません。
| 終わり方 | 扱い |
|---|---|
| 完了・対象なしの省略 | 次の工程へ進む |
| 未完遂・停止 | 自動ではやり直さず、確認依頼を作る(同じ工程への差し戻しを選べる) |
| ルールにより実行不可・そのほかの省略 | 確認依頼を作る(外部の API で工程の「ルールにより実行できない場合」を「失敗として閉じる」にしてあると、ルールにより実行不可のときは案件が失敗で閉じる) |
| 失敗・時間切れ(何が起きたかが分かっていて、外部への効果が「読み取りのみ」か「書き込み (再送しても同じ結果)」) | 自動でやり直します。 やり直しの回数を使い切ると、案件は失敗で閉じます |
| 失敗・時間切れ(外部への効果が「書き込み (再送で重複しうる)」) | 二重に書き込まないように、自動ではやり直さず、確認依頼を作る |
| 何が起きたか分からない終わり方 | 外部への効果の種類にかかわらず、自動ではやり直さず、確認依頼を作る |
-
自動でやり直すのは、プロジェクトの「工程ごとの再試行回数」と 2 回の、少ないほうの回数までです
-
「何が起きたか分からない終わり方」には、Agent のプロセスが異常に終わった、Pod が消えた、結果を受け取りきれなかった、契約の実行上限で打ち切られた(既定 900 秒)ときが入ります。実行上限による時間切れは、自動ではやり直しません
-
起動の前に実行ルールを読めなかったとき(存在しない連携先を指す禁止操作があるときなど)は、少しおいて照合し直し、回数を使い切ると確認依頼を作ります
止める・再開する
SaaS 版と同じく、プロジェクトの一時停止で、新しく始まる実行をすべて止められます。マーケットプレイス版では、次の止め方が加わります。
| 止めたいもの | 止め方 |
|---|---|
| 動いている案件(ワークフロー) | 案件の画面の「案件を中断する」(オーナー・運用担当と組織の運用の役割の人と、その案件を始めた本人)。案件ガイド |
| 動いているサイクルの 1 回の実行 | その実行の実行記録の「停止する」(オーナー・運用担当と組織の運用の役割の人) |
管理者がプロジェクトを止めたときと、実行する利用者のアカウントが停止されたときは、次のとおりです。
| 起きたこと | 動き | 戻し方 |
|---|---|---|
| 管理者がプロジェクトを止めた(管理コンソールの「AIエージェント一覧(横断)」) | 新しい案件は始まらず、巡回も止まります。画面には「管理者が停止しているため、この操作はできません」と出ます(外部 API では 409 admin_stopped) | 管理者に再開を頼みます |
| 実行する利用者(プロジェクトの持ち主)のアカウントを、管理者が停止した | 案件を始める・再開するのが断られます。画面には「実行する利用者のアカウントが停止されているため、実行できません」と出ます(外部 API では 409 principal_suspended) | 管理者に、持ち主の変更か、利用の停止の解除を頼みます |
取り違えやすいところ
- 時間トリガーや Webhook トリガーでも、案件の設定を入れられると思う。 開始のときに入れられるのは「案件を開始」と、外部 API の実行の開始(
config)だけです。時間トリガーと Webhook トリガーでは、工程の設定の値で動きます。確認待ちの案件の設定は、画面でも外部 API でも直せます(オーナーだけ) - 時間トリガーの時刻には必ず始まると思う。 必須の値が足りない、同時に進められる数(3 件)に達している、などのときは、その回は始まらず、取り戻されません
- サイクルの Webhook はまとめて 1 回になると思う。 マーケットプレイス版では、1 件ずつ順に動きます
- 期限で確認が進むと思う。 進みません(確認ガイド)
- メールで起動できると思う。 起動は、時間・手動・Webhook などで行います