# 連携ガイド

**Agent が外部のサービスに手を届かせるための設定**と、**出来事を人に知らせるための設定**を扱います。

Agent に何を持たせるかは[設計ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md)、どの操作まで許すかは[実行ルールガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/control-guide.md)で扱います。

**画面上の場所がある節では**、そこで決めたことを**どこで設定・確認するか**を終わりに書いてあります。

## 連携先は、このプロジェクトがつなぐ先

**Agent は、ゴールに書くだけでは、認証が要る外部サービスに手が届きません。** そのサービスを**連携先**として追加し、認証しておく必要があります。

**連携先には 2 種類あります。** **外部サービス**と、**エージェント連携**です。追加のしかたと認証は同じで、**どちらも基本ルールでは止まりません**。止めたいときは禁止操作として名指ししますが、**指定の仕方が種別で違います**（[実行ルールガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/control-guide.md)）。

**認証はプロジェクトに紐づきます。** 設定画面にある**個人の接続とは別**に保存されます。あなたが個人で認証していても、**プロジェクトの連携先として認証し直します**。

**追加も認証も、オーナーだけが行えます。** メンバーは変更できません（[誰が何を決められるか](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/concepts/roles.md)）。

**連携先から外すときは確認が出ます。** 外すと、このプロジェクトの Agent はその連携先を使えなくなります。接続（認証）は解除されません。

**候補を増やすことはできません。** 選べるのは**用意された候補**の中からだけです。使いたいサービスが候補に無いときは、システム管理者に相談してください。候補は、プロジェクトの持ち主（実行がその人の名前で動く 1 人）の組織・職種で絞られます。ほかのオーナーの組織・職種は見ません。MCP サーバーが使える組織・職種を限られているときは、持ち主が当てはまらなければ候補に出ず、保存でも断られます。すでに付けていた接続は、消えずに見えなくなります。

認証のしかたはサービスによって 2 通りあります。**画面の案内に従って認証するもの**と、**トークンを入力するもの**です。MCP サーバーに「接続できるアカウントのドメイン」が決められているときは、そのドメインの確認済みメールのアカウントでしか接続できず、トークンを貼る接続もできません。

**認証状態は画面で確認できます。**「認証済み」「再認証が必要」「未接続」が並ぶので、**動かす前に「再認証が必要」が残っていないか**を見てください。**「状態を取得できませんでした」と出ることもあります。** これは**未接続とは違い、状態が分からないだけ**なので、時間をおいて見直してください。

**「認証済み」は、これからの実行が成功することの保証ではありません。** 実行時の権限は、そのときに確かめられます。**いつ使われたかは、認証状態とは別の欄（利用実績）に出ます。**

画面上の場所 設定 タブ ＞「連携先(MCP, A2A)」＞「連携先を追加」。認証と状態も同じ場所で確認します

## 共通の記録先にする

**サイクルで段階をつなぐには、共通の記録先が必要です**（[設計ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md)）。その記録先として使う連携先に、「**共通の記録先にする**」を付けます。定義の変更に承認を要るテナントでは、この切り替えも承認されたあとから使われます（[下書きを確かめて反映する](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md#%E4%B8%8B%E6%9B%B8%E3%81%8D%E3%82%92%E7%A2%BA%E3%81%8B%E3%82%81%E3%81%A6%E5%8F%8D%E6%98%A0%E3%81%99%E3%82%8B)）。

**複数の連携先に付けられます。**

**ただし、付けただけでは何も起きません。** これは**目印**で、次のことは**起きません**。

- **読み書きは始まりません。** 何をどう読み書きするかは、**各 Agent のゴール（指示）に書きます**
- **権限は増えません。** 付けても、認証で許された範囲を超えて操作できるようになることはありません
- **重複や競合は防がれません。** 同じ対象を複数の Agent が同時に扱わないようにするのは、**目印の付け替えと各 Agent のゴール**で表します（[設計ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md)）

**付ける意味は、チームの中で「ここを共通の記録先にする」と決めたことを示すところにあります。** Agent のゴールを書く人が、どこを読み書きすればよいか分かる状態にするための指定です。

画面上の場所 設定 タブ ＞「連携先(MCP, A2A)」＞ 対象の連携先 ＞「共通の記録先」の切り替え

## 使う前に人に確かめさせる（接続の確認）

**連携先ごとに、Agent が使う前に人の確認を求められます。** 連携先の名前の下の「**接続時の確認**」を「**確認しない**」（既定）・「**初回のみ確認**」・「**毎回確認**」から選び、「**待ちの上限（分）**」（1〜1440 分。既定は 60 分）を決めます。「確認しない」の間は、待ちの上限は選べません。**エージェント連携（A2A）の連携先には設定できません。** 変えられるのはオーナーだけです。定義の変更に承認を要るテナントでは、この設定の変更も、承認されたあとから使われます（[下書きを確かめて反映する](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md#%E4%B8%8B%E6%9B%B8%E3%81%8D%E3%82%92%E7%A2%BA%E3%81%8B%E3%82%81%E3%81%A6%E5%8F%8D%E6%98%A0%E3%81%99%E3%82%8B)）。

**「接続時の確認」を設定した連携先を Agent が使おうとすると、そこで実行を止めて、確認依頼を立てます**（**接続の確認**）。ワークフローの工程でも、サイクルの巡回でも同じです。止めた実行の結果は「失敗 (Agent の報告)」で、理由は「**接続の確認のため停止**」と出ますが、**失敗には数えません**（[実行結果リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/results-ref.md)）。確認依頼には、使おうとした連携先と、Agent が申告した目的が出ます。

**接続の確認で決められるのは、承認するか却下するかだけです。** 差し戻しと期限の延長はできません（「対応待ち」の一括操作でも対象になりません）。担当者は、「Agent が実行」の工程の結果から作られる確認依頼と同じく、原則として、その時点のオーナー全員です（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md#%E6%B1%BA%E3%82%81%E3%82%89%E3%82%8C%E3%82%8B%E3%81%AE%E3%81%AF%E6%8C%87%E5%AE%9A%E3%81%97%E3%81%9F%E4%BA%BA%E3%81%A0%E3%81%91)）。

- **承認すると、この連携先を使って、止めた工程・巡回を起動し直します。** ワークフローは同じ工程の Agent を新しい試行として動かし、サイクルは同じ配置の巡回を 1 回だけ動かします。サイクルの起動し直しは巡回の再実行と同じ枠を使うので、止めた実行の巡回の再実行をもう求めていれば、起動し直しません。起動し直した実行の実行記録には「**接続の確認の承認で再度起動した実行です**」と出ます
- **承認しても起動し直さないことがあります。** ワークフローでは、待つあいだに配置が外れていれば、却下と同じ扱いになります。ワークフローの実行が閉じていたり、工程が先へ進んでいたりすれば、何もしません。サイクルでは、配置が外れていたときなど、巡回の再実行ができないときは何もしません
- **却下すると、起動し直しません。** ワークフローでは、止めた実行を、その工程の「Agent の報告による失敗のとき」の設定に従って扱います（[設計ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-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%E3%81%A9%E3%81%86%E3%81%99%E3%82%8B%E3%81%8B%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC)）。サイクルでは何もしません
- **待ちの上限を過ぎると、却下として決まります。** 起動し直しません。実行記録の「確認」には「**期限切れ**」と出ます

**承認が効く範囲は、接続時の確認の選び方で違います。** 「初回のみ確認」は、ワークフローでは、同じワークフローの実行の後の工程にも効きます。「毎回確認」は、起動し直した実行と、そこからさらに確認を求めて起動し直した実行だけに効きます。サイクルにはワークフローの実行の区切りが無いので、どちらを選んでも「毎回確認」と同じです。

**依頼は、確認担当者（と期間中の代理人）に、製品の中の通知とメールで届きます。** サイクルでも届きます。メールに返信して承認することもできます（後の[節](#%E7%A2%BA%E8%AA%8D%E3%81%AE%E9%80%9A%E7%9F%A5%E3%81%AF%E6%8B%85%E5%BD%93%E8%80%85%E3%81%B8%E8%87%AA%E5%8B%95%E3%81%A7%E5%B1%8A%E3%81%8F)）。**待ちの上限を過ぎたことは、確認担当者（と期間中の代理人）に、製品の中の通知とメールで届きます。** 確認はもう閉じているので、そのメールからは決められません。期限超過時の連絡先には届きません。

画面上の場所 設定 タブ ＞「連携先(MCP, A2A)」＞ 対象の連携先の名前の下 ＞「接続時の確認」「待ちの上限（分）」。決めるのは、左の「受信トレイ」＞「確認依頼」＞ 対象を選ぶ ＞「承認する」「却下する」

## 確認の通知は、担当者へ自動で届く

**確認の依頼と、確認期限の超過の知らせは、設定しなくても確認担当者へ届きます。** 製品の中の通知と、**担当者ごとの専用リンクが付いたメール**の両方です（期間中の代理人にも、同じく製品の中の通知とメールで届きます。期限で閉じた接続の確認の知らせのメールには、専用リンクも返信の案内も付きません）。止めたいときは、出来事ごとにオフにします（次の節）。担当者の決め方は[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md)で扱います。

**確認期限の超過はワークフローで起きるものです。** 確認の依頼も、サイクルでは接続の確認のときだけ届きます。サイクルには確認工程を置けないためです（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md)）。接続の確認の知らせ方は、前の[節](#%E4%BD%BF%E3%81%86%E5%89%8D%E3%81%AB%E4%BA%BA%E3%81%AB%E7%A2%BA%E3%81%8B%E3%82%81%E3%81%95%E3%81%9B%E3%82%8B%E6%8E%A5%E7%B6%9A%E3%81%AE%E7%A2%BA%E8%AA%8D)にあります。

**期限超過の知らせが届くのは、「通知して待機する」を選んだときです。** 期限後に自動で進める・差し戻す・却下する設定では、**処理が成り立てば知らせずに済みます**（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md)）。接続の確認は、待ちの上限を過ぎると却下として決まり、確認担当者（と期間中の代理人）に、製品の中の通知とメールが届きます。

**届いた通知から、確認の画面へ進めます。** 製品の中の通知も、担当者へのメールのリンクも、左の「**受信トレイ**」の「確認依頼」の該当する依頼を開きます。そこで決めます（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md)）。

**担当者へのメールの専用リンクが、決めるときにも有効なら、メール経由として記録されます。** リンクの期限が切れていても、**確認担当者か期間中の代理人なら、画面からそのまま決められます。** ただし**その決定はメール経由にはなりません。**

**メールには、決定ごとに何が起きるか（「決定後」）と、期限を過ぎたときの動きも書かれます。** 担当者がメールだけを見て、決めたあとの動きが分かるようにするためです。

**メールに返信して承認することもできます。** メールに「このメールに「承認」とだけ返信すると承認できます」と書かれているときは、本文の先頭の行に「承認」か「APPROVE」とだけ書いて返信すると、承認になります。却下・差し戻しは理由が要るので、メールのボタンから開く画面で行います。

- **返信できるのは、そのメールを受け取った確認担当者か期間中の代理人の本人です。** 送り主がその人の登録メールアドレスで、送信元の認証（DMARC）に合格している必要があります
- **返信が効くのは、届いた中で最新のメールだけです。** 確認期限の超過の知らせのメールにも返信の案内が付き（期限で閉じた接続の確認の知らせを除く）、それが届くと、前のメールへの返信は効かなくなります
- **返信で決められるのは、そのメールを送ってから 7 日と、確認期限の早いほうまでです。** 確認期限を過ぎたあとの知らせのメールなら、送ってから 7 日です。接続の確認は、待ちの上限を過ぎると決まってしまうので、上限までです
- **次の工程の候補がある確認では、返信で承認できません。** メールにも返信の案内は出ません。画面で次の工程を選びます
- 送り主が違うとき、返信で決められる期限を過ぎたとき、ほかの人が先に決めたとき、確認の内容が変わったときは、承認になりません。先頭の行が「承認」「APPROVE」でない返信も、決定にはなりません

返信で承認すると、記録 (証跡) のチャネルは `mail_reply` になります（[記録リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/events-ref.md)）。返信で承認できるのは、メールの機能が有効な環境だけです。

**環境によっては、メールが送られないことがあります。** メールの配送が設定されていない環境です。その場合は、確認依頼の履歴に「**通知を送信できませんでした**」と残ります（後の[節](#%E9%80%81%E3%82%8C%E3%81%9F%E3%81%8B%E3%81%A9%E3%81%86%E3%81%8B%E3%82%92%E7%A2%BA%E3%81%8B%E3%82%81%E3%82%8B)）。

画面上の場所 左の「受信トレイ」＞「確認依頼」＞ 対象を選ぶ。届いた通知やメールのリンクからも、同じ画面が開きます

## 通知を止める

**通知は、出来事ごとにオン・オフを切り替えられます。** 出来事は**確認の依頼**・**確認期限の催促**・**確認期限の超過**・**実行の締め切り超過**・**実行の停滞**の 5 つで、どれも既定はオンです。**実行の完了と、巡回の連続の失敗は、別の知らせです**（次の節）。

**オフにすると、製品の中の通知もメールも送られません。** プロジェクトの設定では、製品の中だけ・メールだけの切り替えはありません。**自分の分は、個人の設定の「通知」で、出来事ごとにプッシュ通知とメールを止められます**（製品の中の一覧と履歴は残ります）。確認期限の超過をオフにすると、期限超過時の連絡先にも届きません。

**実行の締め切り超過と実行の停滞は、ワークフローの実行が締め切りを過ぎたとき、「停滞とみなす時間」を過ぎても進まないときに届きます。** 同じ締め切り・同じ停滞につき 1 回だけで、**実行は止まりません**（[記録ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/record-guide.md#%E7%B7%A0%E3%82%81%E5%88%87%E3%82%8A%E3%81%A8%E5%81%9C%E6%BB%9E%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC)）。

**製品の中の通知とメールの送り先は出来事で決まっていて、足すことはできません。** 確認の依頼は確認担当者（と期間中の代理人）に、確認期限の催促は、確認期限が近づいてもまだ決まっていないときに確認担当者（と期間中の代理人）に（最後の 1 回は期限超過時の連絡先にも）、確認期限の超過は確認担当者（と期間中の代理人）と期限超過時の連絡先に（接続の確認の期限切れは確認担当者と期間中の代理人にだけ）、実行の締め切り超過と実行の停滞はプロジェクトのオーナー全員に届きます。ほかのアドレスを加える設定はありません。ほかの仕組みへは、外部へ送信する Webhook で送れます（次の段落）。

**切り替えはオーナーだけが行えます。** この 5 つの切り替えの欄はワークフローにだけ出ます。そのため、サイクルの接続の確認の知らせは止められません。同じ欄で、期限超過時の連絡先の既定も決められます（[確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md#%E6%9C%9F%E9%99%90%E3%82%92%E9%81%8E%E3%81%8E%E3%81%9F%E3%82%89%E3%81%A9%E3%81%86%E3%81%99%E3%82%8B%E3%81%8B)）。

**出来事を、外の仕組みの HTTPS の URL へ送れます（外部へ送信する Webhook）。** 送れる出来事は、上の 5 つと「実行の終了」（ワークフローの実行が閉じたとき。失敗で閉じたときも送ります）です。1 つの Webhook に出来事を 1 つ選び、プロジェクトごとに 20 件まで登録できます。送る中身は、出来事・プロジェクト・実行・確認依頼の ID と時刻・リンクだけです（「実行の終了」は閉じたときの状態も）。署名の秘密鍵を入れると、`X-Agentic-Star-Signature` ヘッダに HMAC-SHA256 の署名が付きます。届かなかったときは、3 回まで送り直します。登録・変更はオーナーだけです。

画面上の場所 設定 タブ ＞「トリガーと通知」＞「通知」＞「確認の依頼」「確認期限の催促」「確認期限の超過」「実行の締め切り超過」「実行の停滞」の切り替えと「期限超過時の連絡先（既定）」。外部へ送信する Webhook は 設定 タブ ＞「トリガーと通知」＞「外部へ送信するWebhook」

## 巡回が続けて失敗したら、オーナーへ届く

**サイクルの同じ配置の巡回が、設定 タブに出る回数続けて失敗すると、オーナー全員と、その配置の Agent の持ち主（メンバーのとき）に、メールとプッシュ通知で届きます。** 始まった巡回は、直近のその回数の実行が「失敗 (Agent の報告)」「失敗」「時間切れ」「失敗 (停止)」「ルールにより実行不可」のどれかのときです（接続の確認で止めた巡回は数えません）。**巡回を始められなかったときは、それが同じ回数続いたときに届きます。** 始まった巡回の失敗と、始められなかった回は、合わせて数えません。回数は、設定 タブに出る「連続して失敗したらオーナーへ通知する (メール・Push)」の値で、3 回です（画面からは変えられません）。

**同じ続きの失敗では 1 回だけ届きます。** 一度成功してからまた続けて失敗すると、もう一度届きます。知らせには、配置の Agent の名前と回数と、その配置の直近の実行記録（無ければ実行履歴）へのリンクが入ります。

プロジェクトの設定では切り替えられません。**自分の分のメールとプッシュ通知は、個人の設定の「通知」で、出来事「連続した失敗」を止められます。** 管理者が通知を止めているときは届きません。

## 実行の結果を、自分で受け取る

**メンバーは、プロジェクトの実行が完了したときの知らせを、自分の分だけ受け取れます。** 既定はオフです。ワークフローでもサイクルでも使えます。

**ワークフローは、実行が完了で閉じたときに 1 回届きます。** 失敗で閉じたときは届きません。**サイクルは、巡回が完了で終わったときに届きます。ただし同じ配置では、時刻の 1 時間ごとの区切り（例: 10 時台）に 1 回まで**です。メールとプッシュ通知で届き、名前・終わった時刻・出力の最初の段落と、記録へのリンクが入ります。どちらかの手段だけを止めるときは、個人の設定の「通知」で、出来事「結果の通知」の手段を選びます。

メンバーでなくなると届きません。

画面上の場所 設定 タブ ＞「トリガーと通知」＞「結果の通知」の切り替え

## 送れたかどうかを確かめる

**確認の知らせのメールを送ろうとした結果は、その確認依頼の履歴に残ります。** ただし**相手に届いたことの確認ではありません。** 主に残るのは「**通知を送信待ちに登録しました**」「**通知を送信しました**」「**通知を送信できませんでした**」です。

**宛先が分からない、受け取らない設定になっている——といった理由で送れなかった場合も、ここに残ります。** 届かないときはまずこれを見てください。

画面上の場所 左の「受信トレイ」＞「確認依頼」＞ 対象を選ぶ ＞「履歴」

## コピーしたときの連携先

**連携先の一覧は引き継がれますが、接続（認証）は引き継がれません。** ほかのプロジェクトからコピーした場合、**コピーしたプロジェクトで接続し直します**。画面にもそう表示されます。

**認証が権限を伴うためです。** コピーした人が、元のプロジェクトの認証をそのまま使えてしまうと困るので、引き継がれません。

**「共通の記録先」の指定と、「接続時の確認」「待ちの上限（分）」も引き継がれます。**

**通知のオン・オフも引き継がれません。** コピーしたプロジェクトでは、5 つの出来事がどれもオンで始まります。**オフにしていたものは設定し直してください**。期限超過時の連絡先の既定も引き継がれません。

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

ここまでの節をまたいで、区別しておく点をまとめます。

- **「共通の記録先にする」を付けたら読み書きが始まると思う。** **目印だけです。** 何をどう読み書きするかは各 Agent のゴールに書きます。**権限も増えません**
- **通知を設定すれば何でも届くと思う。** 出来事の通知は「**確認の依頼**」「**確認期限の催促**」「**確認期限の超過**」「**実行の締め切り超過**」「**実行の停滞**」**の 5 つ**で、ほかに、自分で受け取る「**結果の通知**」と、オーナーに届く「**巡回の連続の失敗**」があります。実行の開始は知らせられません。ワークフローの実行の失敗も、製品の中の通知とメールでは知らせられないので、「対応待ち」で見ます（外の仕組みへは、外部へ送信する Webhook の「実行の終了」で送れます）
- **担当者以外のアドレスにも送れると思う。** **確認の依頼と確認期限の超過は、設定しなくても担当者へ届きます。** 一方で、**通知とメールの送り先を足す設定はありません**（外の仕組みへは、外部へ送信する Webhook で送れます）。できるのは出来事ごとのオン・オフと、期限超過時の連絡先を決めることだけです
- **メールに何を書いて返信しても決められると思う。** **返信で決められるのは承認だけです。** 本文の先頭の行に「承認」か「APPROVE」とだけ書きます。却下・差し戻しは画面で行います
- **接続の確認で止めた実行を失敗だと思う。** **失敗には数えません。** 人の確認を待っているだけで、承認すれば起動し直します。却下したときと、待ちの上限を過ぎたときは起動し直しません
- **記録に「通知を送信しました」と出れば相手に届いたと思う。** **届いたことの確認ではありません。** 送ろうとした結果が残るだけです
- **個人の接続をそのまま使えると思う。** **プロジェクトの連携先は、個人の接続とは別に認証します**
- **使いたいサービスを自分で足せると思う。** **候補は増やせません。** 用意された中から選びます

## 次に読むもの

- [設計ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md) — 共通の記録先で段階をつなぐ組み立て方
- [確認ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/review-guide.md) — 誰に確認を頼み、どう決めさせるか
- [実行ルールガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/control-guide.md) — 連携先に対してどの操作まで許すか
- [誰が何を決められるか](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/concepts/roles.md) — 連携先を変えられるのは誰か
- [設定値リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/reference/settings-ref.md) — 連携先の数の上限
